集成指南

本页介绍在将 users 查找 endpoint 集成到你的系统时需要了解的若干工具和关键概念。我们将本页分为几个不同的部分：

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

​

实用工具

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

​

Postman

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

​

代码示例

想用你常用的编程语言，为这个 endpoint 进行设置并上手编写代码吗？我们在 GitHub 页面提供了多种代码示例，供你作为起点参考。

​

第三方库

借助我们社区的第三方库来快速开始。你可以通过查找相应的版本标签，找到可与 v2 endpoint 配合使用的库。

​

关键概念

​

身份验证

所有 X API v2 endpoint 都要求使用一组凭据（也称为密钥和令牌）对请求进行身份验证。你可以使用 OAuth 1.0a 用户上下文、App only，或 OAuth 2.0 授权码模式（Authorization Code）配合 PKCE 来对这些 endpoint 的请求进行身份验证。 

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，以确保你获得内容所属用户授予的相应权限。  

App only仅要求你在请求中传递一个App only Access Token。你可以直接在开发者 App 中生成一个 App only Access Token，或使用 POST oauth2/token endpoint 生成。

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

​

开发者门户、Project 和开发者 App

要获取可用于 X API v2 endpoints 的一组身份验证凭据，您必须注册开发者账户，在该账户中设置一个Project，并在该 Project 中创建一个开发者 App。随后，您可以在开发者 App 中找到您的密钥和令牌。   

​

请求速率限制

每天都有成千上万的开发者向 X API 发起请求。为管理庞大的请求量，我们在每个 endpoint 上设置了请求速率限制，以限制你代表你的 App 或代表已认证用户所能发起的请求次数。

用户查找类 endpoint 同时在 App 级和用户级受到请求速率限制。不过，已认证用户查找 endpoint 仅在用户级受到请求速率限制。

App 级请求速率限制意味着你作为开发者，从任一特定 App（由你所使用的密钥和令牌所标识）在给定时间窗口内只能对该 endpoint 发起一定数量的请求。用户级请求速率限制意味着你代表的已认证用户，在任何开发者 App 上只能在给定时间窗口内发起有限次数的请求。

下表展示了各 endpoint 的请求速率限制。

Endpoint	HTTP 方法	请求速率限制 / 级别
/2/users	GET	每 15 分钟 900 次请求 / App 和用户
/2/users/:id	GET	每 15 分钟 900 次请求 / App 和用户
/2/users/by	GET	每 15 分钟 900 次请求 / App 和用户
/2/users/by/username/:username	GET	每 15 分钟 900 次请求 / App 和用户
/2/users/me	GET	每 15 分钟 75 次请求 / 用户

​

字段与扩展

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

fields 参数允许你精确选择各数据对象中希望接收的字段。这些 endpoints 主要返回用户对象。默认情况下，用户对象返回 id、name 和 username 字段。若要接收诸如 user.created_at 或 user.location 等其他字段，你需要通过 fields 参数明确请求这些字段。在你的集成中，一些值得考虑的重要字段包括 Post 投票数据、度量、annotations，以及会话 ID 字段。

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

​

边界情况

• 在转发中，Post 文本可能会被截断。短期的权宜之计是展开被引用的 Post，并从展开结果中获取完整文本。此问题属于缺陷，我们将在未来修复。