集成指南

本页提供多种工具和关键概念，帮助你将 Posts 查询端点集成到系统中。我们将内容分为以下几部分：

• 实用工具
• 关键概念
  • 认证
  • 开发者门户、项目与应用
  • 速率限制
  • fields 与 expansions
  • Post 编辑
  • 边界情况

​

实用工具

在深入一些关键概念之前，建议先熟悉以下工具：

Postman
Postman 是一款出色的端点测试工具，涵盖所有路径与请求体参数，帮助你了解可用功能。请查看我们的Postman 入门指南以了解更多信息。

代码示例
在我们的GitHub 页面查找你所用编程语言的代码示例。

第三方库
使用社区构建且与 v2 端点兼容的第三方库。

​

核心概念

​

认证

所有 X API v2 端点都需要经过认证的请求。你可以使用以下任一方式进行认证：

• 使用 API Keys、Access Tokens 以及其他参数，通过 OAuth 1.0a 用户上下文 来创建授权标头。
• 在请求中携带 App Access Token，使用 OAuth 2.0 App-Only 进行认证。
• 使用 OAuth 2.0 授权码（PKCE），以便更好地控制应用的权限范围以及实现多设备授权。

实现 OAuth 1.0a 可能较为复杂。如果你不熟悉，建议在发起请求时使用库或采用 OAuth 2.0。对于私有指标或 Post，请使用 OAuth 1.0a 用户上下文或 OAuth 2.0 授权码（PKCE）。

请注意

如果你请求以下 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

​

开发者门户、项目和应用

要获取 X API v2 的凭据，你需要：

1. 一个已获批准的开发者账号。
2. 该开发者账号下的一个项目。
3. 该项目下的一个开发者应用，可在其中找到密钥和令牌。

​

速率限制

向 X API 发起的请求受速率限制约束，用于管理请求量。限制同时适用于应用和用户级别：

• 应用级：限制任意应用在每个周期内可发起的请求数量。
• 用户级：限制经过认证的用户在各开发者应用之间执行 Post 查询的频率。

​

字段与 expansions

X API v2 允许使用 fields 和 expansions 来选择特定的 data 字段：

• Expansions：用于获取额外的关联对象。支持的 expansions 包括：

  • edit_history_tweet_ids
  • attachments.poll_ids
  • attachments.media_keys
  • author_id
  • entities.mentions.username
  • geo.place_id
  • in_reply_to_user_id
  • referenced_tweets.id
  • referenced_tweets.id.author_id

• Fields：用于指定对象内的 data 字段，以返回更多数据。Post 对象默认包含 id、text 和 edit_history_tweet_ids。其他选项（如 tweet.created_at 和 tweet.entities）需要显式请求。

欲了解更多，请参阅 X API v2 data dictionary 中关于字段与 expansions 的指南。

​

Post 编辑

符合条件的 Post 可在发布后 30 分钟内最多编辑 5 次。Posts 查询端点始终返回最新的 Post 版本。对于近乎实时的使用场景，请注意这一时间窗口。更多信息请参阅Post 编辑基础。

​

边缘情况

• 推广指标：对未推广的 Post 请求推广指标时，会返回空响应。
• 文本截断：转发的 Post 文本会被截断。要获取完整文本，请展开被引用的 Post。