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
- Mermaid (schéma)
- Mermaid (code)
- ASCII
flowchart TD
Start([Démarrer la pagination]) --> Init["Initialiser curseur = null<br/>allObjects = []"]
Init --> Query["Appeler getOwnedObjects<br/>(cursor, limit: 50)"]
Query --> Resp["Recevoir la réponse :<br/>data[], hasNextPage, nextCursor"]
Resp --> Append["Ajouter les éléments au<br/>tableau allObjects"]
Append --> Check{"hasNextPage == true ?"}
Check -->|Oui| Update["Mettre à jour curseur = nextCursor"]
Check -->|Non| Done([Renvoyer tous les objets accumulés])
Update -.->|Page suivante| Query
Flux de pagination (boucle de curseur) :
Client Nœud complet
│ │
│── getOwnedObjects(cursor: null) ──────────►│ (Page 1 : limite 50)
│◄── { data: [50 items], nextCursor } ───────│
│ │
│── getOwnedObjects(cursor: nextCursor) ────►│ (Page 2 : limite 50)
│◄── { data: [12 items], hasNextPage: false }
Signature
client.getOwnedObjects(input: GetOwnedObjectsParams): Promise<PaginatedObjectsResponse>
Paramètres
La méthode accepte un objet de configuration comportant les propriétés suivantes :
| Paramètre | Type | Requis | Description |
|---|---|---|---|
owner | string | Oui | L'adresse hexadécimale de 32 octets du portefeuille cible. |
filter | SuiObjectDataFilter | Non | Critères de filtrage des résultats par type, paquet ou module. |
options | SuiObjectDataOptions | Non | Indicateurs permettant d’inclure plus de détails, par exemple showType, showContent et showDisplay. |
cursor | string | null | Non | Jeton nextCursor issu d’une réponse précédente, utilisé pour récupérer la page suivante. |
limit | number | Non | Nombre 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 filtre | Type de valeur | Description |
|---|---|---|
MatchAll | SuiObjectDataFilter[] | Exige tous les critères de filtre. |
MatchAny | SuiObjectDataFilter[] | Exige l’un des critères de filtre. |
StructType | string | Correspondance exacte avec un type Move Struct entièrement qualifié, par exemple 0x2::coin::Coin<0x2::sui::SUI>. |
Package | string | Correspond à 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 :
{
"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 :
| Champ | Type | Description |
|---|---|---|
data | SuiObjectResponse[] | Tableau d’enveloppes de réponse d’objets pour la page actuelle. |
hasNextPage | boolean | Indique si d’autres pages d’objets existent. |
nextCursor | string | null | Jeton 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 :
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 :
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 :
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'erreur | Cause | Résolution |
|---|---|---|
cursor_invalid | La 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_exceeded | La 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
getObjectrécupère les détails d’un objet individuel sur la chaîne.multiGetObjectsrécupère les détails de nombreux objets dans une seule requête par lot.- Comment récupérer des données d’objets fournit un tutoriel étape par étape pour la mise en œuvre d’opérations de lecture dans Node.js.
- L'architecture de SuiClient explique la conception conceptuelle de
SuiClientet des opérations de lecture.