概述

X API v2 的最新版本影响深远。因此，我们将本迁移章节拆分为若干部分：

X API v2 有哪些新内容	了解我们在 X API v2 中发布的新 endpoint 和功能。
准备迁移了吗？	按照一套指南和说明开始你的迁移。
数据格式迁移指南	了解如何重构此前适配 Standard v1.1 和 Enterprise 数据格式的 data 解析器。
X API endpoint 映射	查看 Standard v1.1 和 Enterprise endpoint 如何映射到新的 X API v2 endpoint。

---

​

什么是 X API v2？

X API v2 现已成为主要的 X API，也是产品投入与创新的重点。我们与开发者合作，共同打造新一代 X API，以更好地服务多元化的开发者社区。基于开发者反馈，我们对 API 进行了重构，更好地满足更广泛的需求，推出了新功能和 endpoint，并优化了开发者体验。

X API v2 现已成为主要的 X API，也是产品投入与创新的重点。过去几年里，我们与开发者携手重构 API，更好地满足更广泛的需求，推出新功能和 endpoint，并优化开发者体验。我们致力于持续构建开放的开发者平台，期待看到你使用 X API v2 构建的成果。

​

为什么要迁移？

X API v2 构建于更现代、更可持续的基础之上，不仅提供了针对 Standard v1.1 和 Enterprise 产品的改进替代 endpoint，还引入了全新的功能。我们强烈建议仍在使用旧版 API（v1.1 和 Enterprise）的客户尽快开始迁移到 v2，因为我们最终计划弃用这些版本。使用 X API 来监听并分析公开讨论、在 X 上与用户互动并推动创新。

在本节中，我们将讨论相关的 endpoint 和功能。

​

V2 endpoint

您可以通过以下指南查看 v2 endpoint 的完整列表及其在 pre-v2 中的对应项：

X API Endpoint Map

虽然 X API v2 中的大多数 endpoint 是替代项，但我们也引入了多个全新的 endpoint。以下是我们在 v2 中发布的一些新 endpoint 示例：

• Spaces endpoint，帮助人们更好地使用 X Spaces，并使开发者能够共同塑造音频对话的未来。
• Hide replies，可让您构建工具，在大规模场景下限制具有辱骂性、干扰性或误导性的回复带来的影响。
• 全新的 Lists endpoint，允许您固定和取消固定 Lists，或查询某人的固定 Lists。
• 全新的批量合规 endpoint，可帮助您确保所存储的用户和 Tweet data 符合合规要求。

​

新功能

X API v2 还引入了新功能，帮助你从 X API 中获得更大价值。许多新增内容源于你的反馈，并包含此前仅面向 Enterprise 客户的功能。

对 API 的部分改进包括：

• 各个 endpoint 间的一致性设计
• 可在响应负载中指定返回的 fields 和对象
• 更为丰富且更详细的数据对象
• 借助 Tweet annotations 提供的新上下文信息来接收并筛选数据
• 访问新的度量
• 轻松识别并筛选属于回复线程的会话
• 为学术研究人员提供高级功能与更高的数据访问权限
• 面向流式 endpoint 的恢复与冗余功能
• 轻松返回与 query 匹配的 Tweets 计数
• 支持 Edit Tweets
• 高置信度垃圾信息过滤
• 短链接将被完全展开，便于更高效的过滤与分析
• 通过移除已弃用字段并现代化标签来简化 JSON 响应对象
• 在搜索查询中返回 100% 符合条件且可用的公开 Tweets
• 流式“rules”，可在不断开连接的情况下进行更改
• 更具表达力的查询语言，适用于 search Tweets、Tweet counts 和 filtered stream
• OpenAPI 规范，用于构建新库并更透明地跟踪变更

​

了解全新与更新的响应对象

以下六种数据对象可用于 v2 endpoint：

Object	Description
Tweet	Tweet 对象具有大量根级字段，例如 id、text 和 created_at。Tweet 对象也是多个子对象（包括 user、media、poll 和 place）的父对象。
User	用户对象包含描述被引用用户的 X 账户元数据。
Spaces	Space 对象由 state、host_id、is_ticketed，以及 lang 等字段组成。
Lists	List 对象包含关于所请求 List 的基本信息，包括 description、member_count 和 owner_id。
Media	如果一条 Tweet 包含媒体（例如图像），则可使用 media.fields 参数请求 media 对象，其包含 media_key、type、url、preview_image_url 等字段。
Poll	Tweet 中包含的投票不是任何 endpoint 的主对象，但可以在 Tweet 对象中找到并通过 expansions 展开。
Place	place 对象包含 place_id、geo 对象、country_code 等字段。此信息可用于按位置识别和分析 Tweet。

进一步了解如何使用 fields 和 expansions。

​

选择接收对象与字段的灵活性

当向 GET endpoint 发起请求时，您将收到与该 endpoint 相关的主要 data 对象，其中包含一组默认字段。例如，Tweet 对象默认返回 id 和 text 字段。

如果您希望在请求中获取更多字段，需要使用 fields 和 expansions 参数。expansions 参数可让您检索相关数据对象，例如用户置顶的 Tweet 或媒体对象；而 fields 参数可让您在返回对象中请求超出默认范围的特定字段。

以下是可与不同 X API v2 endpoint 一起请求的 expansions 完整列表：

Object / Resource	Available Expansions
Tweets	author_id, edit_history_tweet_ids, entities.mentions.username, in_reply_to_user_id, referenced_tweets.id, referenced_tweets.id.author_id, attachments.poll_ids, attachments.media_keys, geo.place_id
Users	pinned_tweet_id
Spaces	invited_user_ids, speaker_ids, creator_id, host_ids, topic_ids

了解更多：如何使用 fields 和 expansions。

​

在 Tweets、用户、Spaces 和媒体对象中新增可用度量

现在可在 Tweet、用户、Spaces、List 和媒体对象中获取更多度量。这些度量包含公开和私有两类，且部分度量可按 Tweet 广告的有机或推广 context 进行细分。

了解更多可用的度量。

对象	可用度量	公开度量	私有度量	有机度量	推广大度量
tweets	retweet_count	✔️		✔️	✔️
	quote_count	✔️
	like_count	✔️		✔️	✔️
	reply_count	✔️		✔️	✔️
	impression_count		✔️	✔️	✔️
	url_profile_clicks		✔️	✔️	✔️
	url_link_clicks		✔️	✔️	✔️
user	follower_count	✔️
user	following_count	✔️
media	view_count		✔️
media	playback_0_count		✔️
space	participant_count	✔️

​

编辑 Tweet

X API v2 的 endpoint 提供已编辑 Tweet 的 metadata。Edit Tweet 功能最初于 2022 年 9 月 1 日在 X 员工中开启测试。从该日期起，符合条件的 Tweets 可在 30 分钟内进行编辑，最多可编辑 5 次。了解更多关于Edit Tweets的信息。 使用 X API v2，开发者可以了解：

• 该 Tweet 在创建时是否具备可编辑资格。某些 Tweets（例如包含投票或已排程发布的 Tweets）无法编辑。
• Tweets 可在 30 分钟内编辑，且最多可编辑 5 次。对于可编辑的 Tweets，您可以查看是否仍在可编辑时间窗口内，以及剩余可编辑次数。
• 您是否正在查看某条 Tweet 的已编辑版本（在大多数情况下，API 将返回该 Tweet 的最新版本，除非根据 Tweet ID 请求了特定的历史版本）。
• 该 Tweet 的完整编辑历史。
• 归属于该 Tweet 各个版本的互动数据。

​

跟踪串联会话

新增的 Tweet 字段可用于标识某条 Tweet 所属的会话串。conversation ID 是发起该会话的那条 Tweet 的 Tweet ID。了解更多会话跟踪。

​

准备迁移

要使用 v2 endpoint，您需要准备以下内容：

• 开发者账户
• 在 Project 中创建的 开发者 App
• 该 Project 中开发者 App 的密钥和令牌

请务必使用位于某个 Project 内的 App 的密钥和令牌。若使用不属于任何 Project 的 App 的密钥和令牌，将无法向 v2 endpoint 发起请求。

获得开发者账户后，您可以在开发者门户中完成上述所有设置。

​

认证

在新的 X API 中，你将使用两种不同的认证方式——OAuth 1.0a 用户上下文 和 OAuth 2.0 Bearer Token——来访问不同的 endpoint。每种方式在向这些 endpoint 发起请求时用途不同：

当代表某位 X 用户发起请求时，需要使用 OAuth 1.0a 用户上下文 当代表你的开发者 App 发起请求时，需要使用 OAuth 2.0 Bearer Token

​

工具与代码

为帮助你上手并熟悉新的 endpoint 与功能，我们提供了几种可快速开展工作的选项：

• 我们提供了一个 X 的 Postman collection，可让你使用 Postman 客户端向各个 endpoint 发起请求并进行连接。这是一种低阻力的方式，用于测试身份验证并试用这些 endpoint。
• 我们还提供了由 X 支持及第三方维护的库清单，涵盖 Ruby、Python、Node、Java 等多种语言。欲了解更多背景，请查看我们的工具与库页面。

​

迁移到更新的 endpoint

当您开始探索新的 Twitter v2 endpoint 时，我们提供了一系列详细的迁移指南，帮助您将每个更新的 endpoint 的功能与较旧版本进行对比：

• Tweets
  • Tweets 查找
  • 管理 Tweets
  • 时间线
  • 搜索 Tweets
  • Tweet 计数
  • 过滤的流
  • 抽样 stream
  • 转发
  • like
  • 隐藏回复
• 用户
  • 用户查找
  • 关注
  • 屏蔽
  • 静音
• Lists
  • List 查找
  • 管理 Lists
  • List Tweet 查找
  • List 成员

​

迁移到新的数据格式

当您从 v1.1 或 Enterprise 迁移到 v2 时，需要注意数据的交付格式已发生重大变化。我们新增了 fields，调整了 fields 的顺序，并在某些情况下完全移除了部分元素。

为帮助您了解这些变化，我们正在编写一系列指南，帮助您将 v2 之前的数据格式 fields 映射到新版的 fields，并说明如何请求这些新 fields。

您可以访问本迁移中心的data formats migration部分了解更多，或查阅以下特定数据格式指南：

• Native format 到 X API v2（Standard v1.1）
• Native Enriched 到 X API v2（Enterprise）
• Activity Streams 到 X API v2（Enterprise）

​

接下来是什么？

已经使用该平台一段时间的用户会注意到，许多新的 endpoint 与现有的 Standard v1.1 和 Enterprise endpoint 保持一致。我们的确计划在未来用这些来替代这三个版本。

我们整理了一张表，帮助你了解 X API endpoint 映射 到先前版本的对应关系。

如果你想了解接下来会推出什么，请访问我们的 产品路线图。

我们还有一个 更新日志，你可以查看我们已经发布的内容。

​

接下来我们应该构建什么？

在我们持续扩展 X API v2 功能的过程中，我们希望不断聆听您的意见。欢迎并鼓励您提交反馈。

请查看已提交的创意，支持与您需求契合的提案，并提出您的反馈。