API 参考: multiGetObjects

通过 32 字节十六进制对象 ID，在单个批量请求中检索多个 Sui 对象的链上详细信息和元数据。

使用此方法可将多个对象查询合并为单次网络调用，与逐个查询对象相比，可显著降低延迟。由于 multiGetObjects 是一项直接从全节点的本地状态提供服务的读取操作，因此它会立即执行，无需提交交易或消耗 gas。

• 类: SuiClient
• 包: @mysten/sui/client
• 操作类型: 读取操作（无需 gas，无需钱包签名）

---

概述

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

顺序与批量对比

顺序 getObject (N 次往返):
App ── getObject(A) ──► Fullnode ──► App ── getObject(B) ──► Fullnode

批量 multiGetObjects (1 次往返):
App ──────────── multiGetObjects([A, B, C]) ────────────► Fullnode
App ◄─────────── [ResultA, ResultB, ResultC] ─────────── Fullnode

签名

签名

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

参数

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

参数	类型	必需	描述
ids	string[]	是	由 32 字节十六进制对象 ID 组成的数组。
options	SuiObjectDataOptions	否	用于切换特定数据字段的配置标志。适用于所有请求的对象。

备注

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

---

返回值

返回一个解析为 SuiObjectResponse 对象数组的 Promise。

数组的顺序与请求中传递的 ids 顺序完全一致：

响应

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

---

使用示例

批量获取 NFT 元数据并显示属性

查询一组 NFT ID，以获取链上字段和图片 URL：

bulkFetch.js

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);
    }
});

为批量限制分块处理大型 ID 列表

由于大多数公共 RPC 节点对单次请求限制为 50 个项目，对于大型列表请使用分块辅助函数：

chunking.js

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...
}

---

最佳实践

按项目处理部分失败

与在出现错误时可能会停止整个批次的标准数据库查询不同，multiGetObjects 会针对每个 ID 返回结果。即使其中一个对象失败（例如被交易删除），批次中的其余项目仍会成功返回。请务必对返回数组中的每个项目检查 data 与 error。

依赖索引顺序保持

SDK 严格保留输入数组的索引顺序：

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

您可以依赖此顺序将结果直接映射回原始数据源。

---

另请参阅

• getObject: 检索单个链上对象的详细信息。
• getOwnedObjects: 列出特定地址拥有的所有对象。
• 如何获取对象数据: 在 Node.js 脚本中实现读取操作的分步教程。
• SuiClient 架构: SuiClient 及读取操作的概念概述。