getObject
Recupera los detalles y metadatos en cadena de un objeto Sui mediante su ID de objeto hexadecimal de 32 bytes.
Utiliza este método para inspeccionar paquetes Move y la propiedad de objetos. También puedes comprobar campos de estructuras. Una operación de lectura no puede cambiar el objeto. getObject lee el estado del nodo completo. Se ejecuta sin una transacción, gas ni firma de la billetera.
- Clase:
SuiClient - Paquete:
@mysten/sui/client
Firma
client.getObject(input: GetObjectParams): Promise<SuiObjectResponse>
Parámetros
El método acepta un objeto que incluye las propiedades siguientes.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
id | string | Sí | El ID de objeto hexadecimal de 32 bytes, como 0x123.... |
options | SuiObjectDataOptions | No | Indicadores para los campos de datos de la respuesta. Cada indicador tiene el valor predeterminado false. |
SuiObjectDataOptions
De manera predeterminada, getObject devuelve un ID, una versión y el digest. Establece cada indicador en true para recuperar más datos.
| Opción | Descripción |
|---|---|
showType | Devuelve el tipo Move, como 0x2::coin::Coin<0x2::sui::SUI>. |
showContent | Devuelve los campos de datos Move analizados, que representan el estado interno del objeto. |
showOwner | Devuelve la dirección o el objeto que posee este elemento. |
showDisplay | Devuelve metadatos estándar de Display para representar el elemento en la interfaz. Estos metadatos incluyen nombres, descripciones y URL de imágenes. |
showStorageRebate | Devuelve el descuento de almacenamiento asociado al objeto. |
showBcs | Devuelve bytes sin procesar en formato Binary Canonical Serialization para la decodificación en el cliente. |
showPreviousTransaction | Devuelve el digest de la última transacción que modificó este objeto. |
Valor de retorno
Devuelve una Promise que se resuelve en un SuiObjectResponse. La respuesta contiene datos de éxito o de error:
┌─────────────────────────────────────────────────────────────┐
│ SuiObjectResponse │
├──────────────────────────────┬──────────────────────────────┤
│ Éxito: `response.data` │ Error: `response.error` │
│ - objectId, version │ - code: "notExists" │
│ - type, digest │ - code: "deleted" │
│ - content, owner, display │ - object_id │
└──────────────────────────────┴──────────────────────────────┘
Respuesta de éxito: data
Cuando el objeto existe, su propiedad data contiene SuiObjectData.
{
"data": {
"objectId": "0x...",
"version": "10",
"digest": "...",
"type": "0x2::coin::Coin<0x2::sui::SUI>", // Presente si showType: true
"content": { // Presente si showContent: true
"dataType": "moveObject",
"fields": { "balance": "1000000000" }
},
"owner": { // Presente si showOwner: true
"AddressOwner": "0xabc..."
}
}
}
Respuesta de error: error
La propiedad error devuelve detalles cuando una transacción elimina el objeto o lo envuelve dentro de otro objeto. También devuelve detalles cuando el ID no existe.
{
"error": {
"code": "notExists",
"object_id": "0x..."
}
}
Ejemplos de uso
Comprobar si un objeto existe
Esta consulta ligera no solicita campos de datos. Solo devuelve el digest y el número de versión.
const response = await client.getObject({
id: '0x123...'
});
if (response.error) {
console.log("El objeto no existe.");
} else if (response.data) {
console.log("El objeto existe en la versión:", response.data.version);
} else {
console.log("La respuesta no incluye datos del objeto.");
}
Obtener metadatos de tokens no fungibles y campos de visualización
Esta solicitud establece showContent para leer campos en la cadena y showDisplay para recuperar recursos de la interfaz.
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(`Nombre del NFT: ${name}, Imagen: ${imageUrl}`);
} else {
console.warn("No se pudo cargar el elemento:", nft.error);
}
Verificar la propiedad del objeto
Utiliza este código para comprobar si una cuenta específica controla un elemento.
const item = await client.getObject({
id: '0x123...',
options: { showOwner: true }
});
const owner = item.data?.owner;
if (owner && owner.AddressOwner === '0xMyAddress...') {
console.log("Eres el propietario de este elemento.");
}
Errores comunes
| Código de error | Causa | Resolución |
|---|---|---|
notExists | El ID del objeto es un valor hexadecimal válido, pero la red no puede localizar el objeto. | Verifica el ID o confirma que una transacción anterior no haya eliminado el objeto. |
deleted | Una transacción ha eliminado, quemado o podado el objeto del estado activo. | No es posible recuperar datos históricos de objetos eliminados mediante getObject. |
invalid_param | El ID de objeto proporcionado no es una cadena hexadecimal válida de 32 bytes. | Asegúrate de que el ID comience por 0x y tenga la longitud correcta. |
Ver también
multiGetObjectsrecupera los detalles de varios objetos en una única solicitud por lotes.getOwnedObjectsenumera todos los objetos que pertenecen a una dirección específica.- Cómo obtener datos de objetos proporciona un tutorial paso a paso que implementa
getObjecten un script de Node.js. - La arquitectura de SuiClient explica el diseño conceptual de
SuiClienty las operaciones de lectura.