Assetの取得

このガイドでは、Metaplex Core SDKを使用してSolanaブロックチェーンからCore AssetとCollectionを取得する方法を説明します。個々のAssetを取得したり、所有者やCollectionでクエリしたり、インデックスクエリにDASを使用できます。

概要

SDKヘルパー関数またはDAS APIを使用してCore AssetとCollectionを取得します。ユースケースに基づいて適切な方法を選択してください：

• 単一のAsset/Collection: 公開鍵でfetchAsset()またはfetchCollection()を使用
• 複数のAsset: fetchAssetsByOwner()、fetchAssetsByCollection()、またはfetchAssetsByUpdateAuthority()を使用
• DAS API: より高速なパフォーマンスのためにインデックスクエリを使用（DAS対応RPCが必要）

スコープ外

Token Metadataの取得（mpl-token-metadataを使用）、圧縮NFTの取得（Bubblegum DAS拡張を使用）、オフチェーンメタデータの取得（URIを直接フェッチ）。

クイックスタート

ジャンプ先: 単一Asset · 所有者別 · Collection別 · DAS API

1. インストール: npm install @metaplex-foundation/mpl-core @metaplex-foundation/umi
2. RPCエンドポイントでUmiを設定
3. AssetアドレスでfetchAsset(umi, publicKey)を呼び出す
4. Assetプロパティにアクセス: name、uri、owner、plugins

前提条件

• RPC接続が設定されたUmi
• 取得するAsset/Collectionアドレス（公開鍵）
• インデックスクエリ用のDAS対応RPC（オプションだが推奨）

単一のAssetまたはCollectionの取得

単一のAssetを取得するには、以下の関数を使用できます：

1import { fetchAsset, fetchCollection, mplCore } from '@metaplex-foundation/mpl-core';
2import { publicKey } from '@metaplex-foundation/umi';
3import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
4
5// Initialize UMI
6const umi = createUmi('https://api.devnet.solana.com')
7  .use(mplCore())
8
9// Fetch a Core Asset
10const assetAddress = publicKey('AssetAddressHere...')
11const asset = await fetchAsset(umi, assetAddress)
12
13// Fetch a Core Collection
14const collectionAddress = publicKey('CollectionAddressHere...')
15const collection = await fetchCollection(umi, collectionAddress)
16
17console.log('Asset fetched:', asset)
18console.log('Name:', asset.name)
19console.log('Owner:', asset.owner)
20console.log('URI:', asset.uri)
21
22console.log('\nCollection fetched:', collection)
23console.log('Name:', collection.name)
24console.log('URI:', collection.uri)

import { fetchCollection } from '@metaplex-foundation/mpl-core'
const asset = await fetchCollection(umi, collection.publicKey, {
  skipDerivePlugins: false,
})
console.log(asset)

複数のAssetの取得

複数のAssetは、getProgramAccounts（GPA）呼び出しを使用して取得できます。これはRPC的にかなり高コストで遅くなる可能性がありますが、Digital Asset Standard APIを使用する方法もあります。こちらはより高速ですが、特定のRPCプロバイダーが必要です。

所有者別Assetの取得

import { publicKey } from '@metaplex-foundation/umi'
import { fetchAssetsByOwner } from '@metaplex-foundation/mpl-core'
const owner = publicKey('11111111111111111111111111111111')
const assetsByOwner = await fetchAssetsByOwner(umi, owner, {
  skipDerivePlugins: false,
})
console.log(assetsByOwner)

Collection別Assetの取得

import { publicKey } from '@metaplex-foundation/umi'
import { fetchAssetsByCollection } from '@metaplex-foundation/mpl-core'
const collection = publicKey('11111111111111111111111111111111')
const assetsByCollection = await fetchAssetsByCollection(umi, collection, {
  skipDerivePlugins: false,
})
console.log(assetsByCollection)

Update Authority別Assetの取得

単一のAssetを取得するには、以下の関数を使用できます：

import { publicKey } from '@metaplex-foundation/umi'
import { fetchAssetsByUpdateAuthority } from '@metaplex-foundation/mpl-core'
const updateAuthority = publicKey('11111111111111111111111111111111')
const assetsByUpdateAuthority = await fetchAssetsByUpdateAuthority(
  umi,
  updateAuthority,
  { skipDerivePlugins: false }
)
console.log(assetsByUpdateAuthority)

DAS - Digital Asset Standard API

DAS対応RPCを使用すると、インデックス化されたAssetを活用して超高速のフェッチとデータ取得が可能になります。 DASはメタデータ、オフチェーンメタデータ、コレクションデータ、プラグイン（Attributesを含む）など、すべてをインデックス化します。Metaplex DAS APIについて詳しくはこちらをご覧ください。一般的なDAS SDKに加えて、MPL Core用の拡張機能が作成されており、MPL Core SDKでさらに使用できる正しい型を直接返します。また、Collectionから継承されたAssetのプラグインを自動的に継承し、DASからCoreへの型変換関数も提供します。 以下は、DASでMPL Core Assetを取得した際に返されるデータの例です。

FetchAssetの例

{
  "id": 0,
  "jsonrpc": "2.0",
  "result": {
    "authorities": [
      {
        "address": "Gi47RpRmg3wGsRRzFvcmyXHkELHznpx6DxEELGWBRWoC",
        "scopes": ["full"]
      }
    ],
    "burnt": false,
    "compression": {
      "asset_hash": "",
      "compressed": false,
      "creator_hash": "",
      "data_hash": "",
      "eligible": false,
      "leaf_id": 0,
      "seq": 0,
      "tree": ""
    },
    "content": {
      "$schema": "https://schema.metaplex.com/nft1.0.json",
      "files": [],
      "json_uri": "https://example.com/asset",
      "links": {},
      "metadata": {
        "name": "Test Asset",
        "symbol": ""
      }
    },
    "creators": [],
    "grouping": [
      {
        "group_key": "collection",
        "group_value": "8MPNmg4nyMGKdStSxbo2r2aoQGWz1pdjtYnQEt1kA2V7"
      }
    ],
    "id": "99A5ZcoaRSTGRigMpeu1u4wdgQsv6NgTDs5DR2Ug9TCQ",
    "interface": "MplCore",
    "mutable": true,
    "ownership": {
      "delegate": null,
      "delegated": false,
      "frozen": false,
      "owner": "Gi47RpRmg3wGsRRzFvcmyXHkELHznpx6DxEELGWBRWoC",
      "ownership_model": "single"
    },
    "plugins": {
      "FreezeDelegate": {
        "authority": {
          "Pubkey": {
            "address": "Gi47RpRmg3wGsRRzFvcmyXHkELHznpx6DxEELGWBRWoC"
          }
        },
        "data": {
          "frozen": false
        },
        "index": 0,
        "offset": 119
      }
    },
    "royalty": {
      "basis_points": 0,
      "locked": false,
      "percent": 0,
      "primary_sale_happened": false,
      "royalty_model": "creators",
      "target": null
    },
    "supply": null,
    "unknown_plugins": [
      {
        "authority": {
          "Pubkey": {
            "address": "Gi47RpRmg3wGsRRzFvcmyXHkELHznpx6DxEELGWBRWoC"
          }
        },
        "data": "CQA=",
        "index": 1,
        "offset": 121,
        "type": 9
      }
    ]
  }
}

よくあるエラー

Asset not found

公開鍵が有効なCore Assetを指していません。確認してください：

• アドレスが正しく、期待されるネットワーク（devnet対mainnet）にあること
• アカウントが存在し、Core Asset（Token Metadataではない）であること

RPC rate limit exceeded

GPAクエリはコストがかかる場合があります。解決策：

• インデックスクエリにDAS対応RPCを使用する
• ページネーションを追加して結果を制限する
• 適切な場所で結果をキャッシュする

注意事項

• fetchAssetはCollectionから継承されたプラグインを含む完全なAssetを返します
• Assetレベルのプラグインのみを取得するにはskipDerivePlugins: trueを設定（より高速）
• GPAクエリ（fetchAssetsByOwnerなど）はメインネットでは遅くなる可能性あり - DASを推奨
• DASはオフチェーンメタデータを返し、SDKフェッチ関数はオンチェーンデータのみを返します

クイックリファレンス

フェッチ関数

DAS vs GPA比較

FAQ

複数のAssetを取得する場合、GPAとDASのどちらを使うべきですか？

可能な限りDASを使用してください。GPAクエリはすべてのプログラムアカウントをスキャンするため、メインネットでは遅くコストがかかる可能性があります。DASはより高速でオフチェーンメタデータも含むインデックスクエリを提供します。互換性のあるエンドポイントについてはDAS RPCプロバイダーを参照してください。

Assetのオフチェーンメタデータはどうやって取得しますか？

uriフィールドにメタデータURLが含まれています。別途取得してください：

const asset = await fetchAsset(umi, assetAddress)
const metadata = await fetch(asset.uri).then(res => res.json())

複数のCollectionにまたがってAssetを取得できますか？

単一のクエリでは不可能です。各CollectionのAssetを別々に取得して結果を組み合わせるか、DASでカスタムフィルターを使用してください。

skipDerivePluginsはなぜ便利ですか？

デフォルトでは、fetchAssetはCollectionレベルのプラグインをAssetに継承します。skipDerivePlugins: trueに設定するとこのステップをスキップし、Assetレベルのプラグインのみを返します。Asset自身のプラグインのみが必要な場合や、より高速なフェッチが必要な場合に使用してください。

大きな結果セットをページネーションするにはどうすればよいですか？

GPA関数は組み込みのページネーションをサポートしていません。大規模なコレクションの場合は、pageとlimitパラメータをサポートするDASを使用するか、クライアントサイドのページネーションを実装してください。

用語集