隨著新版本的發布，已淘汰的版本會設有服務終止日期，過了這個日期就無法再使用該版本。請注意以下其他規範：
- 一次最多可使用三個主要版本。
- 主要版本的生命週期約為 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 控制台查看專案最近呼叫的方法和服務清單：
- 在 Google Cloud 控制台中開啟「API 和服務」。
- 按一下表格中的「Google Ads API」。
- 在「指標」子分頁中，您應該會看到每個圖表上顯示最近的要求。您可以在「Methods」表格中查看已傳送要求的對象。方法名稱包含 Google Ads API 版本、服務和方法名稱，例如
google.ads.googleads.v18.services.GoogleAdsService.Mutate。 - (選用) 選擇要查看的請求時間範圍。
停用和淘汰的差異
| 字詞 | 淘汰 | 日落 |
|---|---|---|
| 定義 | 已淘汰的版本是不是最新版本。 新版本發布後，所有舊版都會標示為已淘汰。 | 不再支援已停止服務的版本。在服務終止日期當天或之後，傳送至這個版本的請求將會失敗。 |
| 影響 | 在淘汰前，您仍可使用淘汰的版本，但淘汰版本的參照項目會取消醒目顯示，以示其已非最新版本。 建議您盡快升級至最新版本，以便享有新功能。 |
您必須立即從停用的版本升級，才能使用 Google Ads API。 我們強烈建議您使用升級指南升級至最新版本。 |
| 時間 | 我們平均每 3 到 4 個月就會發布新版本，因此這個版本會在大約 3 到 4 個月後淘汰。 | 我們預計在推出 1 年後停用該版本。 |
| API | 淘汰版本的 API 端點仍可正常運作。 您可以使用我們的用戶端程式庫、REST 等存取 API 端點，但新功能不會新增至已淘汰的版本。 |
服務終止日期過後，停止服務版本的 API 端點會停止運作。如果您嘗試存取停用的版本 API 端點，Google Ads API 就會擲回錯誤。 |
| 用戶端程式庫 | 為了提供精簡的用戶端程式庫，我們會在停用日期後，停止在新的用戶端程式庫版本中納入已淘汰的 API 版本。這有助於在專案中納入我們的用戶端程式庫時節省空間。 | 服務終止日期過後，用戶端程式庫不再支援任何新用戶端程式庫版本中的停止服務 API 版本。 |
| 支援服務 | 我們會為已淘汰的版本提供定期支援服務。 | 服務終止日期過後，我們就不再支援停止服務的版本。 |
支援的用戶端程式庫版本
表格中列出哪些用戶端程式庫可搭配哪些 API 版本運作。
Java
Google Ads API |
適用於 Java 的用戶端程式庫 |
v18 |
Min: 34.0.0Max: - |
v17 |
Min: 32.0.0Max: - |
v16 |
Min: 30.0.0Max: 34.0.0 |
C#
Google Ads API |
.NET 專用的用戶端程式庫 |
v18 |
Min: 21.1.0Max: - |
v17 |
Min: 20.1.0Max: - |
v16 |
Min: 18.1.0Max: - |
PHP
Google Ads API |
PHP 用戶端程式庫 |
v18 |
Min: 25.0.0Max: - |
v17 |
Min: 23.1.0Max: - |
v16 |
Min: 22.1.0Max: - |
Python
Google Ads API |
Python 專用的用戶端程式庫 |
v18 |
Min: 25.1.0Max: - |
v17 |
Min: 24.1.0Max: - |
v16 |
Min: 23.1.0Max: - |
小茹
Google Ads API |
Ruby 適用的用戶端程式庫 |
v18 |
Min: 31.0.0Max: - |
v17 |
Min: 29.0.0Max: - |
v16 |
Min: 27.0.0Max: - |
Perl
Google Ads API |
適用於 Perl 的用戶端程式庫 |
v18 |
Min: 25.0.1Max: - |
v17 |
Min: 23.0.0Max: - |
v16 |
Min: 21.0.0Max: - |
淘汰功能
請定期查看 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 列。 |
| 目標顧客比對會員資格到期時間更新 | 自 2025 年 4 月 7 日起，UserList.membership_life_span 欄位將不再允許大於 540 的值。 |
2025 年 4 月 7 日 | 我們將從 2025 年 4 月 7 日至 2025 年 4 月 15 日，逐步推出 UserList.membership_life_span 欄位的異動。如果要求將欄位設為超過 540，系統會傳回 RangeError.TOO_HIGH 錯誤。任何欄位值大於 540 的現有使用者名單，都會自動遷移，以便在成員資格到期時，最長保留 540 天的成員資格。詳情請參閱「目標顧客比對會籍到期日更新」。 |