Aller au contenu principal

Référence API : getOwnedObjects

Récupère une liste paginée d’objets sur la chaîne détenus par une adresse de portefeuille Sui spécifique de 32 octets.

Utilisez cette méthode pour alimenter les tableaux de bord des portefeuilles, les écrans d’inventaire des utilisateurs et les listes de soldes de jetons. Étant donné qu’un seul compte peut détenir des milliers d’objets, l’API JSON-RPC de Sui renvoie les objets détenus sur des pages distinctes à l’aide d’une pagination basée sur un curseur. Comme getOwnedObjects 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 (pas de gas, pas de signature de portefeuille)

Vue d'ensemble​

L’appel de getOwnedObjects interroge l’index du nœud complet pour trouver les objets dont la propriété est attribuée à l’adresse cible (AddressOwner). Afin d’éviter une latence élevée et des délais d’expiration du réseau, les nœuds complets paginent les résultats plutôt que de renvoyer l’intégralité de l’inventaire en une seule réponse.

Visualisation de la boucle de pagination​

Diagramme de flux de pagination par curseur

Signature​

Signature
client.getOwnedObjects(input: GetOwnedObjectsParams): Promise<PaginatedObjectsResponse>

Paramètres​

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

ParamètreTypeRequisDescription
ownerstringOuiL'adresse hexadécimale de 32 octets du portefeuille cible.
filterSuiObjectDataFilterNonCritères de filtrage des résultats par type, paquet ou module.
optionsSuiObjectDataOptionsNonIndicateurs permettant d’inclure des détails supplémentaires (par exemple, showType, showContent, showDisplay).
cursorstring | nullNonLe jeton nextCursor issu d’une réponse précédente pour récupérer la page suivante.
limitnumberNonNombre maximal d’éléments à renvoyer par page (la valeur par défaut et maximale est généralement de 50 sur les nœuds RPC publics).

SuiObjectDataFilter​

Le paramètre filter affine les requêtes sur le nœud complet, ce qui permet d’économiser de la bande passante et de réduire le traitement côté client :

Clé de filtreType de valeurDescription
MatchAllSuiObjectDataFilter[]ET logique. Un objet doit satisfaire à tous les critères de filtrage fournis.
MatchAnySuiObjectDataFilter[]OU logique. Un objet peut satisfaire à n'importe lequel des critères de filtrage fournis.
StructTypestringCorrespondance exacte avec un type Move Struct entièrement qualifié (par exemple, 0x2::coin::Coin<0x2::sui::SUI>).
PackagestringCorrespond à tout objet instancié à partir de modules appartenant à l’ID de paquet spécifié.
MoveModule{ package: string, module: string }Correspond à tout objet défini au sein d’un module spécifique d’un paquet.

Valeur de retour​

Renvoie une Promise qui se résout en un objet PaginatedObjectsResponse :

Réponse
{
  "data": [
    { "data": { "objectId": "0xA...", "version": "1", "type": "0x2::coin::Coin<0x2::sui::SUI>" } },
    { "data": { "objectId": "0xB...", "version": "4", "type": "0x2::coin::Coin<0x2::sui::SUI>" } }
  ],
  "hasNextPage": true,
  "nextCursor": "0x12345...ResultCursor"
}

L’enveloppe de réponse contient les champs suivants :

ChampTypeDescription
dataSuiObjectResponse[]Tableau d’enveloppes de réponse d’objets pour la page actuelle.
hasNextPagebooleanIndique s’il existe d’autres pages d’objets.
nextCursorstring | nullJeton de pagination opaque à passer en tant que cursor lors de l’appel suivant. Lorsque hasNextPage est false, cette valeur est null.

Exemples d'utilisation​

Récupérer la première page d’un inventaire​

Récupérer les 5 premiers objets détenus par une adresse :

basicInventory.js
const response = await client.getOwnedObjects({
    owner: '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
    limit: 5,
    options: { showType: true }
});

response.data.forEach((item) => {
    if (item.data) {
        console.log(`ID: ${item.data.objectId}, Type: ${item.data.type}`);
    }
});

Filtrer les actifs par type de structure Move​

Interroger uniquement les objets de type SUI coin détenus par un utilisateur, en excluant les autres jetons et NFT :

filterCoins.js
const response = await client.getOwnedObjects({
    owner: '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
    filter: {
        StructType: '0x2::coin::Coin<0x2::sui::SUI>'
    },
    options: { showContent: true }
});

console.log(`Objets SUI coin trouvés : ${response.data.length}`);

Pager tous les objets détenus​

Utiliser une boucle while pour parcourir tous les objets détenus par une adresse :

pagination.js
let hasNextPage = true;
let nextCursor = null;
const allObjects = [];

while (hasNextPage) {
    const response = await client.getOwnedObjects({
        owner: '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
        cursor: nextCursor,
        limit: 50
    });

    allObjects.push(...response.data);
    
    hasNextPage = response.hasNextPage;
    nextCursor = response.nextCursor;
}

console.log(`Total des objets récupérés : ${allObjects.length}`);

Erreurs courantes​

Code d'erreurCauseRésolution
cursor_invalidLa chaîne transmise à cursor a expiré, est mal formée ou provient d’une requête différente.Transmettez exactement la chaîne de caractères renvoyée dans nextCursor par la requête précédente.
limit_exceededLa limite demandée dépasse la taille maximale de page autorisée par le nœud complet (généralement 50).Réduisez le paramètre limit à 50 éléments ou moins.

Voir aussi​