Aller au contenu principal

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 et gérer les inventaires des utilisateurs. Un compte peut contenir des milliers d’objets. L’API Sui renvoie les objets détenus sur des pages distinctes avec une pagination basée sur un curseur. JSON-RPC (JavaScript Object Notation Remote Procedure Call) envoie cette requête à un nœud complet Sui. getOwnedObjects lit l’état du nœud complet et s’exécute immédiatement, sans transaction ni gas. Les appelants n’ont pas besoin de signature de portefeuille.

  • Classe : SuiClient
  • Paquet : @mysten/sui/client
  • Type d’opération : opération de lecture
  • Transaction : non requise
  • Gas : non consommé
  • Signature du portefeuille : non requise

Fonctionnement de la pagination​

L’appel de getOwnedObjects interroge l’index du nœud complet pour trouver les objets attribués à l’adresse cible. Le type de propriété est AddressOwner.

Les nœuds complets paginent les résultats afin d’éviter une latence élevée et les délais d’expiration du réseau. Ils ne renvoient pas tout l’inventaire dans 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 plus de détails, par exemple showType, showContent et showDisplay.
cursorstring | nullNonJeton nextCursor issu d’une réponse précédente, utilisé pour récupérer la page suivante.
limitnumberNonNombre maximal d’éléments par page. Les nœuds JSON-RPC publics utilisent généralement 50 par défaut et n’autorisent pas plus de 50 éléments.

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[]Exige tous les critères de filtre.
MatchAnySuiObjectDataFilter[]Exige l’un des critères de filtre.
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 si d’autres pages d’objets existent.
nextCursorstring | nullJeton de pagination opaque à passer comme cursor lors de l’appel suivant. Si hasNextPage vaut false, nextCursor vaut 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​

Interrogez uniquement les objets de type pièce SUI détenus par un utilisateur. SUI est la cryptomonnaie native du réseau. Excluez 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​

Utilisez une boucle while pour traiter 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 cursor a expiré, utilise un format non valide ou provient d’une autre requête.Transmettez la chaîne exacte renvoyée par nextCursor lors de la requête précédente.
limit_exceededLa limite demandée dépasse la limite de taille de page du nœud complet, généralement fixée à 50.Définissez limit sur 50 éléments ou moins.

Voir aussi​