概述

X API v2 的最新版本意义重大。因此，我们将本迁移部分划分为几个模块：

X API v2 的最新变化	了解我们在 X API v2 中发布的新端点与新功能。
准备开始迁移？	按照一组指南与操作说明启动你的迁移流程。
数据格式迁移指南	了解如何改造先前适用于标准 v1.1 和企业版数据格式的数据解析器。
X API 端点映射	查看标准 v1.1 和企业版端点如何映射到新的 X API v2 端点。

---

​

什么是 X API v2？

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

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

​

为什么要迁移？

X API v2 构建在更现代、更可持续的基础之上，不仅为标准版 v1.1 和企业版产品提供了改进的替代端点，也带来了全新的功能。我们强烈建议传统 API（v1.1 和企业版）的客户尽快开始迁移到 v2，我们确实计划最终弃用这些旧版接口。使用 X API 倾听并分析公开对话、在 X 上与用户互动并持续创新。

在本节中，我们将讨论端点和功能。

​

V2 端点

你可以通过以下指南查看 v2 端点的完整列表及其在 pre-v2 中的对应等价项：

X API 端点映射

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

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

​

新增功能

X API v2 还引入了新功能，帮助你从 X API 中获取更多价值。许多新增内容源自你的反馈，其中包含此前仅向企业客户提供的部分功能。

API 的一些改进包括：

• 在各端点间保持一致的设计
• 可在响应负载中指定返回哪些 fields 和对象
• 全新且更为详尽的数据对象
• 借助 Tweet 注释获取并基于新增的上下文信息进行过滤
• 访问新增指标
• 轻松识别并筛选属于回复线程的会话
• 为学术研究人员提供高级功能并提升数据访问权限
• 为流式端点提供恢复与冗余功能
• 轻松返回匹配查询的 Tweet 数量
• 支持编辑 Tweets
• 高置信度垃圾信息过滤
• 将缩短的 URL 完整解包，便于更高效的过滤与分析
• 通过移除已弃用字段并现代化标签，简化 JSON 响应对象
• 在搜索查询中返回 100% 匹配的公开且可用的 Tweets
• 流式“规则”，可在不断开连接的情况下进行更改
• 更具表达力的查询语言，适用于搜索 Tweets、Tweet 计数和过滤流
• OpenAPI 规范，用于构建新库并更透明地跟踪变更

​

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

以下六种 data 对象可用于 v2 端点：

对象	说明
Tweet	Tweet 对象包含大量根级字段，例如 id、text 和 created_at。Tweet 对象也是多个子对象（包括 user、media、poll 和 place）的父对象。
User	user 对象包含描述所引用用户的 X 用户账号元数据。
Spaces	Space 对象包含诸如 state、host_id、is_ticketed，以及 lang 等字段。
Lists	List 对象包含所请求列表的基础信息，包括 description、member_count 和 owner_id。
Media	如果某条 Tweet 包含媒体（如图像），则可使用 media.fields 参数请求 media 对象，其包含 media_key、type、url、preview_image_url 等字段。
Poll	Tweet 中包含的投票不是任何端点的主对象，但可在 Tweet 对象中找到并展开。
Place	place 对象包含诸如 place_id、geo 对象、country_code 等字段。可据此按位置识别并研究 Tweets。

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

​

灵活选择要接收的对象和字段

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

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

以下是您可在不同 X API v2 端点中请求的完整 expansions 列表：

对象 / 资源	可用 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、Users、Spaces 和 Media 对象中新增可用指标

现在可在 Tweet、user、Spaces、Lists 和 media 对象中获取更多指标。这些指标涵盖公开和私有两类，部分指标还可按自然或推广情境细分，用于 Tweet 广告分析。

了解更多可用的指标。

Object	Available Metrics	Public Metrics	Private Metrics	Organic Metrics	Promoted Metrics
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 端点提供已编辑 Tweet 的元数据。编辑 Tweet 功能于 2022 年 9 月 1 日首先在 X 员工中进行测试。从该日期起，符合条件的 Tweet 可在 30 分钟内编辑，最多可编辑 5 次。了解更多编辑 Tweets。 使用 X API v2，开发者可以了解：

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

​

跟踪主题式会话

一个新的 Tweet 字段可用于标识某条 Tweet 所属的会话线程。conversation ID 是开启该会话的那条 Tweet 的 Tweet ID。了解更多会话跟踪。

​

准备迁移

要使用 v2 端点，您需要具备以下条件：

• 开发者账户
• 在项目中创建的开发者应用
• 来自该项目开发者应用的密钥和令牌

请务必使用项目内应用的密钥和令牌。若使用项目外应用的密钥和令牌，将无法向 v2 端点发起请求。

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

​

认证

使用全新的 X API 时，你将使用两种不同的认证方式：OAuth 1.0a 用户上下文 和 OAuth 2.0 Bearer Token，以访问不同的端点。它们在向端点发起请求时用途各不相同：

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

​

工具与代码

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

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

​

迁移到更新的端点

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

• Tweets
  • Tweets 查询
  • 管理 Tweets
  • 时间线
  • 搜索 Tweets
  • Tweet 计数
  • 过滤流
  • 抽样流
  • 转发
  • 点赞
  • 隐藏回复
• Users
  • Users 查询
  • 关注
  • 屏蔽
  • 静音
• Lists
  • List 查询
  • 管理 Lists
  • List 中的 Tweet 查询
  • List 成员

​

迁移到新数据格式

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

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

你可以访问本迁移中心的数据格式迁移部分，或查阅以下具体的数据格式指南：

• 原生格式到 X API v2（标准版 v1.1）
• 原生增强（Native Enriched）到 X API v2（企业版）
• 活动流（Activity Streams）到 X API v2（企业版）

​

接下来是什么？

对于已经使用该平台一段时间的你们来说，会注意到许多新的端点与现有的标准 v1.1和企业版端点保持一致。确实，我们计划让这些端点在未来取代这三个版本。

我们整理了一张表，帮助你了解X API 端点与以往版本的对应关系。

如果你想了解接下来的规划，请访问我们的产品路线图。

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

​

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

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

浏览已提交的想法，为符合你需求的提议投票支持，并分享你的反馈！