Aller au contenu principal

Référence API : getObject

Récupère les détails et les métadonnées sur la chaîne d'un objet Sui individuel à partir de son identifiant d'objet hexadécimal de 32 octets.

Utilisez cette méthode pour interroger les définitions de paquets Move, inspecter les champs des structures et vérifier la propriété des objets. Vous pouvez également vérifier si une transaction a modifié ou supprimé un objet. Comme getObject est une opération de lecture effectuée 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)

Signature​

Signature
client.getObject(input: GetObjectParams): Promise<SuiObjectResponse>

Paramètres​

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

ParamètreTypeObligatoireDescription
idstringOuiL'identifiant d'objet hexadécimal de 32 octets, par exemple 0x123....
optionsSuiObjectDataOptionsNonIndicateurs de configuration permettant d'activer des champs de données spécifiques dans la réponse. La valeur par défaut est false pour tous les champs.

SuiObjectDataOptions​

Par défaut, getObject renvoie uniquement la référence de l'objet, à savoir son ID, sa version et son résumé. Pour récupérer les données réelles, vous devez explicitement définir ces indicateurs sur true.

OptionDescription
showTypeRenvoie le type Move, par exemple 0x2::coin::Coin<0x2::sui::SUI>.
showContentRenvoie les champs de données Move analysés, représentant l'état interne de l'objet.
showOwnerRenvoie l'adresse ou l'objet propriétaire de cet élément.
showDisplayRenvoie les métadonnées d'affichage standard (noms, descriptions, URL d'images) pour le rendu de l'interface utilisateur.
showStorageRebateRenvoie la remise sur le stockage associée à l'objet.
showBcsRenvoie les octets bruts au format BCS (Binary Canonical Serialization) pour le décodage côté client.
showPreviousTransactionRenvoie le résumé de la dernière transaction ayant modifié cet objet.

Valeur de retour​

Renvoie une Promise qui se résout en un SuiObjectResponse. Cette réponse est une enveloppe standard qui encapsule à la fois les états de réussite et d'erreur :

Enveloppe SuiObjectResponse
┌─────────────────────────────────────────────────────────────┐
│                     SuiObjectResponse                       │
├──────────────────────────────┬──────────────────────────────┤
│   Succès: `response.data`    │    Erreur: `response.error`  │
│   - objectId, version        │    - code: "notExists"       │
│   - type, digest             │    - code: "deleted"         │
│   - content, owner, display  │    - object_id               │
└──────────────────────────────┴──────────────────────────────┘

Réponse de succès (data)​

Lorsque l'objet existe et reste accessible, la propriété data contient un objet SuiObjectData.

Réponse : succès
{
  "data": {
    "objectId": "0x...",
    "version": "10",
    "digest": "...",
    "type": "0x2::coin::Coin<0x2::sui::SUI>", // Présent si showType: true
    "content": {                              // Présent si showContent: true
       "dataType": "moveObject",
       "fields": { "balance": "1000000000" }
    },
    "owner": {                                // Présent si showOwner: true
       "AddressOwner": "0xabc..." 
    }
  }
}

Réponse d'erreur (error)​

Si une transaction a supprimé l'objet, l'a encapsulé dans un autre objet ou si l'ID n'existe pas, la propriété error renvoie les détails de l'erreur.

Réponse : erreur
{
  "error": {
    "code": "notExists",
    "object_id": "0x..."
  }
}

Exemples d'utilisation​

Vérifier si un objet existe​

Il s'agit de la requête la plus légère. Elle ne demande aucun champ de données, uniquement le résumé et le numéro de version.

checkExists.js
const response = await client.getObject({
    id: '0x123...'
});

if (response.error) {
    console.log("L'objet n'existe pas.");
} else {
    console.log("L'objet existe à la version :", response.data.version);
}

Récupérer les métadonnées et les champs d'affichage d'un NFT​

Cette requête demande content pour lire les champs sur la chaîne et display pour récupérer les ressources de rendu de l'interface utilisateur.

fetchNFT.js
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(`Nom du NFT : ${name}, Image : ${imageUrl}`);
} else {
    console.warn("Échec du chargement de l'élément :", nft.error);
}

Vérifier la propriété d'un objet​

Utilisez ceci pour vérifier si une adresse de compte spécifique possède un élément.

verifyOwnership.js
const item = await client.getObject({
    id: '0x123...',
    options: { showOwner: true }
});

const owner = item.data?.owner;

if (owner && owner.AddressOwner === '0xMyAddress...') {
    console.log("Vous êtes propriétaire de cet élément.");
}

Erreurs courantes​

Code d'erreurCauseRésolution
notExistsL'ID de l'objet est une valeur hexadécimale valide, mais le réseau ne parvient pas à localiser l'objet.Vérifiez l'ID ou confirmez qu'une transaction antérieure n'a pas supprimé l'objet.
deletedUne transaction a supprimé, brûlé ou purgé l'objet de l'état actif.Il n'est pas possible de récupérer les données historiques des objets supprimés via getObject.
invalid_paramL'ID d'objet fourni n'est pas une chaîne hexadécimale valide de 32 octets.Assurez-vous que l'ID commence par 0x et qu'il possède la bonne longueur.

Voir aussi​