如 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 串流傳輸報表
。