Aller au contenu principal

Référence API : multiGetObjects

Récupère les détails de plusieurs objets en une seule requête réseau.

-Classe: SuiClient

  • Method Type: Opération de lecture, pas de gaz

Aperçu​

L'utilisation de multiGetObjects s'avère beaucoup plus efficace que d'appeler getObject dans une boucle. Elle réduit la latence du réseau en combinant plusieurs requêtes en un seul appel de procédure à distance (RPC).

Signature​

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

Paramètres​

La méthode accepte un objet de configuration avec les propriétés suivantes :

ParamètreTypeObligatoireDescription
idsstring[]OuiUn tableau d'ID d'objets hexadécimaux de 32 octets.
optionsSuiObjectDataOptionsNonDrapeaux de configuration pour activer des champs de données spécifiques. S'applique à tous les objets demandés.
remarque

La plupart des nœuds RPC publics appliquent une limite de 50 ID par requête. Pour des lots plus importants, vous devez diviser votre tableau en morceaux.

Valeur de retour​

Retourne une Promesse qui se résout en un tableau d'objets SuiObjectResponse.

L'ordre du tableau correspond exactement à l'ordre des id passés dans la requête.

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

Exemples d'utilisation​

Scénario A : récupération en masse de métadonnées​

Imaginez que vous disposiez d'une liste d'identifiants de jetons non fongibles (NFT) et que vous ayez besoin d'afficher leurs noms.

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

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

// Traiter les résultats
results.forEach((result) => {
    if (result.data) {
        console.log("Found Item :", result.data.display ?.data ?.name) ;
    } else {
        console.warn("Item failed to load :", result.error) ;
    }
}) ;

Scénario B : Traitement des grandes listes par découpage​

Étant donné qu'une limite de 50 éléments, par exemple, s'applique à chaque requête, il convient d'utiliser une aide au découpage pour les listes volumineuses.

import { chunk } from 'lodash' ; // ou votre propre aide

const allIds = [/* ... tableau de 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 }
    }) ;
    // Traite les résultats du lot...
}

Meilleures pratiques​

1. Toujours gérer les échecs partiels​

Contrairement à une requête de base de données standard qui pourrait arrêter tout le lot en cas d'erreur, multiGetObjects renvoie un résultat pour chaque ID. Même si vous supprimez un objet ( ***** ), les autres retournent toujours un résultat positif ( **** ). Vous devez vérifier data vs error pour chaque élément du tableau retourné.

2. Préservation de l'ordre​

Le SDK garantit que le tableau de sortie correspond à l'index du tableau d'entrée.

  • results[0] correspond à ids[0].
  • results[1] correspond à ids[1].

Vous pouvez compter sur cela pour mapper les résultats vers votre source de données originale.