集成指南

本页介绍在将 List 查询 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 token 必须与你所代表的目标用户相关联。如果你想为另一位用户生成一组 Access Tokens，则他们必须通过 三方 OAuth 授权流程授权你的 App。

请注意，OAuth 1.0a 可能较难使用。如果你不熟悉这种身份验证方法，我们建议你使用一个library、使用诸如 Postman 之类的工具，或使用 OAuth 2.0 来对你的请求进行身份验证。

OAuth 2.0 授权码模式（Authorization Code）配合 PKCE 允许对应用的 scope，以及跨多设备的授权流程进行更精细的控制。OAuth 2.0 允许你选择细粒度的 scope，从而代表用户获得特定权限。 

要在你的 App 中启用 OAuth 2.0，你必须在开发者门户的 App 设置部分，进入你的 App 的身份验证设置中将其启用。

App only 只要求你在请求中携带一个 App only Access Token。你可以直接在开发者 App 中生成一个 App only Access Token，或通过 POST oauth2/token endpoint 来生成。

​

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

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

​

请求速率限制

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

这些 endpoints 同时在 App 级别和用户级别实施请求速率限制。App 级别的请求速率限制意味着你（开发者）在给定时间段内，从任意一个 App（假定使用 API Key 和 API Secret Key，或 App only Access Token）对该 endpoint 只能发起一定数量的请求。用户级别的请求速率限制意味着你代表其发起请求的已认证用户，在任意开发者 App 中只能执行一定次数的 List 查询。

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

Endpoint	HTTP method	Rate limit
/2/lists/:id	GET	75 requests per 15 minutes
/2/users/:id/owned_lists	GET	15 requests per 15 minutes

Fields 和 expansions

X API v2 的 GET endpoint 允许用户使用名为 fields 和 expansions 的一组工具，精确选择希望从 API 返回的 data。expansions 参数允许你展开载荷中仅通过 ID 引用的对象。例如，通过 ID 查找一个 List 时，你可以获取以下expansions：

• owner_id

fields 参数允许你精确选择希望接收的不同数据对象中的哪些fields。这些 endpoints 主要返回 List 对象。默认情况下，List 对象返回 id 和 name 字段。要接收诸如 list.created_at 或 list.follower_count 等附加字段，你必须使用 list.fields 参数明确请求这些字段。

我们在X API v2 data dictionary中新增了一篇关于同时使用fields 和 expansions的指南。

下表展示了此 endpoint 组可用的 fields 和 expansions：

Endpoint	Fields	Expansions
/2/lists/:id	list.fields user.fields	owner_id
/2/users/:id/owned_lists	list.fields user.fields	owner_id

​

分页

查询用户拥有的 List 可能会返回大量数据。为确保在任何时刻都能返回一致且高性能的结果，我们使用分页。分页是 X API v2 的 endpoint 提供的一项功能：当单次响应无法容纳所有结果时，将通过分页返回更多结果。出现这种情况时，data 会以一系列“页”的形式返回。了解如何分页遍历结果。