2021-1-19文章

从2021年1月18日星期一开始，Decentraland LAND API（或Marketplace API）的新版本2.0可用。完整的文档可在GitHub上的API仓库中找到，但您可以在此博客文章中找到有关更改的概述，并且Decentraland Docs中已添加了迁移指南。

2.0版引入了几个新的终结点，可为需要访问有关LAND宗地和遗产的描述性数据的任何建筑工具返回更容易消化的信息。继续阅读有关v2的概述，与v1的堆叠方式，以及v1中不推荐使用的内容（以及存在的内容）。

如果您不是熟悉LAND NFT的开发人员，您可能想知道该API的哪个版本都适用。简而言之，每个LAND地块或地产都拥有一组描述性元数据。诸如Marketplace之类的工具需要访问此数据，以显示LAND的任何特定部分的所有相关详细信息。

例如，LAND可以具有不同的类型：它可以是未拥有的或拥有的。它可以专用于广场或社区区域，也可以是公共道路的一部分。

所有者也可以为LAND指定一个描述性名称，或者所有者可以在LAND的详细信息中包含自己的名称。显然，每个地块还必须具有x和y坐标，以标记其在创世纪城市地图上的位置。现在，这些只是可通过LAND API访问的最重要的LAND元数据的几个示例，但是Marketplace和其它平台，如OpenSea，需要访问所有这些信息。

无论您是在构建市场还是要绘制自己的Decentraland地图，任何需要访问LAND和Estates的易于分析和可消化的数据的构建工具都可以使用LAND API。

首先，重要的是，任何API中的每个端点都必须以一致的方式返回数据。使用具有多个返回相同或相关数据但格式不同的端点的API编写代码可能会令人沮丧。

假设您希望以字符串形式接收LAND类型，但会得到一个可以任意映射到类型的整数。您应该如何在代码中处理此问题？

LAND API的版本1包含了一些这样的不一致之处，但是自文档中可以看到，版本2.0至今已对所有这些数据类型进行了标准化。

此外，旧的v1终结点返回的对象通常很大，使得API调用执行缓慢，并且生成的数据非常难以解析。第2版简化了这些对象，使API的性能更高，并且更易于与您的代码集成。

最后，并非可以通过LAND API的v1渲染Genesis City内的所有地块。具体来说，Aetheria社区区域包含另外2,000个未在旧API中公开的包裹。现在，API的v2都支持这些包裹，从而构成了完整而全面的Atlas。

v1和v2之间的最大区别之一是GET / tiles。 v1端点将返回以下格式的对象：

{
  type: number
  x: number
  y: number
  owner?: string
  estate_id?: string
  name?: string
  top?: number
  left?: number
  topLeft?: number
  price?: number
}

新的GET / v2 / tiles端点返回以下对象：

{
  id: string
  x: number
  y: number
  type: 'owned' | 'unowned' | 'plaza' | 'road' | 'district'
  top: boolean
  left: boolean
  topLeft: boolean
  updatedAt: number
  name?: string
  owner?: string
  estateId?: string
  tokenId?: string
  price?: number
}

现在，此端点不仅返回更多数据，例如包裹的ID，最新更新时间戳和令牌ID，而且还返回比整数更易读的字符串形式的数据。

您可以使用以下参数过滤结果：

参数：x1,y1,x2,y2
说明：在以给定坐标为边界的地图区域内请求宗地。 示例：/v2/tiles?x1=10&y1=10&x2=20&y2=20

参数：include 说明：仅使用指定的信息请求宗地数据。 示例：/v2/tiles?include=type,top,left,topLeft

参数：exclude 说明：在结果中排除特定字段。 示例：/v2/tiles?exclude=updatedAt,tokenId

由于此端点（以及 v2 中的类似端点）返回的数据更复杂且可自定义，因此新 API 使用的端点总数更少，性能更高。

您会注意到，某些旧的v1端点在v2中没有对应的端点。这是因为现在可以通过The Graph更轻松地访问此数据：该索引协议提供了开放的API（称为“subgraphs”），您可以使用这些API访问以太坊或IPFS等web3网络中存储的数据。

Graph是对以前的v1 API的重大改进，因为它提供了LAND数据，而无需集中式专有索引服务器。通过使用共享和开放的网络，The Graph为dApp提供了一种更稳定和分散的Web3协议数据查询方式。

通过访问The Graph的Decentraland游乐场，了解如何在Graph中查询有关Decentraland的信息。在这里，您可以找到有关如何格式化请求的信息以及可以进行一些实验性调用的控制台！

这是一个简单的示例，可帮助您熟悉如何查询图表格式：

查找当前出售的五种最便宜的包裹：

该查询返回按价格排序列出的5个最便宜的LAND NFT。类别已设置为“包裹”，订单状态为“未清”，且订单的到期日设置为大于“现在”，以确保所有列出的销售均未到期。

注意：“now”表示为Unix时间戳，可在此处找到。

查询：

{
  nfts(first: 5, orderBy: searchOrderPrice, where:{ category: parcel, searchOrderStatus: open, searchOrderExpiresAt_gt: 1611082372 }) {
    parcel {
      x,
      y
    }
    activeOrder {
      price
    }
  }
}

结果：

{
  "data": {
    "nfts": [
      {
        "activeOrder": {
          "price": "7950000000000000000000"
        },
        "parcel": {
          "x": "82",
          "y": "-21"
        }
      },
      {
        "activeOrder": {
          "price": "7950000000000000000000"
        },
        "parcel": {
          "x": "83",
          "y": "-21"
        }
      },
      {
        "activeOrder": {
          "price": "7950000000000000000000"
        },
        "parcel": {
          "x": "84",
          "y": "-21"
        }
      },
      {
        "activeOrder": {
          "price": "8000000000000000000000"
        },
        "parcel": {
          "x": "-74",
          "y": "-47"
        }
      },
      {
        "activeOrder": {
          "price": "8000000000000000000000"
        },
        "parcel": {
          "x": "-74",
          "y": "-46"
        }
      }
    ]
  }
}

您会注意到价格以wei表示。只需将小数点移到18位以上即可获得实际的标价。以太坊区块链上存储的所有数字都存储在wei中，以帮助保持较小数字的精度。

在深入了解多汁的细节之前，应注意，原始v1 / map端点仍受支持，不会被弃用。这是社区中使用最广泛的端点，因此避免不必要的重大更改很重要。

有关旧API如何与2.0版堆叠的完整摘要，请访问文档。在这里，您将找到一份迁移指南，其中说明了哪些v1端点已替换为v2，哪些端点已被Graph查询替换，以及哪些端点将完全不受支持。

在Twitter上关注Decentraland，以了解World Explorer、Builder、Marketplace、SDK和DAO中所有最新的开源、社区版本！

选择您常用的频道加入与我们联系，关注Decentraland(MANA)的最新动态

DCL基金会全球社区： 【Official Website】 【Telegram】 【Blog】 【Twitter】 【Discord】

DCL中文社区： 【电报群】 【推特】 【微博】 【微信群】请加微信ID ChinWaan 【微信公众号】manalandcn

2021-1-19文章

从2021年1月18日星期一开始，Decentraland LAND API（或Marketplace API）的新版本2.0可用。完整的文档可在GitHub上的API仓库中找到，但您可以在此博客文章中找到有关更改的概述，并且Decentraland Docs中已添加了迁移指南。

2.0版引入了几个新的终结点，可为需要访问有关LAND宗地和遗产的描述性数据的任何建筑工具返回更容易消化的信息。继续阅读有关v2的概述，与v1的堆叠方式，以及v1中不推荐使用的内容（以及存在的内容）。

如果您不是熟悉LAND NFT的开发人员，您可能想知道该API的哪个版本都适用。简而言之，每个LAND地块或地产都拥有一组描述性元数据。诸如Marketplace之类的工具需要访问此数据，以显示LAND的任何特定部分的所有相关详细信息。

例如，LAND可以具有不同的类型：它可以是未拥有的或拥有的。它可以专用于广场或社区区域，也可以是公共道路的一部分。

所有者也可以为LAND指定一个描述性名称，或者所有者可以在LAND的详细信息中包含自己的名称。显然，每个地块还必须具有x和y坐标，以标记其在创世纪城市地图上的位置。现在，这些只是可通过LAND API访问的最重要的LAND元数据的几个示例，但是Marketplace和其它平台，如OpenSea，需要访问所有这些信息。

无论您是在构建市场还是要绘制自己的Decentraland地图，任何需要访问LAND和Estates的易于分析和可消化的数据的构建工具都可以使用LAND API。

首先，重要的是，任何API中的每个端点都必须以一致的方式返回数据。使用具有多个返回相同或相关数据但格式不同的端点的API编写代码可能会令人沮丧。

假设您希望以字符串形式接收LAND类型，但会得到一个可以任意映射到类型的整数。您应该如何在代码中处理此问题？

LAND API的版本1包含了一些这样的不一致之处，但是自文档中可以看到，版本2.0至今已对所有这些数据类型进行了标准化。

此外，旧的v1终结点返回的对象通常很大，使得API调用执行缓慢，并且生成的数据非常难以解析。第2版简化了这些对象，使API的性能更高，并且更易于与您的代码集成。

最后，并非可以通过LAND API的v1渲染Genesis City内的所有地块。具体来说，Aetheria社区区域包含另外2,000个未在旧API中公开的包裹。现在，API的v2都支持这些包裹，从而构成了完整而全面的Atlas。

v1和v2之间的最大区别之一是GET / tiles。 v1端点将返回以下格式的对象：

{
  type: number
  x: number
  y: number
  owner?: string
  estate_id?: string
  name?: string
  top?: number
  left?: number
  topLeft?: number
  price?: number
}

新的GET / v2 / tiles端点返回以下对象：

{
  id: string
  x: number
  y: number
  type: 'owned' | 'unowned' | 'plaza' | 'road' | 'district'
  top: boolean
  left: boolean
  topLeft: boolean
  updatedAt: number
  name?: string
  owner?: string
  estateId?: string
  tokenId?: string
  price?: number
}

现在，此端点不仅返回更多数据，例如包裹的ID，最新更新时间戳和令牌ID，而且还返回比整数更易读的字符串形式的数据。

您可以使用以下参数过滤结果：

参数：x1,y1,x2,y2
说明：在以给定坐标为边界的地图区域内请求宗地。 示例：/v2/tiles?x1=10&y1=10&x2=20&y2=20

参数：include 说明：仅使用指定的信息请求宗地数据。 示例：/v2/tiles?include=type,top,left,topLeft

参数：exclude 说明：在结果中排除特定字段。 示例：/v2/tiles?exclude=updatedAt,tokenId

由于此端点（以及 v2 中的类似端点）返回的数据更复杂且可自定义，因此新 API 使用的端点总数更少，性能更高。

您会注意到，某些旧的v1端点在v2中没有对应的端点。这是因为现在可以通过The Graph更轻松地访问此数据：该索引协议提供了开放的API（称为“subgraphs”），您可以使用这些API访问以太坊或IPFS等web3网络中存储的数据。

Graph是对以前的v1 API的重大改进，因为它提供了LAND数据，而无需集中式专有索引服务器。通过使用共享和开放的网络，The Graph为dApp提供了一种更稳定和分散的Web3协议数据查询方式。

通过访问The Graph的Decentraland游乐场，了解如何在Graph中查询有关Decentraland的信息。在这里，您可以找到有关如何格式化请求的信息以及可以进行一些实验性调用的控制台！

这是一个简单的示例，可帮助您熟悉如何查询图表格式：

查找当前出售的五种最便宜的包裹：

该查询返回按价格排序列出的5个最便宜的LAND NFT。类别已设置为“包裹”，订单状态为“未清”，且订单的到期日设置为大于“现在”，以确保所有列出的销售均未到期。

注意：“now”表示为Unix时间戳，可在此处找到。

查询：

{
  nfts(first: 5, orderBy: searchOrderPrice, where:{ category: parcel, searchOrderStatus: open, searchOrderExpiresAt_gt: 1611082372 }) {
    parcel {
      x,
      y
    }
    activeOrder {
      price
    }
  }
}

结果：

{
  "data": {
    "nfts": [
      {
        "activeOrder": {
          "price": "7950000000000000000000"
        },
        "parcel": {
          "x": "82",
          "y": "-21"
        }
      },
      {
        "activeOrder": {
          "price": "7950000000000000000000"
        },
        "parcel": {
          "x": "83",
          "y": "-21"
        }
      },
      {
        "activeOrder": {
          "price": "7950000000000000000000"
        },
        "parcel": {
          "x": "84",
          "y": "-21"
        }
      },
      {
        "activeOrder": {
          "price": "8000000000000000000000"
        },
        "parcel": {
          "x": "-74",
          "y": "-47"
        }
      },
      {
        "activeOrder": {
          "price": "8000000000000000000000"
        },
        "parcel": {
          "x": "-74",
          "y": "-46"
        }
      }
    ]
  }
}

您会注意到价格以wei表示。只需将小数点移到18位以上即可获得实际的标价。以太坊区块链上存储的所有数字都存储在wei中，以帮助保持较小数字的精度。

在深入了解多汁的细节之前，应注意，原始v1 / map端点仍受支持，不会被弃用。这是社区中使用最广泛的端点，因此避免不必要的重大更改很重要。

有关旧API如何与2.0版堆叠的完整摘要，请访问文档。在这里，您将找到一份迁移指南，其中说明了哪些v1端点已替换为v2，哪些端点已被Graph查询替换，以及哪些端点将完全不受支持。

在Twitter上关注Decentraland，以了解World Explorer、Builder、Marketplace、SDK和DAO中所有最新的开源、社区版本！

选择您常用的频道加入与我们联系，关注Decentraland(MANA)的最新动态

DCL基金会全球社区： 【Official Website】 【Telegram】 【Blog】 【Twitter】 【Discord】

DCL中文社区： 【电报群】 【推特】 【微博】 【微信群】请加微信ID ChinWaan 【微信公众号】manalandcn