获取 Asset

本指南展示如何使用 Metaplex Core SDK 从 Solana 区块链获取 Core Asset 和 Collection。检索单个 Asset，按所有者或集合查询，或使用 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 · 按所有者 · 按集合 · 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

可以使用 getProgramAccounts（GPA）调用获取多个 Asset，这在 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)

按集合获取 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)

按更新权限获取 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 - 数字资产标准 API

如果您使用启用了 DAS 的 RPC，您将能够利用索引 Asset 进行快速获取和数据检索。 DAS 将索引从元数据、链下元数据、集合数据、插件（包括 Attributes）等所有内容。要了解更多关于 Metaplex DAS API 的信息，您可以点击这里。除了通用的 DAS SDK，还创建了一个针对 MPL Core 的扩展，它直接返回正确的类型，以便进一步与 MPL Core SDK 一起使用。它还自动派生从集合继承的资产中的插件，并提供 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 vs mainnet）
• 账户存在且是 Core Asset（不是 Token Metadata）

RPC rate limit exceeded

GPA 查询可能很昂贵。解决方案：

• 使用启用 DAS 的 RPC 进行索引查询
• 添加分页以限制结果
• 在适当的地方缓存结果

注意事项

• fetchAsset 返回完整的 Asset，包括从 Collection 派生的插件
• 设置 skipDerivePlugins: true 仅获取 Asset 级别的插件（更快）
• GPA 查询（fetchAssetsByOwner 等）在主网上可能很慢——优先使用 DAS
• DAS 返回链下元数据；SDK 获取函数仅返回链上数据

快速参考

获取函数

DAS 与 GPA 比较

常见问题

获取多个 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，或实现客户端分页。

术语表