近期搜索

​

快速开始使用 recent search 端点

本快速入门指南将帮助你使用 Postman，针对 recent search 端点发出首个请求，并指定一组 fields。

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

​

先决条件

要完成本指南，你需要一组 keys and tokens 来对请求进行认证。你可以通过以下步骤生成这些 keys 和 tokens：

• 注册开发者账户 并获得批准。
• 在开发者门户中创建一个 Project 以及关联的 开发者应用。
• 前往你的应用的 “Keys and tokens” 页面以生成所需的凭证。请确保将所有凭证妥善保存在安全位置。

​

构建近期搜索请求的步骤

第一步：选择工具或库

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

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

将 X API v2 添加到 Postman

在 Postman 中加载好 X API v2 集合后，前往 Search Posts > Recent search request。

第二步：为请求进行认证

要正确向 X API 发起请求，你需要先验证访问权限。针对该端点，你必须使用 OAuth 2.0 App-Only、OAuth 2.0 Authorization Code with PKCE 或 OAuth 1.0a User Context 进行认证。

为简便起见，本示例将使用 OAuth 2.0 App-Only。但如果你需要请求私有metrics 或私密的 Posts，则需要使用上述其他认证方式之一。 

使用 OAuth 2.0 App-Only 时，你必须将密钥和令牌添加到 Postman，具体为 App Access Token（亦称 App-only Bearer Token）。你可以在 Postman 右上角选择名为“X API v2”的环境，并将密钥和令牌填入 “initial value” 和 “current value” 字段（点击环境下拉菜单旁的“眼睛”图标）完成设置。

配置正确后，这些变量会自动注入到该请求的 Authorization 选项卡中。  

第三步：创建搜索查询

每个近期搜索请求需要一个搜索查询。本示例将使用一个匹配 @XDevelopers 账号发布的 Posts 的查询。对此，我们使用 from 运算符并将其设置为 XDevelopers（不区分大小写）：

from:XDevelopers

在 Postman 中，前往 “Params” 选项卡，将该 ID，或用逗号分隔的一串 Post ID，填入 ids 参数的 “Value” 列。

Key	Value	Description
query	from:XDevelopers	提交给近期搜索端点的搜索查询

第四步：确定并指定希望返回的字段

如果在第三步后点击 “Send” 按钮，你会在响应中收到默认的Post 对象字段：id、text 和 edit_history_tweet_ids。如果希望返回除 id、text 和 edit_history_tweet_ids 之外的更多字段，需要在请求中通过 field 和/或 expansion 参数进行指定。

在本练习中，我们将请求来自不同对象的四组字段：

1. 默认的 Post 对象字段。
2. 主体 Post 对象中的附加字段 tweet.created_at。
3. 返回的 Posts 所关联作者的用户对象的默认字段。
4. 关联用户对象中的附加字段 user.description。

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

Key	Value	Returned fields
tweet.fields	created_at	tweets.created_at
expansions	author_id	includes.users.id, includes.users.name, includes.users.username
user.fields	description	includes.users.description

现在你应该会在 “Send” 按钮旁看到以下 URL：

https://api.x.com/2/tweets/search/recent?query=from:XDevelopers&tweet.fields=created_at&expansions=author_id&user.fields=created_at

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

完成所有设置后，点击“Send”按钮，您将会收到如下响应：

{
   "data": [
       {
           "author_id": "2244994945",
           "created_at": "2020-06-11T16:05:06.000Z",
           "id": "1271111223220809728",
           "text": "今晚收看 @jessicagarson 为我们演示如何在 R 中运行您喜爱的 Python 包。🍿\n\n了解如何将两种强大的编程语言结合用于数据科学,并查看使用 X 开发者实验室最近搜索端点的实际示例。https://t.co/v178oUZNuj"
       },
       {
           "author_id": "2244994945",
           "created_at": "2020-06-10T19:25:24.000Z",
           "id": "1270799243071062016",
           "text": "在我们构建新的 X API 的过程中,我们延长了几个 Labs v1 端点的弃用时间表。了解更多 📖 https://t.co/rRWaJYJgKk"
       },
       {
           "author_id": "2244994945",
           "created_at": "2020-06-09T18:08:47.000Z",
           "id": "1270417572001976322",
           "text": "注释帮助您更深入地了解 Tweet——它们甚至可以帮助您找到感兴趣的话题。🔬\n\n在本教程中,@suhemparack 向我们展示如何使用注释和过滤流端点查找与 COVID-19 相关的 Tweet。\n\n了解您也可以如何做到。⤵️\nhttps://t.co/qwVOgw0zSV"
       }
   ],
   "includes": {
       "users": [
           {
               "description": "X #DevRel 团队的官方声音,是您获取 X API 更新、新闻和活动的官方来源。\n\n#BlackLivesMatter",
               "id": "2244994945",
               "name": "X Developers",
               "username": "XDevelopers"
           }
       ]
   },
   "meta": {
       "newest_id": "1271111223220809728",
       "oldest_id": "1270417572001976322",
       "result_count": 3
   }
}

下一步

使用 API 参考自定义请求

查看查询运算符完整列表

查看这些端点的示例代码