升級至最新版本

建議您定期從舊的 Google Ads API 主要版本升級至新的主要版本。這可能是因為某個版本即將停用 或是您想使用新功能建議您隨時升級至最新版本。

請參考淘汰時間表，規劃升級方式。如要瞭解版本管理的運作方式，請參閱版本管理指南。

以下檢查清單可協助您開始進行升級程序：

  1. 當您變更主要版本時，端點將會變更。更新您的用戶端程式庫，使用最新的端點。
  2. 查看版本資訊瞭解各版本有哪些變更。
  3. 請參閱下表，瞭解升級目標版本的具體細節。

如要全面瞭解這兩個版本之間的差異，請參閱「差異表」。

v16 至 v17

服務及其元件變更
GoogleAdsService Search 和 SearchStream 要求

要求限縮時出現的錯誤，該錯誤會是 QuotaError.EXCESSIVE_SHORT_TERM_QUERY_RESOURCE_CONSUMPTION 或 QuotaError.EXCESSIVE_LONG_TERM_QUERY_RESOURCE_CONSUMPTION，而不是 QuotaError.RESOURCE_EXHAUSTED。詳情請參閱這篇網誌文章。
GoogleAdsService Search 要求。

將 page_size 傳遞至 GoogleAdsService.Search 會導致 RequestError.PAGE_SIZE_NOT_SUPPORTED 錯誤。
Campaign和Ad

AdvertisingChannelType 為 DISCOVERY 的廣告活動現在的 AdvertisingChannelType 將改為 DEMAND_GEN。

此外，部分廣告會變更報表的類型和欄位名稱：

  • DISCOVERY_MULTI_ASSET_ADD 會變為 DEMAND_GEN_MULTI_ASSET_ADD，對應的報表欄位 ad_group_ad.ad.discovery_multi_asset_ad 將變為 ad_group_ad.ad.demand_gen_multi_asset_ad
  • DISCOVERY_CAROUSEL_AD 會變為 DEMAND_GEN_CAROUSEL_AD，對應的報表欄位 ad_group_ad.ad.discovery_carousel_ad 將變為 ad_group_ad.ad.demand_gen_carousel_ad
  • DISCOVERY_VIDEO_RESPONSIVE_AD 會變為 DEMAND_GEN_VIDEO_RESPONSIVE_AD，對應的報表欄位 ad_group_ad.ad.discovery_video_responsive_ad 將變為 ad_group_ad.ad.demand_gen_video_responsive_ad
AdService 系統將移除 GetAd 端點。如此一來，AdService 就能與 Google Ads API 中的其他服務一致。請參閱擷取物件指南，瞭解擷取廣告和其他資源類型的建議方式。
CustomerLifecycleGoal 和 CampaignLifecycleGoal 重新調整生命週期目標區隔的方式。如需完整總覽，請參閱生命週期目標說明文件的「區隔目標對象」一節。
ProductLink 針對 product_link 執行 GoogleAdsService 搜尋或搜尋串流要求時，您現在只能選取與一項已連結產品相關的欄位。從不同已連結產品中選取多個欄位會導致 QuotaError.PROHIBITED_FIELD_COMBINATION_IN_SELECT_CLAUSE 錯誤。
通報偏誤 已將 metrics.sk_ad_network_conversion_value 欄位重新命名為 metrics.sk_ad_network_fine_conversion_value。

v15 至 v16

服務及其元件變更
AccountLink 已移除 linked_account 中的 data_partner 和 google_ads 連結。改用 ProductLinkService 和 ProductLinkInvitationService。
CampaignLifecycleGoal 之前更新現有的 CampaignLifecycleGoal 時，您會發出符合特定需求的 create 作業。您現在可以改為發出 update 作業，和其他資源類型一樣。
Error Reporting 現在系統傳回一般 ContextError.OPERATION_NOT_PERMITTED_FOR_CONTEXT 錯誤時，會導致更明確的錯誤訊息：
  • CampaignError.CANNOT_LINK_TO_COMPARISON_SHOPPING_SERVICE_ACCOUNT
  • CampaignError.CANNOT_TARGET_NETWORK_FOR_COMPARISON_SHOPPING_SERVICE_LINKED_ACCOUNTS
AudienceInsightsAttributeMetadata 已移除 score 欄位。
KeywordMatchTypeRecommendation 如未設定關鍵字比對類型，API 現在會針對 recommended_match_type 欄位傳回 UNSPECIFIED，而不是 UNKNOWN。

v14 至 v15

服務及其元件變更
AssetGroupListingGroupFilter vertical 列舉欄位已重新命名為 feed_type。
MediaFileService 服務不再需要，因此已遭移除。請參閱下方的 ImageAdInfo 變更。
ImageAdInfo media_file 欄位已由 image_asset 取代。
MerchantCenterLinkService 服務已替換為 ProductLinkInvitationService 和 ProductLinkService。
Campaign.ShoppingSetting 已移除 sales_country 欄位。這項資訊現在會透過 feed_label 欄位傳回。
ProductBiddingCategoryConstant 已替換為 ProductCategoryConstant。我們已視情況重新命名多個欄位，如下圖中的三項變更。
ListingDimensionInfo 將 product_bidding_category 欄位替換為 product_category。
ListingGroupFilterDimension 將 product_bidding_category 欄位替換為 product_category。
shopping_performance_view 報告 下列區隔欄位：
  • product_bidding_category_level1
  • product_bidding_category_level2
  • product_bidding_category_level3
  • product_bidding_category_level4
  • product_bidding_category_level5
已由以下版本取代：
  • product_category_level1
  • product_category_level2
  • product_category_level3
  • product_category_level4
  • product_category_level5
Campaign.shopping_setting 不再支援使用這個欄位建立搜尋廣告活動。
CampaignCriterion.listing_scope 不再支援使用這個欄位建立搜尋廣告活動。
sk_ad_network_conversions 報告 metrics.sk_ad_network_conversions 已由 metrics.sk_ad_network_installs 取代。
OfflineConversionClientSummary 將 offline_conversion_client_summaries 欄位從 Customer 移至可個別查詢的頂層資源。

將查詢從：

SELECT customer.offline_conversion_client_summaries
FROM customer
變更為： 
SELECT
  offline_conversion_upload_client_summary.client,
  offline_conversion_upload_client_summary.status,
  offline_conversion_upload_client_summary.total_event_count,
  offline_conversion_upload_client_summary.successful_event_count,
  offline_conversion_upload_client_summary.last_upload_date_time,
  ...
FROM offline_conversion_upload_client_summary

使用查詢建構工具探索可用欄位清單選取及篩選。
OfflineConversionUploadAlert 已重新命名為 OfflineConversionAlert。
OfflineConversionUploadError 已重新命名為 OfflineConversionError。
AdNetworkType YOUTUBE_SEARCH 和 YOUTUBE_WATCH 列舉已合併為單一列舉： YOUTUBE。