整合指南

本页介绍在将 List Posts 查询 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 可能较难使用。如果你不熟悉这种身份验证方法，建议使用库、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 生成一个。

​

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

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

​

请求速率限制

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

此 endpoint 在 App 级别和用户级别均设有请求速率限制。App 级别的请求速率限制意味着你（开发者）在给定时间段内，从任意 App（通过使用 API Key 和 API Secret Key，或 Bearer Token）只能对该 endpoint 发起一定数量的请求。用户级别的请求速率限制意味着你所代表的已认证用户，在任意开发者 App 上只能执行一定次数的 List Post 查询。

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

Endpoint	HTTP method	Rate limit
/2/lists/:id/tweets	GET	每 15 分钟 900 次请求

Fields 和 expansions

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

• author_id

fields 参数允许你选择希望接收的不同数据对象中的具体fields。此 endpoint 主要返回 Post 对象。默认情况下，Post 对象返回 id 和 text 字段。若要接收诸如 tweet.created_at 或 tweet.lang 等附加字段，你需要使用 fields 参数明确请求这些字段。

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

下表展示了该查询 endpoint 可用的 field 和 expansions：

Endpoint	Fields	Expansions
/2/lists/:id/tweets	tweet.fields user.fields	author_id

分页

查询 List Posts 可能会返回大量数据。为确保在任意时间点提供一致且高性能的结果，我们使用分页。分页是 X API v2 中的一项特性，适用于返回结果多于单个响应所能包含的 endpoints。发生这种情况时，data 会以一系列“页面”的形式返回。了解更多关于如何分页获取结果。