跳到主要内容

API 参考：multiGetObjects

通过单次网络请求检索多个对象的详细信息。

类： SuiClient 方法类型： 读取操作，无需 gas

概述​

使用 multiGetObjects 比在循环中调用 getObject 效率高得多。它通过将多个查询合并为单个远程过程调用 (RPC)，从而降低了网络延迟。

签名​

client.multiGetObjects(input: MultiGetObjectsParams): Promise<SuiObjectResponse[]>

参数​

该方法接受一个包含以下属性的配置对象：

参数类型必填描述
idsstring[]是由 32 字节十六进制对象 ID 组成的数组。
optionsSuiObjectDataOptions否用于控制特定数据字段的配置标志。适用于 所有 请求的对象。
备注

大多数公共 RPC 节点通常限制每个请求最多 50 个 ID。对于更大的批次，您必须将数组拆分为多个块。

返回值​

返回一个 Promise，其解析结果为一个包含 SuiObjectResponse 对象的 数组。

该数组的顺序与请求中传入的 ids 顺序完全一致。

[
  {
    "data": { "objectId": "0xA...", "version": "1", ... }
  },
  {
    "error": { "code": "notExists", "object_id": "0xB..." }
  },
  {
    "data": { "objectId": "0xC...", "version": "5", ... }
  }
]

使用示例​

场景 A：批量获取元数据​

假设您有一组非同质化代币 (NFT) ID，并需要显示其名称。

const objectIds = ['0x123...', '0x456...', '0x789...'];

const results = await client.multiGetObjects({
    ids: objectIds,
    options: {
        showContent: true,
        showDisplay: true
    }
});

// 处理结果
results.forEach((result) => {
    if (result.data) {
        console.log("找到项目：", result.data.display?.data?.name);
    } else {
        console.warn("项目加载失败：", result.error);
    }
});

场景 B：通过分块处理大型列表​

由于每次请求的项数上限为 50 项（例如），对于大型列表，请使用分块辅助函数。

import { chunk } from 'lodash'; // 或您自己的辅助函数

const allIds = [/* ... 包含 200 个 ID 的数组 ... */];
const CHUNK_SIZE = 50;
const chunks = chunk(allIds, CHUNK_SIZE);

for (const batch of chunks) {
    const batchResults = await client.multiGetObjects({
        ids: batch,
        options: { showType: true }
    });
    // 处理 batchResults...
}

最佳实践​

1. 始终处理部分失败​

与标准数据库查询在出现错误时可能导致整个批处理中止不同，multiGetObjects 会为 每个 ID 返回结果。即使其中一个对象获取失败（例如已被删除），该批次中的其他对象仍会成功返回。您必须针对返回数组中的 每个项 检查 data 与 error。

2. 顺序保持​

SDK 保证输出数组的索引与输入数组的索引一致。

  • results[0] 对应 ids[0]。
  • results[1] 对应 ids[1]。

您可以依靠这一点将结果映射回原始数据源。