快速开始

​

开始使用 blocks 查询端点

本快速入门指南将帮助你使用 Postman 向 blocks 查询端点发出你的第一个请求。

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

​

前提条件

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

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

​

构建封禁查询请求的步骤

​

第一步：选择工具或库

有多种工具、代码示例和库可用于向该端点发起请求，但这里我们将使用 Postman 来简化操作。

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

将 X API v2 添加到 Postman

在你将 X API v2 集合加载到 Postman 后，进入 “Blocks” 文件夹，并选择 “Blocks Lookup”。  

​

第二步：对请求进行认证

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

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

你需要将密钥和令牌——具体包括 API Key、API Secret Key、OAuth 1.0a user Access Token，以及 OAuth 1.0a user Access Token Secret——添加到 Postman。你可以在 Postman 右上角选择名为“X API v2”的环境，并将密钥和令牌填入“initial value”和“current value”字段（点击环境下拉菜单旁的眼睛图标）以完成此操作。

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

​

第三步：指定用户

使用此端点时，你必须指定你的用户 ID，或某个已认证用户的用户 ID，才能查看你已屏蔽的对象。

在 Postman 中，进入“Params”选项卡，将该用户的用户名输入到 id 路径变量的“Value”列（位于本节底部），并确保用户名前后不包含空格。  

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

​

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

如果在第三步后点击“Send”按钮，您的响应将返回默认的 user object 字段：id、name 和 username。

如果您希望在 id、name 和 username 之外获取更多字段，需要在请求中通过 fields 和/或 expansions 参数指定这些字段。

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

1. 主用户对象中的额外 user.created_at 字段。
2. 返回用户所关联的置顶 Post 对象的默认字段：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 的 URL：

      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 支持"
    },
    {
      "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：Early Access 已推出\n\n我们今天宣布对新版 Twitter API 的首批端点开放 Early Access！\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 个用户，从而减少分页次数。