跳转到主要内容

​
开始使用 users lookup 端点

本快速入门指南将帮助你通过 Postman，使用一组指定的 fields 向 users lookup 端点发出第一个请求。 如果你想查看不同语言的示例代码，请访问我们的 X API v2 sample code GitHub 代码库。

​
前提条件

完成本指南需要一组用于对请求进行认证的 keys and tokens。你可以按照以下步骤生成这些 keys 和 tokens：
  • 注册开发者账户 并通过审核。
  • 在开发者门户中创建一个 Project 以及关联的 developer App。
  • 前往你的应用的“Keys and tokens”页面生成所需的凭证。请确保将所有凭证安全保存。

​
构建用户查询请求的步骤

​
第一步：选择工具或库

有多种工具、代码示例和库可用于向该端点发起请求，但为简化流程，我们将在此使用 Postman。 要将 X API v2 的 Postman 集合加载到你的环境中，请点击下方按钮：
在你已在 Postman 中加载 X API v2 集合后，前往 GET /users/by 端点。  

​
步骤二：为请求进行认证

要正确向 X API 发起请求，你需要先确认自己具备权限。为此，该端点要求你使用 App only、OAuth 2.0 授权码（PKCE） 或 OAuth 1.0a 用户上下文 等认证方式对请求进行认证。 为简化说明，我们在本次请求中使用 App only；但如果你希望请求私有的 metrics 或用户数据，则需要改用上述其他认证方式之一。 使用 App only 时，你需要将密钥和令牌，尤其是 App Access Token（也称 App only Bearer Token）添加到 Postman。你可以在 Postman 右上角选择名为“X API v2”的环境，并将密钥和令牌填入 “initial value” 和 “current value” 字段（点击环境下拉菜单旁的“眼睛”图标）。 若配置正确，这些变量会自动注入到请求的 authorization 选项卡中。  

​
步骤三：确定并指定你要检索的用户

你必须在请求中指定一个或一组希望返回的用户。根据所用的用户端点不同，你可以传递用户 id 或用户名。在本示例中，我们将使用 GET /users/by 端点。该端点允许你在单个请求中传递多个用户名（相对于 single-ID、multi-ID 和 single-username 端点），并通过 usernames 查询参数传入一组用户名。 用户名即账号在个人资料页 URL 中的账号标识（handle）。例如，以下账号的用户名是 XDevelopers。 https://x.com/XDevelopers 在 Postman 中，转到“Params”选项卡，将该用户名或一个用逗号分隔的用户名列表输入到 username 参数的“Value”列中，确保用户名与逗号之间不包含空格。
KeyValue
usernameXDevelopers,API,adsapi

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

如果你在第三步后点击“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”表中添加以下键值对：
KeyValueReturned fields
user.fieldscreated_atuser.created_at
expansionsauthor_idtweet.id, tweet.text
tweet.fieldscreated_atincludes.users.created_at
现在你应该会在“Send”按钮旁边看到以下 URL： 
      https://api.x.com/2/users/by?usernames=twitterdev,twitterapi,adsapi&user.fields=created_at&expansions=pinned_tweet_id&tweet.fields=author_id,created_at

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

完成所有设置后，点击“Send”按钮，您将收到如下响应： 
{
  "data": [
    {
      "created_at": "2013-12-14T04:35:55.000Z",
      "id": "2244994945",
      "name": "X Dev",
      "pinned_tweet_id": "1255542774432063488",
      "username": "TwitterDev"
    },
    {
      "created_at": "2007-05-23T06:01:13.000Z",
      "id": "6253282",
      "name": "X API",
      "username": "TwitterAPI"
    },
    {
      "created_at": "2013-02-27T20:01:12.000Z",
      "id": "1225933934",
      "name": "X Ads API",
      "username": "AdsAPI"
    }
  ],
  "includes": {
    "tweets": [
      {
        "author_id": "2244994945",
        "created_at": "2020-04-29T17:01:38.000Z",
        "id": "1255542774432063488",
        "text": "在这个前所未有的时期,X 上发生的事情可以帮助全球更好地了解疫情并做出应对。\n\n我们正在推出免费的 COVID-19 流式端点,让符合条件的开发者和研究人员能够实时研究公共对话。https://t.co/BPqMcQzhId"
      }
    ]
  }
}