弃用和停用

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

  • 任何时候都最多有 三个主要版本可用。
  • 主要版本的生命周期约为 12 个月；次要版本：10 个月。
  • 您每年最多只能执行两次升级，并且无需严格按顺序升级，例如，您可以直接从版本 (N) 升级到版本 (N+2)。
  • 为最新版本发布所有客户端库的日期与要弃用的版本之间的重叠期至少为 20 周。

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

时刻表

下表列出了每个可用版本的具体弃用和停用日期，以及未来版本的预计发布日期。我们建议您在最新版本发布后尽快升级到该版本。

API 版本 发布日期 弃用日期 停用日期 升级指南
v18 2024 年 10 月 16 日 2025 年 2 月 2025 年 9 月 24 日
v17.1 2024 年 8 月 7 日 2024 年 10 月 16 日 2025 年 6 月 4 日 从 v17 升级到 v18
v17 2024 年 6 月 5 日 2024 年 10 月 16 日 2025 年 6 月 4 日 从 v17 升级到 v18
v16.1 2024 年 4 月 24 日 2024 年 6 月 5 日 2025 年 2 月 5 日 从 v16 升级到 v17
v16 2024 年 2 月 21 日 2024 年 6 月 5 日 2025 年 2 月 5 日 从 v16 升级到 v17

查看项目使用的版本

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

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

废弃和弃用的区别

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

我们建议您尽快升级到最新版本，以便获享新功能。

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

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

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

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

支持的客户端库版本

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

Java

Java 版客户端库
v18 Min: 34.0.0
Max: -
v17 Min: 32.0.0
Max: -
v16 Min: 30.0.0
Max: 34.0.0

C#

适用于 .NET 的客户端库
v18 Min: 21.1.0
Max: -
v17 Min: 20.1.0
Max: -
v16 Min: 18.1.0
Max: -

PHP

PHP 版客户端库
v18 Min: 25.0.0
Max: -
v17 Min: 23.1.0
Max: -
v16 Min: 22.1.0
Max: -

Python

适用于 Python 的客户端库
v18 Min: 25.1.0
Max: -
v17 Min: 24.1.0
Max: -
v16 Min: 23.1.0
Max: -

Ruby

Ruby 版客户端库
v18 Min: 31.0.0
Max: -
v17 Min: 29.0.0
Max: -
v16 Min: 27.0.0
Max: -

Perl

适用于 Perl 的客户端库
v18 Min: 25.0.1
Max: -
v17 Min: 23.0.0
Max: -
v16 Min: 21.0.0
Max: -

功能弃用

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

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

功能 说明 生效日期 其他说明
自 2025 年 3 月 3 日起，Google Ads API 和 Google Ads 脚本搜索字词数据分析报告更新 自 2025 年 3 月 3 日起，Google Ads API 和 Google Ads 脚本的搜索字词数据分析报告将将所有搜索子类别返回为空。 Google Ads 界面已移除此字段，API 也将推出此项更改，以便在 Google Ads 中保持一致。 2025 年 3 月 3 日 自 2025 年 3 月 3 日起， segments.search_subcategory 的所有值都将变为空值。如果您在 campaign_search_term_insight 或 customer_search_term_insight 报告中查询 segments.search_subcategory，请检查您的代码是否可以处理 segments.search_subcategory 中的空值。空字符串已经是万能字符串，因此您的代码应该已经在处理此问题。我们建议从您的查询中移除 segments.search_subcategory。
Google Ads API 中的页面大小即将发生变更 在 v16 弃用后，您将无法再在发出 GoogleAdsService.Search 请求时设置 page_size 字段。 2025 年 2 月 停用 v16 后，所有 GoogleAdsService.Search 请求都将默认采用 10,000 行的固定页面大小。