變更與檢查物件

API 結構指南所述,Google Ads API 中的每個頂層資源都有支援下列資源類型的特定服務:

  • 修改資源的執行個體
  • 擷取資源的單一執行個體以進行檢查

本指南將使用 CampaignService 示範修改及檢查 Campaign 物件的方式,但相同的概念也適用於所有其他資源類型特定服務。

變更物件

每種資源類型專屬服務都有一個可接受 變更 要求的 mutate 方法。這項要求由:

  • customerId
  • 一系列作業
  • 回應內容類型設定,可決定應在修改後傳回可變動資源或僅傳回資源名稱。

舉例來說,CampaignServiceMutateCampaigns 方法接受 MutateCampaignsRequest,其中包含:

  • customerId
  • 一組 CampaignOperation 物件
  • response_content_type 欄位表示偏好的回應類型。

作業套件

CampaignOperation 等作業物件可讓您設定 operation 欄位,指定要對單一資源執行的操作。這個欄位是一欄位,由以下屬性組成,其類型為資源類型:

create
建立新的資源執行個體。
update
更新資源,使其與 update 資源的屬性相符。 設定這個欄位時,您也必須設定作業的 update_mask,告知 Google Ads API 要在更新作業期間修改哪些屬性。每個用戶端程式庫都有公用程式或輔助方法,可為您產生 update_mask,如用戶端程式庫中所示。
remove
移除資源。

由於 operation 欄位是 oneof 欄位,因此您無法使用一項作業修改多個物件。舉例來說,如要建立一個廣告活動並移除另一個廣告活動,請在要求中加入兩個 CampaignOperation 的例項:一個已設定 create,另一個設有 remove 的例項。

批次作業

雖然一項作業只能建立、更新或移除單一資源,但一項 變動 請求可以包含多個作業。建議您將作業組合成單一 change 請求,而不是傳送每個包含一項作業的多項變更請求。

舉例來說,如果要建立 10 個廣告活動,就應傳送單一 MutateCampaignsRequest,當中含有十個 CampaignOperation 物件。

更改回覆

回應中傳回的內容取決於變更請求的 response_content_type 中傳送的內容。舉例來說,如果指定 MUTABLE_RESOURCE,則回應只會包含廣告活動中可變動的欄位。接著,您可以針對該資源物件進行後續修改,而不必重建該物件。

更改錯誤

只有在請求中的「每次」作業成功時,特定 change 請求中的作業才會套用到您的 Google Ads 帳戶。請參閱常見錯誤指南,查看常見錯誤清單和解決方法。

使用 get 檢查物件 (已淘汰)

除了變更物件之外,每種資源類型專屬服務也都有 get 方法,可用來擷取單一資源的所有屬性。此方法接受僅屬性為 resource_name 的 get 要求。

取得方法是 Google Ads API 提供的便利方法,方便您擷取單一物件的所有屬性。雖然這是學習 API 或檢查個別物件以進行偵錯或教育用途的絕佳工具,但應用程式不應使用 get 方法擷取物件以進行處理或回報。請改用 GoogleAdsService,因為您只能擷取物件的特定屬性、支援擷取效能指標,並允許串流處理大型結果集。如果應用程式提交大量取得要求,可能會遇到頻率限制。