跳转到主要内容

​
如何集成 Timelines 端点

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

​
实用工具

在探讨一些关键概念之前，建议你先使用以下任一工具或代码示例来测试这些端点的功能。 代码示例 想用你偏好的编程语言，通过代码来对接这些端点吗？我们在 GitHub 页面提供了多种代码示例，可作为你的起点。 库 利用我们的众多社区第三方库快速上手。你可以通过查看相应的版本标签，找到适配 v2 端点的库。 Postman Postman 是一款非常适合用于测试这些端点的工具。每个 Postman 请求都包含所有路径和请求体参数，帮助你快速了解可用项。想了解我们的 Postman 集合，请访问使用 Postman页面。

​
关键概念

认证 所有 X API v2 端点都要求使用一组凭证（亦称 keys 和 tokens）对请求进行认证。你可以使用 OAuth 1.0a 用户上下文或 OAuth 2.0 授权码（PKCE）来对这些端点的请求进行认证。对于用户 Posts 时间线和用户提及时间线，你可以使用 OAuth 2.0 App-Only。 OAuth 1.0a 用户上下文要求你使用 API Keys、用户 Access Tokens，以及少量其他参数来创建授权标头，并随请求一同发送。Access Tokens 必须与被你代表发起请求的用户相关联。如果你想为其他用户生成一组 Access Tokens，该用户必须通过三方 OAuth 流程授权你的应用。  请注意，OAuth 1.0a 上手难度较高。如果你不熟悉此认证方法，建议使用库、使用 Postman 等工具，或使用 OAuth 2.0 来对请求进行认证。如果你想从这些端点请求某个 Post 或私有指标，你需要使用 OAuth 1.0a 用户上下文或 OAuth 2.0 授权码（PKCE），以确保你获得内容所有用户的相应权限。 OAuth 2.0 App-Only 仅要求你在请求中携带一个 OAuth 2.0 App Access Token。你可以直接在开发者应用中生成 App Access Token，或通过 POST oauth2/token 端点生成。它适用于用户 Posts 时间线或用户提及时间线。 OAuth 2.0 授权码（PKCE） 允许对应用的 scope 进行更细粒度的控制，并支持跨多设备的授权流程。OAuth 2.0 允许你选择特定的细粒度 scopes，以便代表用户获得相应权限。  要在你的应用中启用 OAuth 2.0，你必须在开发者门户的应用设置中的认证设置里将其开启。
请注意如果你请求以下fields，则需要使用 OAuth 1.0a 用户上下文或 OAuth 2.0 授权码： 
  • 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
开发者门户、Projects 和开发者应用 要使用任何 X API v2 端点，你必须先注册开发者账号，在该账号下设置一个 Project，并在该 Project 中创建一个开发者应用。你在该开发者应用中的 keys 和 tokens 适用于这些时间线端点。 速率限制 每天有成千上万的开发者向 X API 发起请求。为管理请求量，速率限制会应用于每个端点，限制每位开发者代表某个应用或某个已认证用户所能发起的请求数。  这些端点会根据所使用的认证方法应用不同的速率限制。应用级速率限制适用于使用 OAuth 2.0 App-Only 发起请求的应用；用户级速率限制适用于使用 OAuth 1.0a 用户上下文、代表特定授权用户发起的请求。这两类速率限制均基于 15 分钟窗口内的请求频率。 例如，一个使用 OAuth 2.0 App-Only 认证来调用这两个时间线端点的应用，可以在 15 分钟的时间窗口内，对用户 Post 时间线发起 1500 次请求（包括分页请求），对用户提及时间线发起 450 次请求（包括分页请求）。同一个应用在同一 15 分钟窗口内，若有两个不同的已授权用户（使用 OAuth 1.0a 用户上下文），则可对每个已认证用户分别向用户 Post 时间线发起 900 次请求（包括分页请求），并向用户提及时间线发起 180 次请求（包括分页请求）。 按时间倒序的主页时间线对每位用户的速率限制为每 15 分钟 180 次请求。使用此端点，你可以返回该时间线上过去 7 天内创建的每条 Post，以及最近的 800 条 Post（不论创建日期）。 Fields 和 expansions X API v2 允许你使用 fields 和 expansions 精确选择希望从 API 返回的数据。expansions 参数允许你展开负载中被引用的对象。例如，该端点允许你通过 expansions 参数请求 poll、place、media 等对象。 fields 参数允许你精确选择希望接收的各数据对象中的字段。默认情况下，这些端点返回的主 Post 对象包含 id 和 text 字段。若要接收其他字段（如 author_id 或 public_metrics），必须通过 fields 参数显式请求。你在集成中可能会考虑使用的一些重要字段包括投票数据、metrics、Post 注解以及会话 ID。 我们在 X API v2 数据字典中新增了关于如何同时使用 fields 和 expansions的指南。 Post 指标 X API v2 端点允许你直接从返回的 Post 对象中请求 Post 指标，前提是你在请求中传递了相应的 fields。 有关 Post 指标有一些需要注意的限制，尤其与用户隐私和以下响应字段相关：
  • 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
上述字段包含私有指标数据，这意味着当使用用户 Post 时间线端点时，你必须获得 Post 发布者的授权，方可代表其检索这些数据；也就是说，你必须使用 OAuth 1.0a User Context 或 OAuth 2.0 Authorization Code Flow with PKCE。 例如，若要在用户 ID 1234 的用户 Post 时间线上获取 non_public_metrics，你需要在请求中包含与该用户关联的访问令牌。你可以通过三方 OAuth 流程让用户授权你的应用，并获取与其关联的一组访问令牌。 如果你使用的是用户提及时间线，除非发出提及的作者已授权你的应用访问其私有指标数据，且你在使用 OAuth 1.0a 用户上下文发起请求时使用了该用户的访问令牌，否则上述字段不可用。 所有 non_public_metrics、organic_metrics 和 promoted_metrics 仅适用于过去 30 天内创建的 Posts。这意味着当你请求上述字段时，结果将自动限定为仅包含过去 30 天内的 Posts。 如果请求了上述字段，则只会返回由已认证用户创作的 Posts，其他所有 Posts 将返回错误信息。 分页 这些端点使用分页以加快响应速度。当结果多于单个响应可返回的数量时（时间线端点最多 100 条 Post），你需要进行分页。使用 max_results 参数指定每页返回的结果数量，使用 pagination_token 参数获取下一页结果。你可以查阅我们的分页指南了解更多信息。 筛选结果 这些端点包含多个参数，可用于筛选结果。使用 start_date 和 end_date 可以将结果限定到特定时间范围。如果你更倾向用 Post ID 来选择一组特定的 Post，可以使用 since_id 和 until_id。用户 Post 时间线还提供 exclude 参数，可从结果中移除转发（Retweets）和回复（Replies）。  Post 上限与返回的 Post 数量 用户 Post 时间线和用户提及（mention）时间线端点在单月内可返回的 Post 数量有限制。按时间倒序的主页时间线端点不受此限制。 无论你使用哪个时间线端点，返回的 Post 都会计入项目级别的Post 上限。使用量会显示在开发者门户中，“月度”周期从你的订阅续费日（见开发者门户仪表板）开始计算。  用户 Post 时间线端点仅返回用户时间线上最近的 3200 条 Post。即使将 start_time 和 end_time 设置为覆盖超过最近 3200 条 Post 的时间段，你也会收到成功响应，但不会返回 Post。 还需注意，如果在用户 Post 时间线请求中传入 excludes=replies，则仅会返回最近的 800 条 Post。 用户提及时间线端点仅返回最近的 800 条被提及的 Post。 按时间倒序的主页时间线端点返回最近的 3200 条 Post。 Post 编辑 符合编辑条件的 Post 可在原始 Post 发布后的 30 分钟内最多编辑五次。搜索端点将始终提供该 Post 的最新版本。如果你只请求发布于 30 分钟或更早之前的 Post，你将始终收到该 Post 的最终版本。然而，如果你有近实时的使用场景，并在查询最近 30 分钟内发布的 Post，这些 Post 可能会在你接收后被编辑。这些 Post 可以通过搜索或 Post Lookup 端点“再水化”（rehydrate）以确认其最终状态。要了解 Post 编辑的工作方式，请参阅编辑 Post 基础页面。   边界情况
  • 当在用户 Post 时间线端点请求超过 30 天之前的 Post 的非公开指标时，你可能会在响应中看到一个 next_token，但结果计数为 0。为避免此问题，请确保使用 non_public_metrics 参数请求的时间范围在最近 30 天内。此外，max_results 的最小值应为 10。这些做法可能有助于避免该情况，但仍可能发生。
  • 为未投放推广的 Post 请求推广指标时，将返回空响应，而非 Post 数据。我们的团队正在修复此问题。
  • 对于包含超过 140 个字符正文文本的转发（Retweet），text 字段会被截断，而不会返回完整的 Post 文本。短期解决方法是展开被引用的 Post，并从展开内容中获取完整文本。这是一个我们将在未来修复的缺陷。
下一步 [向 Timelines 端点发起你的第一个请求]/x-api/posts/timelines#getting-started-with-reverse-chronological-home-timeline “向 Timelines 端点发起你的第一个请求”) 在我们的 API 参考页面查看完整的参数、fields 等列表 获取支持或排查错误