getObject
Récupère les détails et les métadonnées sur la chaîne d'un objet Sui à l'aide de son identifiant d'objet hexadécimal de 32 octets.
Utilisez cette méthode pour inspecter les paquets Move et la propriété des objets. Vous pouvez également vérifier les champs des structures. Une opération de lecture ne peut pas modifier l'objet. getObject lit à partir de l'état du nœud complet. Elle s'exécute sans transaction, sans gas et sans signature de portefeuille.
- Classe :
SuiClient - Package :
@mysten/sui/client
Signature
client.getObject(input: GetObjectParams): Promise<SuiObjectResponse>
Paramètres
La méthode accepte un objet. Elle comprend les propriétés ci-dessous.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
id | string | Oui | L'identifiant hexadécimal de l'objet de 32 octets, tel que 0x123.... |
options | SuiObjectDataOptions | Non | Indicateurs pour les champs de données de réponse. Chaque indicateur est défini par défaut sur false. |
SuiObjectDataOptions
Par défaut, getObject renvoie un identifiant, une version et un condensé. Définissez chaque indicateur sur true pour récupérer davantage de données.
| Option | Description |
|---|---|
showType | Renvoie le type de Move, tel que 0x2::coin::Coin<0x2::sui::SUI>. |
showContent | Renvoie les champs de données Move analysés, représentant l'état interne de l'objet. |
showOwner | Renvoie l'adresse ou l'objet propriétaire de cet élément. |
showDisplay | Renvoie les métadonnées standard « Display » pour le rendu de l'interface utilisateur. Ces métadonnées comprennent les noms, les descriptions et les URL d'images. |
showStorageRebate | Renvoie la remise de stockage associée à l'objet. |
showBcs | Renvoie les octets bruts de la sérialisation binaire canonique (BCS) pour le décodage côté client. |
showPreviousTransaction | Renvoie le condensé de la dernière transaction ayant modifié cet objet. |
Valeur de retour
Renvoie une Promise qui se résout en une SuiObjectResponse. La réponse contient des données de réussite ou d'erreur :
┌─────────────────────────────────────────────────────────────┐
│ SuiObjectResponse │
├──────────────────────────────┬──────────────────────────────┤
│ Success: `response.data` │ Error: `response.error` │
│ - objectId, version │ - code: "notExists" │
│ - type, digest │ - code: "deleted" │
│ - content, owner, display │ - object_id │
└──────────────────────────────┴──────────────────────────────┘
Réponse de réussite : data
Lorsque l'objet existe, sa propriété data contient un objet SuiObjectData.
{
"data": {
"objectId": "0x...",
"version": "10",
"digest": "...",
"type": "0x2::coin::Coin<0x2::sui::SUI>",
"content": {
"dataType": "moveObject",
"fields": { "balance": "1000000000" }
},
"owner": {
"AddressOwner": "0xabc..."
}
}
}
Réponse d'erreur : error
La propriété error renvoie des détails lorsqu'une transaction supprime l'objet ou l'encapsule dans un autre objet. Elle renvoie également des détails lorsque l'ID n'existe pas.
{
"error": {
"code": "notExists",
"object_id": "0x..."
}
}
Exemples d'utilisation
Vérifier si un objet existe
Cette requête légère ne demande pas de champs de données. Elle renvoie uniquement le digest et le numéro de version.
const response = await client.getObject({
id: '0x123...'
});
if (response.error) {
console.log("Object doesn't exist.");
} else if (response.data) {
console.log("Object exists at version:", response.data.version);
} else {
console.log("The response didn't include object data.");
}
Récupérer les métadonnées d'un jeton non fongible et les champs d'affichage
Cette requête définit showContent pour lire les champs sur la chaîne et showDisplay pour récupérer les ressources de l'interface utilisateur.
const nft = await client.getObject({
id: '0x123...',
options: {
showContent: true,
showDisplay: true
}
});
if (nft.data) {
const name = nft.data.content?.fields?.name;
const imageUrl = nft.data.display?.data?.image_url;
console.log(`NFT Name: ${name}, Image: ${imageUrl}`);
} else {
console.warn("Item failed to load:", nft.error);
}
Vérifier la propriété d'un objet
Utilisez ce code pour vérifier si une adresse de compte spécifique contrôle un élément.
const item = await client.getObject({
id: '0x123...',
options: { showOwner: true }
});
const owner = item.data?.owner;
if (owner && owner.AddressOwner === '0xMyAddress...') {
console.log("You own this item.");
}
Erreurs courantes
| Code d'erreur | Cause | Résolution |
|---|---|---|
notExists | L'ID de l'objet contient une valeur hexadécimale valide, mais le réseau ne parvient pas à localiser l'objet. | Vérifiez l'ID ou assurez-vous qu'une transaction antérieure n'a pas supprimé l'objet. |
deleted | Une transaction a supprimé, brûlé ou éliminé l'objet de l'état actif. | Vous ne pouvez pas récupérer les données historiques des objets supprimés via getObject. |
invalid_param | L'ID de l'objet présente un format hexadécimal de 32 octets mal formé. | Vérifiez que l'ID commence par 0x et qu'il a la longueur correcte. |
Voir aussi
multiGetObjectsrécupère les détails de quatre objets en une seule requête groupée.getOwnedObjectsrépertorie tous les objets appartenant à une adresse spécifique.- Comment récupérer les données d'un objet propose un tutoriel utilisant
getObjectdans un script Node.js. - L'architecture de SuiClient explique la conception conceptuelle de
SuiClientet des opérations de lecture.