變更物件

如 API 結構指南所述,Google Ads API 中的每個頂層資源都有對應的資源類型專屬服務,可支援修改資源例項。您也可以使用 GoogleAdsService.Mutate,在單一要求中以原子方式變動多個資源類型。

本指南使用 CampaignService 示範如何修改 Campaign 物件,但同樣的概念也適用於所有其他資源類型專屬服務。

變更要求

每個資源類型專屬服務都有 mutate 方法,可接受變動要求。這項要求包含:

  • customer_id (或 REST 網址中的 customerId)
  • operations 的集合
  • 選用執行設定,例如 partial_failure、validate_only 和 response_content_type (決定修改作業後是否傳回可變動的資源或只有資源名稱)

舉例來說,CampaignService 的 MutateCampaigns 方法會接受 MutateCampaignsRequest,其中包含:

  • A customer_id
  • CampaignOperation 物件的集合 (operations)
  • 選用執行設定 (partial_failure、validate_only 和 response_content_type 表示偏好的回應類型)

作業

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

create
建立資源的新執行個體。
update
更新資源,使其符合 update 資源的屬性。設定這個欄位時,您也必須設定作業的 update_mask,讓 Google Ads API 知道要在更新作業期間修改哪些屬性。每個用戶端程式庫都包含欄位遮罩公用程式或輔助方法,可為您產生 update_mask。
remove
移除資源名稱字串指定的資源 (例如 customers/1234567890/campaigns/987654321)。

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

批次作業

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

舉例來說,如要建立十個廣告活動,請傳送單一 MutateCampaignsRequest,其中包含十個 CampaignOperation 物件。如要將不同資源類型的作業分組為單一要求,請使用 GoogleAdsService.Mutate 或變更資源。

變更回應

回覆中傳回的內容取決於變更要求 response_content_type 欄位中傳送的內容。舉例來說,如果指定 MUTABLE_RESOURCE,則回應會同時包含資源的 resource_name 和廣告活動的可變動欄位 (位於 campaign 中)。依預設 (RESOURCE_NAME_ONLY),每個 MutateCampaignResult 中只會填入 resource_name。

變動錯誤

根據預設 (partial_failure = false),只有在要求中的所有作業都成功時,變更要求中的作業才會套用至 Google Ads 帳戶;如果任何作業失敗,系統會將整個要求復原。對於支援部分失敗的變動要求 (要求訊息中含有 partial_failure 欄位),設定 partial_failure = true 會提交有效作業,而失敗的作業則會在回應的 partial_failure_error 欄位中傳回作業專屬錯誤。如要瞭解如何處理錯誤,請參閱部分失敗指南和常見錯誤指南。

追蹤變更

如要追蹤 Google Ads 帳戶中物件的變更,或擷取物件的目前狀態,可以使用 change_status 和 change_event 資源。

  • change_status 提供指定時間範圍內變更的資源摘要。
  • change_event 提供詳細的變更記錄,包括變更欄位的舊值和新值。

如要查詢這些資源,請使用 GoogleAdsService.SearchStream 或 GoogleAdsService.Search 方法。進一步瞭解如何使用 GoogleAdsService 串流傳輸報表 。