變更與檢查物件

API 結構指南中所述,Google Ads API 中的每個頂層資源都有相對應的資源類型專屬服務,可支援:

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

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

變更物件

每項資源類型專屬的服務都會有 mutate 方法,用來接受變更請求。這項要求包括:

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

舉例來說,CampaignServiceMutateCampaigns 方法接受由以下內容組成的 MutateCampaignsRequest

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

作業套件

作業物件 (例如 CampaignOperation) 可讓您設定 operation 欄位,藉此指定要對單一資源執行的動作。這個欄位是 oneof 欄位,包含以下屬性類型為資源類型的屬性:

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

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

批次作業

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

舉例來說,假設您想建立十個廣告活動,應傳送含有十個 CampaignOperation 物件的單一 MutateCampaignsRequest

修改回應

回應中傳回的內容取決於 change 要求 response_content_type 中傳送的內容。舉例來說,如果指定 MUTABLE_RESOURCE,則 response 只會包含廣告活動中的可變動欄位。這樣一來,您就可以對該資源物件進行後續變更,而不需重建該物件。

更改錯誤

只有在請求中的每項作業皆成功時,特定變更要求中的作業才會套用到您的 Google Ads 帳戶。請參閱常見錯誤指南,瞭解常見錯誤和解決方法。

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

除了變更物件以外,每個資源類型專屬的服務還包含 get 方法,可擷取單一資源的所有屬性。這個方法接受僅屬性為 resource_name 的 get 要求。

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