跳转到主要内容

​
如何集成 Search Posts 端点

本页介绍在将 recent search 或 full archive search 端点集成到你的系统时需要了解的多种工具和关键概念。我们将本页分为以下部分：

​
实用工具

在开始探讨一些关键概念之前，我们建议你使用以下任一工具或代码示例来开始测试这些端点的功能。

​
代码示例

想用你常用的编程语言，通过一些示例代码来对这些端点进行设置吗？我们在 GitHub 页面提供了多种可作为起点的代码示例，包括 Python 客户端和 Ruby 客户端。

​
库

利用我们提供的众多社区第三方库来帮助您快速上手。通过查找相应的版本标签，您可以找到适用于 v2 端点的库。

​
Postman

Postman 是一款出色的工具，可用于测试这些端点。每个 Postman 请求都包含该端点的所有参数，帮助你快速了解可用项。要了解更多关于我们 Postman 集合的内容，请访问我们的使用 Postman页面。  

​
核心概念

​
身份验证

所有 X API v2 端点都要求你使用一组凭据（也称为密钥与令牌）对请求进行身份验证。你可以使用 OAuth 1.0a User Context、OAuth 2.0 App-Only，或 OAuth 2.0 授权码模式（含 PKCE）来对最近搜索端点的请求进行身份验证。使用完整归档搜索端点时，你必须使用 OAuth 2.0 App-Only。 OAuth 2.0 App-Only 仅要求你在请求中携带一个 OAuth 2.0 App Access Token。你可以直接在开发者 App 中生成一个 App Access Token，或使用 POST oauth2/token 端点来生成。 OAuth 1.0a User Context 要求你使用 API Keys、用户访问令牌，以及少量其他参数来创建授权标头，然后随请求一同发送。访问令牌必须与你代表其发起请求的用户相关联。如果你希望为另一位用户生成一组访问令牌，则该用户必须通过三方 OAuth 流程授权你的 App。 请注意，OAuth 1.0a 的使用可能较为复杂。如果你不熟悉此身份验证方法，建议使用库、Postman 等工具，或使用 OAuth 2.0 来为请求进行身份验证。如果你希望从这些端点请求某个帖子或私有指标，你需要使用 OAuth 1.0a User Context 或 OAuth 2.0 授权码模式（含 PKCE），以确保你拥有该内容所有者授予的适当权限。 OAuth 2.0 授权码模式（含 PKCE） 允许对应用的 scope 进行更精细的控制，并支持跨多设备的授权流程。OAuth 2.0 允许你选择特定的细粒度 scope，从而代表用户获取特定权限。 要在你的 App 中启用 OAuth 2.0，你必须在开发者门户的 App 设置部分的身份验证设置中将其启用。
请注意如果你请求以下字段，则需要使用 OAuth 1.0a User Context 或 OAuth 2.0 Authorization Code：
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics

​

开发者门户、Project 和开发者 App 要使用任何 X API v2 端点，您必须先注册开发者账户，在账户下创建一个 Project，并在该 Project 中创建一个开发者 App。该开发者 App 中的密钥与令牌可用于这些搜索端点。 您可以使用任一访问级别的 Project 的密钥与令牌来调用“近期搜索”端点。但若要调用“完整存档搜索”端点，则需要使用访问级别为 Pro 或 Enterprise 的 Project。若您拥有Enterprise 访问权限，将可使用更多功能，包括更多可用运算符和更长的查询长度。  

​
速率限制

每天都有成千上万的开发者向 X API 发起请求。为帮助管理请求量，我们在每个端点设置了速率限制，以限制每位开发者代表某个应用或某个已认证用户所能发起的请求数量。 根据所使用的身份验证方法不同，这些端点适用的速率限制也不同。应用级速率限制适用于使用 OAuth 2.0 App-Only 发起请求的应用；而用户级速率限制适用于代表特定授权用户、使用 OAuth 1.0a User Context 或 OAuth 2.0 授权码模式（含 PKCE）发起的请求。这两类速率限制均基于 15 分钟时间窗口内的请求频率。 例如，一个使用 OAuth 2.0 App-Only 向“近期搜索”端点发起请求的应用，可在 15 分钟内发出 450 次请求（包括分页请求）。同一应用在相同的 15 分钟时间窗口内，若有两个不同的已认证用户（使用 OAuth 1.0a User Context 或 OAuth 2.0 授权码模式〔含 PKCE〕），则可为每个已认证用户对该“近期搜索”端点最多发出 180 次请求（包括分页请求）。  

​
字段与 expansions

X API v2 允许你使用字段和expansions精确选择希望从 API 返回的数据。expansions 参数可将负载中被引用的对象展开。例如，此端点允许你通过 expansions 参数请求投票、地点、媒体等对象。 字段参数允许你精确指定希望接收的各类数据对象中的字段。默认情况下，这些端点返回的主要帖子对象包含 id 和 text 字段（对于该功能上线后创建的帖子，此外还包括 edit_history_tweet_ids）。若要接收诸如 author_id 或 public_metrics 等其他字段，你需要通过字段参数明确请求。一些在集成中值得考虑的重要字段包括投票数据、指标、帖子注释以及会话 ID。 我们已在X API v2 数据字典中添加了如何将字段与 expansions 一起使用的指南。  

​
指标

X API v2 端点允许你直接从返回对象中请求指标，前提是在请求中传递相应的字段。 与帖子指标相关存在一些限制，尤其涉及用户隐私和以下响应字段：
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
上述字段包含私有指标数据。这意味着在使用“近期搜索”端点时，你必须获得帖子发布者的授权，才能代表其检索这些数据；也就是说，你必须使用 OAuth 1.0a User Context。由于此身份验证方式仅能用于近期搜索，你无法通过“完整存档搜索”端点获取这些指标。 例如，要获取用户 ID 1234 的帖子所对应的 non_public_metrics，你需要在请求中包含与该用户关联的访问令牌。你可以通过使用三方 OAuth 流程让用户授权你的应用，并获取与其关联的一组访问令牌。 所有 non_public_metrics、organic_metrics 和 promoted_metrics 仅适用于最近 30 天内创建的帖子。这意味着当你请求上述字段时，结果会自动仅包含最近 30 天内的帖子。 如果请求了上述字段，则只会返回由已认证用户创作的帖子，其他所有帖子将返回错误消息。  

​
构建搜索查询

这些端点的核心在于使用单个搜索查询来筛选交付给你的帖子。查询由用于匹配帖子和用户属性的运算符构成，例如消息关键词、话题标签（hashtag）和 URL。你可以通过布尔逻辑与括号将运算符组合为查询，以进一步精确匹配行为。 你可以参阅我们的指南：如何构建查询了解更多。 这些端点使用分页以便更快返回响应。当结果数量超过单个响应可返回的上限时（近期搜索最多 100 条帖子，完整归档搜索最多 500 条），需要进行分页。使用 max_results 参数指定每页返回的结果数量，并使用 pagination_token 参数获取下一页结果。你可以查阅我们的分页指南了解更多信息。

​
帖子上限

无论分页与否，Search Posts 端点在每个自然月可返回的帖子数量都有上限。 无论你使用哪个搜索端点，返回的帖子都会计入项目级的帖子上限。用量会显示在开发者门户中，“月份”从你的订阅续费日开始，续费日可在开发者门户仪表板上查看。 帖子编辑 符合编辑条件的帖子在原始帖子发布后 30 分钟内最多可编辑五次。搜索端点始终返回帖子的最新版本。如果你只请求发布于 30 分钟之前的帖子，你将始终收到该帖子的最终版本。不过，如果你的用例接近实时，并在查询最近 30 分钟内发布的帖子，这些帖子在你接收后可能会被编辑。你可以通过搜索或 Post Lookup 端点重新回填这些帖子，以确认其最终状态。要了解帖子编辑的工作原理，请参阅帖子编辑基础页面。   后续步骤 向 Search Posts 端点发起你的第一个请求 在我们的 API 参考页面查看完整的参数、字段等列表 获取支持或排查错误