集成指南

​

集成指南

本页介绍在将 List 成员端点集成到你的系统时需要了解的多种工具和关键概念。我们将内容划分为以下部分：

• 实用工具
• 关键概念
• 认证
• 开发者门户、项目与应用
• 速率限制
• Fields 和 expansions
• 分页

​

实用工具

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

​

Postman

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

​

代码示例

想使用你偏好的编程语言，配合一些代码来对接此端点吗？我们在 GitHub 页面提供了多种代码示例，可作为你的起点。

​

第三方库

利用我们社区提供的第三方库来快速上手。你可以通过查看相应的版本标签，找到适配 v2 端点的库。

​

关键概念

​

认证

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

OAuth 1.0a 用户上下文，这意味着你必须使用一组 API Keys 和用户 Access Tokens 才能成功发起请求。Access Tokens 必须与你代表其发起请求的用户关联。如果你想为另一位用户生成一组 Access Tokens，他们必须通过 3-legged OAuth flow 授权你的应用。

请注意，OAuth 1.0a 的使用可能较为复杂。如果你不熟悉此认证方法，我们建议你使用库、使用 Postman 等工具，或使用 OAuth 2.0 或 App only 来对请求进行认证。

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

要在你的应用中启用 OAuth 2.0，你需要在开发者门户的应用设置中找到认证设置并将其开启。

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

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

​

开发者门户、Project 与开发者应用

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

​

速率限制

每天都有成千上万的开发者向 X API 发出请求。为帮助管理如此大量的请求，我们在每个端点上设置了速率限制，以限制你代表你的应用或经身份验证的用户所能发起的请求数量。

查询（GET）端点在应用级和用户级均受速率限制；而管理（POST/DELETE）端点则在用户级受限。应用级速率限制意味着你（开发者）在给定时间段内，从任一应用（通过使用 API Key 和 API Secret Key，或 App only Access Token）对该端点只能发起限定数量的请求。用户级速率限制意味着你代表的经身份验证的用户，在任意开发者应用中执行列表查询的次数也有限制。

下表展示了各端点的速率限制。

端点	HTTP 方法	速率限制
/2/lists/:id/members	GET	每 15 分钟 900 次请求
/2/users/:id/list_memberships	GET	每 15 分钟 75 次请求
/2/lists/:id/members	POST	每 15 分钟 300 次请求
/2/lists/:id/members/:user_id	DELETE	每 15 分钟 300 次请求

​

字段与 expansions

X API v2 的 GET 端点允许用户使用一组称为 fields 和 expansions 的工具，精确选择希望从 API 返回的 data。expansions 参数允许你展开载荷中被引用的对象。例如，查询 List 成员时，你可以获取以下 expansions：

• pinned_tweet_id

fields 参数允许你精确选择不同 data 对象中希望接收的哪些 fields。List 成员查询主要返回 user 对象。默认情况下，user 对象返回 id、name 和 username 字段。若需接收诸如 user.created_at 或 user.description 等其他字段，你必须通过 user.fields 参数明确请求这些字段。 

我们新增了关于使用fields 和 expansions的指南。

下表显示了各查询端点可用的字段和 expansions：

Endpoint	Fields	Expansions
/2/lists/:id/members	user.fields tweet.fields	pinned_tweet_id
/2/users/:id/list_memberships	list.fields user.fields	owner_id

​

分页

查询成员资格/成员可能会返回大量 data。为确保我们随时提供一致且高性能的结果，我们使用分页。分页是 X API v2 端点中的一项功能，当返回结果超过单个响应可包含的数量时，会将 data 分成一系列“页面”返回。了解如何对结果进行分页