快速入门

​

开始使用 blocks lookup endpoint

本快速上手指南将帮助你使用 Postman 向 blocks lookup endpoint 发出首个请求。

如果你希望查看不同语言的示例代码，请访问我们的 X API v2 sample code GitHub 仓库。

​

先决条件

要完成本指南，你需要一组用于对请求进行身份验证的 密钥和令牌。你可以按照以下步骤生成这些密钥和令牌：

• 注册开发者账户 并通过审核。
• 在开发者门户中创建一个 Project 以及关联的 开发者 App。
• 前往你的 App 的“Keys and tokens”页面以生成所需的凭证。请确保将所有凭证保存在安全的位置。

​

构建拉黑查询请求的步骤

​

第一步：从工具或库入手

有多种工具、代码示例和库可用于向此 endpoint 发送请求，但这里我们将使用 Postman 来简化流程。

要将 X API v2 的 Postman 集合导入到你的环境中，请点击以下按钮：

将 X API v2 添加到 Postman

在你将 X API v2 集合导入 Postman 后，前往“Blocks”文件夹并选择“Blocks Lookup”。  

​

第二步：为请求进行身份验证

要正确向 X API 发起请求，你需要先确认自己具备相应权限。对于此 endpoint，你必须使用 OAuth 1.0a 用户上下文 或 OAuth 2.0 授权码模式（Authorization Code）配合 PKCE 对请求进行身份验证。

在本示例中，我们将使用 OAuth 1.0a 用户上下文。

你必须将你的 密钥和令牌——具体包括 API Key、API Secret Key、OAuth 1.0a 用户 access token，以及 OAuth 1.0a 用户 Access Token Secret——添加到 Postman。你可以在 Postman 右上角选择名为“X API v2”的 environment，并将你的 密钥和令牌 添加到“initial value”和“current value”fields（点击 environment 下拉菜单旁的眼睛图标）中。

如果设置正确，这些变量将会自动填充到请求的 authorization 选项卡中。  

​

第三步：指定用户

使用此 endpoint 时，你必须指定你的用户 ID，或已通过身份验证的用户的用户 ID，才能查看你已屏蔽的账号。

在 Postman 中，转到“Params”选项卡，在该部分底部的 id 路径变量的“Value”列中输入该用户名，确保用户名前后没有空格。  

Key	Value
id	（你的用户 ID）
max_results	5

​

第四步：确定并指定要检索的 fields

如果你在完成第三步后点击“Send”按钮，响应中将返回默认的用户对象字段：id、name 和 username。

如果你希望获取除 id、name 和 username 之外的其他字段，需要在请求中通过 fields 和/或 expansions 参数进行指定。

在本练习中，我们将从不同对象请求三组额外字段：

1. 主用户对象中的额外 user.created_at 字段。
2. 返回用户所关联的置顶 Posts 对象的默认字段：id 和 text。
3. 关联的 Post 对象中的额外 tweet.created_at 字段。

在 Postman 中，转到“Params”选项卡，并在“Query Params”表中添加以下键值对：

Key	Value	Returned fields
user.fields	created_at	user.created_at
expansions	pinned_tweet_id	tweet.id, tweet.text
tweet.fields	created_at	includes.tweets.created_at

现在，你应当会在“Send”按钮旁看到一个类似的 URL，其中包含你的用户 ID，而非 TwitterDev 的：

      https://api.x.com/2/users/2244994945/blocking?user.fields=created_at&expansions=pinned_tweet_id&tweet.fields=created_at

​

第五步：发起请求并查看响应

完成所有设置后，点击“Send”按钮，即可收到与下方示例响应类似的返回结果：

    {
  "data": [
    {
      "created_at": "2008-12-04T18:51:57.000Z",
      "id": "17874544",
      "username": "TwitterSupport",
      "name": "Twitter Support"
    },
    {
      "created_at": "2007-02-20T14:35:54.000Z",
      "id": "783214",
      "username": "Twitter",
      "name": "Twitter"
    },
    {
      "pinned_tweet_id": "1389270063807598594",
      "created_at": "2018-11-21T14:24:58.000Z",
      "id": "1065249714214457345",
      "username": "TwitterSpaces",
      "name": "Spaces"
    },
    {
      "pinned_tweet_id": "1293595870563381249",
      "created_at": "2007-05-23T06:01:13.000Z",
      "id": "6253282",
      "username": "XAPI",
      "name": "X API"
    }
  ],
  "includes": {
    "tweets": [
      {
        "created_at": "2021-05-03T17:26:09.000Z",
        "id": "1389270063807598594",
        "text": "现在，拥有 600 名或更多关注者的用户都可以主持 Space。\n\n根据我们的了解，这些账户由于拥有现有受众，很可能在主持方面有良好的体验。在将创建 Space 的功能开放给所有人之前，我们专注于几个方面。🧵"
      },
      {
        "created_at": "2020-08-12T17:11:04.000Z",
        "id": "1293595870563381249",
        "text": "X API v2：抢先体验版发布\n\n今天我们宣布了新 Twitter API 首批 endpoint 的抢先体验版！\n\n#TwitterAPI #EarlyAccess #VersionBump https://t.co/g7v3aeIbtQ"
      }
    ]
  }

​

第六步：对结果进行分页

你可能会注意到响应底部有一个 meta 对象。如果你收到了一个 next_token，这表示还有另一页可检索的结果。要获取下一页结果，你需要读取 next_token 字段的值，并将其作为额外的 pagination_token 参数的值添加到请求中。  

键	值
pagination_token	1D3PU6DRII9HEZZZ

添加该参数后发送请求时，由于我们在第三步将 max_results 设为 5，接下来的五条结果将随后续的负载返回。你可以持续重复此流程，直到返回所有结果；同时，你也可以使用 max_results 参数在每个请求中最多获取 1000 个用户，从而减少分页次数。