跳转到主要内容

​
如何集成 Timelines endpoint

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

​
实用工具

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

​
关键概念

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