メインコンテンツまでスキップ

API リファレンス: getObject

ブロックチェーンから特定のオブジェクトの詳細を取得します。

クラス: SuiClient メソッドタイプ: 読み取り操作、ガス代不要

シグネチャ​

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

パラメーター​

このメソッドは、以下のプロパティを含む単一の構成オブジェクトを受け入れます。

パラメータータイプ必須説明
idstringはい32 バイトの 16 進数オブジェクト ID（例: 0x123...）。
optionsSuiObjectDataOptionsいいえレスポンス内の特定のデータ フィールドを切り替えるための構成フラグ。デフォルトではすべてのフィールドが false です。

SuiObjectDataOptions​

デフォルトでは、getObject はオブジェクトの参照（具体的には ID、バージョン、およびダイジェスト）のみを返します。実際のデータを取得するには、これらのフラグを明示的に true に設定する必要があります。

オプション説明
showTypeMove タイプ（例: 0x2::coin::Coin<SUI>）を返します。
showContentパースされた Move データ フィールド（オブジェクトの内部状態）を返します。
showOwnerこのアイテムを所有するアドレスまたはオブジェクトを返します。
showDisplayUI レンダリング用の Display 標準メタデータ（具体的には画像と名前）を返します。
showStorageRebateオブジェクトに関連付けられたストレージ リベート（払い戻し）を返します。

戻り値​

SuiObjectResponse に解決される Promise を返します。このレスポンスは、成功状態とエラー状態の両方を処理する標準的なラッパーです。

1. 成功レスポンス (data)​

オブジェクトが存在し、アクセスが維持されている場合、data プロパティに SuiObjectData が保持されます。

{
  "data": {
    "objectId": "0x...",
    "version": "10",
    "digest": "...",
    "type": "0x2::coin::Coin<0x2::sui::SUI>", // showType: true の場合に存在
    "content": {                              // showContent: true の場合に存在
       "dataType": "moveObject",
       "fields": { "balance": "1000000000" }
    },
    "owner": {                                // showOwner: true の場合に存在
       "AddressOwner": "0xabc..." 
    }
  }
}

2. エラーレスポンス (error)​

オブジェクトを削除したか、別のオブジェクトにラップされている、または存在しない場合、error プロパティに値が保持されます。

{
  "error": {
    "code": "notExists",
    "object_id": "0x..."
  }
}

使用例​

シナリオ A: オブジェクトが存在するか確認する​

これは最も軽量なクエリです。データは要求せず、ダイジェストとバージョンのみを取得します。

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

if (response.error) {
    console.log("オブジェクトが存在しません。");
} else {
    console.log("オブジェクトはバージョンで存在します:", response.data.version);
}

シナリオ B: 非代替性トークン (NFT) のメタデータを取得する​

このリクエストでは、フィールドを読み取るために content を、画像アドレスを確認するために display を要求します。

const nft = await client.getObject({
    id: '0x123...',
    options: {
        showContent: true,
        showDisplay: true
    }
});

const name = nft.data.content.fields.name;
const imageUrl = nft.data.display.data.image_url;

シナリオ C: 所有権の確認​

これを使用して、特定のユーザーがアイテムを所有しているかどうかを確認します。

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

const owner = item.data.owner;

if (owner && owner.AddressOwner === '0xMyAddress...') {
    console.log("あなたはこのアイテムの所有者です。");
}

よくあるエラー​

エラーコード原因解決策
notExistsオブジェクト ID は有効な 16 進数ですが、ネットワーク上でオブジェクトが見つかりません。ID を確認するか、前のトランザクションでオブジェクトが削除されていないか確認してください。
deletedオブジェクトは以前存在していましたが、バーンされたか削除されました。削除されたオブジェクトのデータは取得できません。
invalid_param指定されたオブジェクト ID が有効な 32 バイトの 16 進文字列ではありません。ID が 0x で始まり、正しい長さであることを確認してください。

関連項目​

  • getMultiGetObjects: 一括処理のために、1 回のネットワーク リクエストで多数のオブジェクトを取得します。
  • getOwnedObjects: 特定のアドレスが所有するすべてのオブジェクトを検索します。