如API 結構指南所述,Google Ads API 中的每個頂層資源都有對應的資源類型專屬服務,可支援下列項目:
- 修改資源的執行個體
- 擷取單一資源例項進行檢查
本指南將使用 CampaignService
示範如何修改及檢查 Campaign
物件,但相同的概念也適用於所有其他資源類型專屬服務。
變更物件
每個資源類型專屬服務都會有可接受變更要求的 mutate 方法。這項要求包含:
customerId
- 一組作業
- 回應內容類型設定,用於決定應在變動後傳回可變動資源,還是只傳回資源名稱。
舉例來說,CampaignService
的 MutateCampaigns
方法會接受 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 要求,可能會遇到頻率限制。