集成指南

此页面介绍在将 users lookup 端点集成到你的系统时需要了解的多种工具和关键概念。我们将页面拆分为以下几个部分：

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

​

实用工具

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

​

Postman

Postman 是一款非常实用的工具，可用于测试端点。每个 Postman 请求都包含所有路径参数和请求体参数，帮助你快速了解可用选项。要了解更多关于我们的 Postman 集合的信息，请访问我们的 “使用 Postman” 页面。 

​

代码示例

想用你常用的编程语言，通过代码来对该端点进行集成吗？我们在 GitHub 页面提供了多种代码示例，可作为你的起点。

​

第三方库

借助我们社区提供的第三方库快速开始。查看相应的版本标签即可找到兼容 v2 端点的库。

​

核心概念

​

认证

所有 X API v2 端点都要求使用一组凭证（也称为 keys 和 tokens）对请求进行认证。你可以使用 OAuth 1.0a 用户上下文、仅应用（App only）或 OAuth 2.0 授权码（PKCE）来对这些端点的请求进行认证。

OAuth 1.0a 用户上下文要求你使用 API Keys、用户 Access Tokens，以及少量其他参数来创建授权标头，然后随请求一并发送。Access Tokens 必须与您代表其发起请求的用户关联。若要为其他用户生成一组 Access Tokens，他们必须通过三方（3-legged）OAuth 流程授权你的应用。

请注意，OAuth 1.0a 使用起来可能较为复杂。如果你不熟悉此认证方法，我们建议使用库、使用 Postman 等工具，或使用 OAuth 2.0 来完成请求认证。若你希望从这些端点请求某条 Post 或私有指标，你需要使用 OAuth 1.0a 用户上下文或 OAuth 2.0 授权码（PKCE），以确保你获得该内容所属用户的适当权限。

仅应用（App only）只要求你在请求中携带一个仅应用 Access Token。你可以直接在开发者应用中生成仅应用 Access Token，或使用POST oauth2/token端点生成。

OAuth 2.0 授权码（PKCE）允许对应用的 scope 进行更细粒度的控制，并支持跨多设备的授权流程。OAuth 2.0 允许你选择具体的细粒度 scopes，从而代表用户获取相应的权限。

要在你的应用中启用 OAuth 2.0，必须在开发者门户的 App 设置部分找到该应用的认证设置并将其启用。

请注意

如果你请求以下 fields，则需要 OAuth 1.0a 用户上下文或 OAuth 2.0 授权码：

• tweet.fields.non_public_metrics
• tweet.fields.promoted_metrics
• tweet.fields.organic_metrics

​

开发者门户、项目和开发者应用

要获取可用于 X API v2 端点的一组认证凭证，你必须先注册开发者账号，在该账号下设置一个项目，并在该项目中创建一个开发者应用。随后，你可以在你的开发者应用中找到密钥和令牌。   

​

速率限制

每天都有成千上万的开发者向 X API 发起请求。为帮助管理海量请求，速率限制会应用到每个端点上，用于限制你代表你的应用或代表已认证用户所能发起的请求数量。

用户查询端点在应用级和用户级都会受到速率限制。然而，已认证用户查询端点仅在用户级受到速率限制。

应用级速率限制意味着你（开发者）在给定时间段内，使用任一给定的应用（由你所使用的密钥和令牌确定）对该端点只能发起一定数量的请求。用户级速率限制意味着你所代表的已认证用户，在任意开发者应用中只能在该时间段内执行有限次数的请求。

下表显示了每个端点的速率限制。

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

​

字段与 expansions

X API v2 允许用户使用一组称为字段与 expansions 的工具，精确选择希望从 API 返回的 data。expansions 参数允许你展开负载中被引用的对象。例如，此端点允许你使用 pinned_tweet_id expansion。

fields 参数允许你选择不同 data 对象中希望接收的确切fields。这些端点主要返回用户对象。默认情况下，用户对象返回 id、name 和 username 字段。若要接收诸如 user.created_at 或 user.location 等其他字段，你必须通过 fields 参数明确请求。你在集成中可能希望考虑使用的一些重要字段包括 Post 的投票 data、metrics、annotations，以及会话 ID 字段。

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

​

边缘情况

• 在转发中，Post 文本会被截断。短期的解决办法是展开被引用的 Post，并从该扩展中获取完整文本。这个问题我们会在后续修复。