集成指南

​

集成指南

本页面介绍在将 List 成员 endpoint 集成到你的系统时需了解的多种工具与关键概念。我们将内容分为以下几个部分：

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

​

实用工具

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

​

Postman

Postman 是一款非常适合用于测试 endpoint 的工具。每个 Postman 请求都包含所有路径参数和请求体参数，帮助你快速了解可用的选项。要进一步了解我们的 Postman 集合，请访问我们的 「Using Postman」 页面。 

​

代码示例

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

​

第三方库

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

​

核心概念

​

身份验证

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

OAuth 1.0a 用户上下文，这意味着你必须使用一组 API Key 和用户 Access Tokens 才能成功发起请求。access token 必须与由你代为发起请求的用户关联。如果你希望为另一位用户生成一组 Access Tokens，该用户必须通过 三方 OAuth 授权流程授权你的 App。

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

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 生成一个。

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 或代表已通过身份验证的用户所能发起的请求数量。

查询（GET）endpoint 同时在 App 级和用户级受限；而管理（POST/DELETE）endpoint 仅在用户级受限。App 级请求速率限制意味着你（开发者）从任一给定的 App（使用 API Key 与 API Secret Key，或 App only Access Token）在一定时间内只能向该 endpoint 发起限定数量的请求。用户级请求速率限制则意味着，你代表其发起请求的已认证用户，在任何开发者 App 中执行 List 查询的次数也被限制在一定范围内。

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

Endpoint	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 次请求

​

字段与扩展

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

• pinned_tweet_id

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

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

下表展示了各查询 endpoint 可用的字段与扩展：

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

​

分页

查询 membership/members 可能会返回大量 data。为确保在任何时刻都能返回一致且高性能的结果，我们采用分页。分页是 X API v2 各个 endpoint 提供的一项功能，用于在单个响应无法承载所有结果时分批返回更多结果。此时，data 将按一系列“页面”返回。了解更多关于如何分页获取结果。