Aller au contenu principal

Référence API : multiGetObjects

Récupère les détails et les métadonnées sur la chaîne pour plusieurs objets Sui en une seule requête groupée, à partir de leurs identifiants d'objet hexadécimaux de 32 octets.

Utilisez cette méthode pour regrouper plusieurs requêtes d'objets en un seul appel réseau, ce qui réduit la latence par rapport à des requêtes individuelles. Comme multiGetObjects est une opération de lecture servie directement à partir de l'état local du nœud complet, elle s'exécute immédiatement sans soumettre de transaction ni consommer de gas.

  • Classe : SuiClient
  • Paquet : @mysten/sui/client
  • Type d'opération : opération de lecture (sans gas, sans signature de portefeuille)

Aperçu​

L'appel de la méthode multiGetObjects s'avère bien plus efficace que l'appel de getObject dans une boucle. Il réduit la latence réseau en regroupant plusieurs requêtes d'objets en un seul appel de procédure à distance (RPC).

Comparaison entre le traitement séquentiel et par lots
getObject séquentiel (N allers-retours) :
App ── getObject(A) ──► Fullnode ──► App ── getObject(B) ──► Fullnode

multiGetObjects par lots (1 aller-retour) :
App ──────────── multiGetObjects([A, B, C]) ────────────► Fullnode
App ◄─────────── [ResultA, ResultB, ResultC] ─────────── Fullnode

Signature​

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

Paramètres​

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

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

La plupart des nœuds RPC publics imposent une limite généralement fixée à 50 identifiants par requête. Pour les lots plus volumineux, vous devez diviser votre tableau en plusieurs fragments.

Valeur de retour​

Renvoie une Promise qui se résout en un tableau d'objets SuiObjectResponse.

L'ordre des éléments du tableau correspond exactement à l'ordre des identifiants transmis dans la requête :

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

Exemples d'utilisation​

Récupération en masse des métadonnées de NFT et des attributs d'affichage​

Interrogez une liste d'identifiants de NFT pour afficher les champs sur la chaîne et les URL des images :

bulkFetch.js
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("Élément trouvé :", result.data.display?.data?.name);
    } else {
        console.warn("Échec du chargement de l'élément :", result.error);
    }
});

Découper les longues listes d'identifiants pour respecter les limites de traitement par lots​

Étant donné qu'une limite de 50 éléments s'applique par requête sur la plupart des nœuds RPC publics, utilisez une fonction utilitaire de découpage pour les listes volumineuses :

chunking.js
import { chunk } from 'lodash'; // ou votre propre fonction utilitaire

const allIds = [/* ... tableau de 200 identifiants ... */];
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 }
    });
    // Traiter batchResults...
}

Bonnes pratiques​

Gérer les échecs partiels par élément​

Contrairement à une requête de base de données classique qui peut interrompre l'ensemble du lot en cas d'erreur, multiGetObjects renvoie un résultat pour chaque ID. Même si un objet échoue (par exemple, s'il a été supprimé par une transaction), les éléments restants du lot sont tout de même renvoyés avec succès. Vérifiez toujours data et error pour chaque élément du tableau renvoyé.

S'appuyer sur la préservation de l'ordre des index​

Le SDK conserve l'ordre des index du tableau d'entrée :

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

Vous pouvez vous fier à cet ordre pour mapper les résultats directement à votre source de données d'origine.

Voir aussi​