集成指南

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

• 实用工具
• 关键概念
• 身份验证
• 开发者门户、Project 和 App
• 请求速率限制
• fields 和 expansions

​

实用工具

在深入介绍有助于你集成此 endpoint 的关键概念之前，建议先熟悉以下内容：

​

Postman

Postman 是一款优秀的工具，可用于测试某个 endpoint。每个 Postman 请求都包含所有路径参数和请求体参数，帮助你快速了解可用的选项。要了解更多关于我们 Postman 集合的内容，请访问我们的 “Using Postman” 页面。 

​

代码示例

想用你常用的编程语言配合此 endpoint 快速上手吗？我们在 GitHub 页面提供了多种代码示例，供你作为起点使用。

​

第三方库

充分利用我们社区的第三方库来快速上手。通过查找相应的版本标签，您可以找到与 v2 endpoint 兼容的库。  

​

关键概念

​

认证

所有 X API v2 endpoint 都要求你使用一组凭据（也称为密钥和令牌）对请求进行认证。

你可以使用 OAuth 1.0a 用户上下文 或 OAuth 2.0 Bearer Token 来对发往 Retweets 查询 endpoint 的请求进行认证。

“管理转发”的 endpoints 需要使用 OAuth 1.0a 用户上下文，这意味着你必须使用一组 API Key 和用户 access token 才能成功发起请求。access token 必须与被你代表其发起请求的用户关联。如果你想为另一位用户生成一组 access token，则必须先通过三方 OAuth 授权流程让对方授权或验证你的 App。

请注意，OAuth 1.0a 的使用可能较为复杂。如果你不熟悉这种认证方法，建议使用 library 来正确完成请求认证。

请注意

如果你请求以下 fields，则需要使用 OAuth 1.0a 用户上下文：

• 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 中找到密钥和令牌。   

​

请求速率限制

每天有成千上万的开发者向 X API 发起请求。为便于管理海量请求，我们在每个 endpoint 上设置了请求速率限制，以限制你代表 App 或经身份验证的用户所能发起的请求数量。

管理转发的 endpoints 的限制为每位用户每 15 分钟 50 次请求。此外，对于 POST endpoint，每位用户、每个 App 在每 3 小时的时间窗口内限 300 次请求。

对于转发查询 endpoint，你在每 15 分钟的时间窗口内限 75 次请求。此外，此 endpoint 仅返回最近 100 位进行过转发的用户。

​

字段与扩展（expansions）

X API v2 允许用户使用称为 fields 和 expansions 的一组工具，精确选择希望从 API 返回的数据。expansions 参数允许你展开负载中被引用的对象。例如，此 endpoint 允许你获取以下expansions：

• 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 参数允许你在不同的数据对象中精确选择希望接收的fields。这些 endpoint 主要返回 Post 对象。默认情况下，Post 对象返回 id 和 text 字段。要接收 tweet.created_at 或 tweet.entities 等附加字段，你需要通过 fields 参数显式请求它们。在集成中你可能希望考虑使用的一些重要字段包括投票数据、度量、Post 注释（annotations）以及会话 ID 字段。

我们在 X API v2 数据字典中新增了关于如何同时使用 fields 和 expansions的指南。