弃用和停用

随着新版本的发布，弃用版本的停用日期也会公布，在该日期之后将不再提供弃用版本。以下是一些需要注意的其他准则：

  • 我们力求在任何时候都只提供最多四个主要版本。
  • 主要版本的生命周期约为 12 个月，次要版本的生命周期为 10 个月。
  • 您每年最多需要执行两次升级，并且不必严格按顺序升级，例如，您可以直接从版本 (N) 升级到版本 (N+2)。
  • 所有客户端库针对最新版本发布之日与要停用的版本之间的重叠时间至少为 20 周。

我们的客户端库支持服务的任何可用版本，因此您可以通过指定所用服务的不同版本来逐步升级。

时刻表

下表列出了每个可用版本的具体弃用和停用日期，以及未来版本的预计发布日期。我们建议您在最新版本发布后尽快升级到该版本。“暂定日期”表示该产品可能会在该月的任何时间停用，并且日期可能会发生变化。订阅博客，接收 API 版本弃用公告提醒。

API 版本发布日期停用日期升级指南
已发布版本
v212025 年 8 月 6 日2026 年 8 月（暂定）从 v20 升级到 v21
v222025 年 10 月 15 日2026 年 10 月（暂定）从 v21 升级到 v22
v232026 年 1 月 28 日2027 年 2 月从 v22 升级到 v23
v23.1 2026 年 2 月 25 日 2027 年 2 月 从 v23 升级到 v23.1
v23.2 2026 年 3 月 25 日 2027 年 2 月 从 v23.1 升级到 v23.2
v24 2026 年 4 月 22 日 2027 年 5 月 从 v23.2 升级到 v24
v24.1 2026 年 5 月 13 日 2027 年 5 月 从 v24 升级到 v24.1
即将推出的版本
v24.2 2026 年 6 月 2027 年 5 月  
v25 2026 年 7 月 2027 年 8 月  
v25.1 2026 年 8 月 2027 年 8 月  
v25.2 2026 年 9 月 2027 年 8 月  
v26 2026 年 10 月 2027 年 11 月  
v26.1* 2026 年 11 月 2027 年 11 月  

* 由于与假期重叠，v26.1 被指定为可选版本。

查看项目正在使用的版本

您可以使用 Google Cloud 控制台查看项目最近调用的方法和服务列表：

  1. 在 Google Cloud 控制台中打开 API 和服务。
  2. 点击表格中的 Google Ads API。
  3. 在指标子标签页上，您应该会看到每个图表上绘制的近期请求。您可以在方法表格中查看您已向哪些方法发送请求。方法名称包括 Google Ads API 版本、服务和方法名称，例如 google.ads.googleads.v24.services.GoogleAdsService.Mutate。
  4. （可选）选择要查看请求的时段。

弃用与停用之间的区别

术语弃用落日余晖
定义 已弃用的版本是指不是最新版本的版本。 发布新版本后，所有旧版本都将被标记为已弃用。 无法再使用已停用的版本。在停用日期当天或之后，向此版本发送的请求将失败。
含义 在停用之前，您仍然可以使用已弃用的版本，但已弃用版本的参考会取消突出显示，以表明它们不再是最新版本。

建议您尽快升级到最新版本，以便享受新功能带来的好处。

 您需要立即从已停用的版本升级，才能使用 Google Ads API。

我们强烈建议您使用升级指南升级到最新版本。
计时 我们平均每 3 到 4 个月发布一个新版本，因此给定的版本将在大约 3 到 4 个月后被弃用。 我们计划在版本发布 1 年后将其弃用。
API 已弃用版本的 API 端点仍可照常使用。

您可以使用我们的客户端库和 REST 访问我们的 API 端点。 不过，我们不会向已弃用的版本添加新功能。

 已停用的版本的 API 端点会在停用日期之后停止运行。如果您尝试访问已停用版本的 API 端点，Google Ads API 将抛出错误。
客户端库 为了提供精简的客户端库，我们将停止在新客户端库版本中包含已弃用的 API 版本（自弃用日期起）。这有助于您在项目中纳入我们的客户端库时节省空间。 在停用日期之后，任何新版客户端库都不再支持已停用的 API 版本。
支持 我们会定期为已废弃的版本提供支持。 在停用日期过后，已停用的版本将不再受支持。

支持的客户端库版本

下表显示了哪些客户端库适用于哪些 API 版本。

所列的最低客户端库版本足以支持主要的 Google Ads API 版本（例如 v24）。如需查看次要版本所需的客户端库版本，请参阅关联的更改日志。

Java

更新日志

Java 版客户端库
v24 Min: 43.0.0
Max: -
v23 Min: 42.0.0
Max: -
v22 Min: 41.0.0
Max: -
v21 Min: 39.0.0
Max: -

C#

更新日志

适用于 .NET 的客户端库
v24 Min: 25.3.0
Max: -
v23 Min: 25.1.0
Max: -
v22 Min: 24.1.0
Max: -
v21 Min: 24.0.0
Max: -

PHP

更新日志

PHP 版客户端库
v24 Min: 33.3.0
Max: -
v23 Min: 32.2.0
Max: -
v22 Min: 31.0.0
Max: -
v21 Min: 28.0.0
Max: -

Python

更新日志

适用于 Python 的客户端库
v24 Min: 30.1.0
Max: -
v23 Min: 29.2.0
Max: -
v22 Min: 28.1.0
Max: -
v21 Min: 28.0.0
Max: -

Ruby

更新日志

Ruby 版客户端库
v24 Min: 40.0.0
Max: -
v23 Min: 38.0.0
Max: -
v22 Min: 36.0.0
Max: -
v21 Min: 35.0.0
Max: -

Perl

更新日志

适用于 Perl 的客户端库
v24 Min: 32.0.0
Max: -
v23 Min: 31.0.0
Max: -
v22 Min: 29.0.0
Max: -
v21 Min: 28.0.0
Max: -

功能弃用和变更

请定期关注 Google Ads 开发者博客，以便率先了解即将弃用的功能。

下表列出了 Google Ads API 计划弃用的具体功能。如需详细了解每项弃用，请参阅相关博文。

功能 说明 生效日期 其他说明
数据保留政策变更

细粒度报告数据（按天、按小时、按周）的保留期限将缩短为 37 个月。高级别数据（每月、每季度、每年）仍可保留 11 年。11 年的保留期限与完整的日历周期边界（下一个完整周期的开始）保持一致。 例如：

  • 如果 11 年前是 2022-03-22，则返回 2022-04-01 至今的数据。
  • 如果 11 年前是 2022-03-01，系统仍会返回 2022-04-01 到现在的数据。
2026 年 6 月 1 日 如需了解详情，请参阅我们的博文。
线下转化支持服务发生变化

自 2026 年 6 月 15 日起，如果开发者令牌近期未曾发出线下转化请求，则必须使用 Data Manager API 来完成线下转化工作流程。

  • 如果您的开发者令牌在 2025 年 12 月 17 日至 2026 年 6 月 15 日期间发送了 UploadClickConversions 请求，则可以继续将该开发者令牌与 Google Ads API 搭配使用，以实现线下转化工作流。 不过，我们建议您将线下转化工作流程升级为 Data Manager API，以获得更好的开发者体验并使用更多功能。
  • 否则，自 2026 年 6 月 15 日起，任何 UploadClickConversions 请求都会失败并显示错误 CUSTOMER_NOT_ALLOWLISTED_FOR_THIS_FEATURE。 对于线下转化工作流，请使用 Data Manager API，而不是 Google Ads API。
2026 年 6 月 15 日 如需了解详情，请参阅我们的博文。
目标客户匹配支持方面的变更

自 2026 年 4 月 1 日起，如果开发者令牌最近没有发出目标客户匹配请求，则必须使用 Data Manager API 来完成目标客户匹配工作流程。

April 1, 2026 如需了解详情，请参阅我们的博文。
IP 地址和会话属性支持方面的变更 Google Ads API 不再接受新用户在转化导入过程中使用会话属性或 IP 地址数据。现有用户应迁移到 Data Manager API。 2026 年 2 月 2 日 如需了解详情，请参阅我们的博文。
来电专用广告弃用 无法制作新的来电专用广告。现有的来电专用广告将于 2027 年 2 月停止投放，并且 API 支持将被移除。广告客户应改用包含电话素材资源的自适应搜索广告。 2026 年 1 月 如需了解详情，请参阅我们的博文。