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

APIリファレンス: getObject

32バイトの16進数オブジェクトIDを指定して、個々のSuiオブジェクトのオンチェーン詳細およびメタデータを取得します。

このメソッドを使用すると、Moveパッケージ定義の照会、構造体のフィールドの確認、およびオブジェクトの所有権の検証を行うことができます。また、トランザクションによってオブジェクトが変更または削除されたかどうかも確認できます。getObjectはフルノードのローカル状態から直接提供される読み取り操作であるため、トランザクションを送信したりガスを消費したりすることなく、即座に実行されます。

  • クラス: SuiClient
  • パッケージ: @mysten/sui/client
  • 操作タイプ: 読み取り操作（ガス代不要、ウォレット署名不要）

シグネチャ​

シグネチャ
client.getObject(input: GetObjectParams): Promise<SuiObjectResponse>

パラメータ​

このメソッドは、以下のプロパティを含む単一の設定オブジェクトを受け取ります：

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

SuiObjectDataOptions​

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

オプション説明
showTypeMove型を返します（例: 0x2::coin::Coin<0x2::sui::SUI>）。
showContentオブジェクトの内部状態を表す、解析済みのMoveデータフィールドを返します。
showOwnerこのアイテムを所有するアドレスまたはオブジェクトを返します。
showDisplayUIレンダリング用のDisplay標準メタデータ（名前、説明、画像URL）を返します。
showStorageRebateオブジェクトに関連付けられたストレージリベートを返します。
showBcsクライアント側でのデコード用に、未加工のBCS（Binary Canonical Serialization）バイト配列を返します。
showPreviousTransactionこのオブジェクトを最後に変更したトランザクションのダイジェストを返します。

戻り値​

SuiObjectResponseに解決されるPromiseを返します。このレスポンスは、成功状態とエラー状態の両方をカプセル化した標準的なエンベロープです：

SuiObjectResponseエンベロープ
┌─────────────────────────────────────────────────────────────┐
│                     SuiObjectResponse                       │
├──────────────────────────────┬──────────────────────────────┤
│   成功: `response.data`      │    エラー: `response.error`  │
│   - objectId, version        │    - code: "notExists"       │
│   - type, digest             │    - code: "deleted"         │
│   - content, owner, display  │    - object_id               │
└──────────────────────────────┴──────────────────────────────┘

成功レスポンス (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..." 
    }
  }
}

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

トランザクションによってオブジェクトが削除された場合、別のオブジェクトにラップされた場合、またはIDが存在しない場合、errorプロパティがエラーの詳細を返します。

レスポンス: エラー
{
  "error": {
    "code": "notExists",
    "object_id": "0x..."
  }
}

使用例​

オブジェクトが存在するか確認する​

これは最も軽量なクエリです。データフィールドは一切指定せず、ダイジェストとバージョン番号のみを要求します。

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

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

NFTメタデータとDisplayフィールドを取得する​

このリクエストは、オンチェーンフィールドを読み取るためにcontentを要求し、UIレンダリングアセットを取得するためにdisplayを要求します。

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(`NFT名: ${name}, 画像: ${imageUrl}`);
} else {
    console.warn("アイテムの読み込みに失敗しました:", nft.error);
}

オブジェクトの所有権を検証する​

これを使用して、特定のアカウントアドレスがアイテムを所有しているかどうかを確認します。

verifyOwnership.js
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トランザクションによってアクティブな状態からオブジェクトが削除、バーン、またはプルーニングされました。getObjectを使用して削除されたオブジェクトの履歴データを取得することはできません。
invalid_param指定されたオブジェクトIDが有効な32バイトの16進数文字列ではありません。IDが0xで始まり、正しい長さであることを確認してください。

関連情報​