變更與檢查物件

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

批次作業

雖然單一作業只能建立、更新或移除單一資源,但單一變異要求可包含多個作業。您應將作業合併為單一變更要求,而非傳送多個變更要求 (每個要求都包含單一作業)。

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

修改回應

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

變異錯誤

只有在所有請求中的作業都成功時,系統才會將特定變異要求中的作業套用至 Google Ads 帳戶。請參閱常見錯誤指南,瞭解常見錯誤和解決方法。

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

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

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