Saltar al contenido principal

Referencia API: multiGetObjects

Recupera detalles y metadatos en cadena de varios objetos Sui en una única solicitud por lotes mediante sus identificadores de objeto hexadecimales de 32 bytes.

Utiliza este método para combinar varias consultas de objetos en una única llamada de red, lo que reduce la latencia en comparación con la consulta de objetos de forma individual. Dado que multiGetObjects es una operación de lectura que se realiza directamente desde el estado local del nodo completo, se ejecuta de forma inmediata sin necesidad de enviar una transacción ni consumir gas.

  • Clase: SuiClient
  • Paquete: @mysten/sui/client
  • Tipo de operación: operación de lectura (sin gas, sin firma de billetera)

Descripción general​

La llamada a multiGetObjects resulta mucho más eficiente que llamar a getObject en un bucle. Reduce la latencia de red al combinar varias consultas de objetos en una única llamada a procedimiento remoto (RPC).

Comparación entre el modo secuencial y el modo por lotes
getObject secuencial (N idas y vueltas):
App ── getObject(A) ──► Fullnode ──► App ── getObject(B) ──► Fullnode

multiGetObjects por lotes (1 ida y vuelta):
App ──────────── multiGetObjects([A, B, C]) ────────────► Fullnode
App ◄─────────── [ResultA, ResultB, ResultC] ─────────── Fullnode

Firma​

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

Parámetros​

El método acepta un objeto de configuración con las siguientes propiedades:

ParámetroTipoRequeridoDescripción
idsstring[]SíUna matriz de identificadores de objeto hexadecimales de 32 bytes.
optionsSuiObjectDataOptionsNoBanderas de configuración para activar campos de datos específicos. Se aplica a todos los objetos solicitados.
nota

La mayoría de los nodos RPC públicos imponen un límite de, normalmente, 50 ID por solicitud. Para lotes más grandes, debes dividir tu matriz en fragmentos.

Valor de retorno​

Devuelve una Promise que se resuelve en una matriz de objetos SuiObjectResponse.

El orden de la matriz se corresponde exactamente con el orden de los identificadores pasados en la solicitud:

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

Ejemplos de uso​

Obtención masiva de metadatos de NFT y atributos de visualización​

Consulta una lista de identificadores de tokens no fungibles (NFT) para mostrar campos en la cadena y URL de imágenes:

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

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

// Procesar los resultados
results.forEach((result) => {
    if (result.data) {
        console.log("Elemento encontrado:", result.data.display?.data?.name);
    } else {
        console.warn("No se pudo cargar el elemento:", result.error);
    }
});

Fragmentar listas grandes de ID para límites de procesamiento por lotes​

Dado que en la mayoría de los nodos RPC públicos se aplica un límite de 50 elementos por solicitud, utiliza una función auxiliar de fragmentación para listas extensas:

chunking.js
import { chunk } from 'lodash'; // o tu propia función auxiliar

const allIds = [/* ... array de 200 IDs ... */];
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 }
    });
    // Procesar batchResults...
}

Prácticas recomendadas​

Manejar fallos parciales por elemento​

A diferencia de una consulta de base de datos estándar que podría detener todo el lote en caso de error, multiGetObjects devuelve un resultado para cada ID. Aunque un objeto falle (por ejemplo, si una transacción lo ha eliminado), el resto de elementos del lote se devuelven con éxito. Comprueba siempre data frente a error para cada elemento de la matriz devuelta.

Confiar en la preservación del orden de índices​

El SDK preserva el orden de índices de la matriz de entrada:

  • results[0] se corresponde con ids[0]
  • results[1] se corresponde con ids[1]

Puedes confiar en este orden para mapear los resultados directamente a tu fuente de datos original.

Ver también​