如 API 結構指南所述,Google Ads API 中的每個頂層資源都有支援下列資源類型的特定服務:
- 修改資源的執行個體
- 擷取資源的單一執行個體以進行檢查
本指南將使用 CampaignService
示範修改及檢查 Campaign
物件的方式,但相同的概念也適用於所有其他資源類型特定服務。
變更物件
每種資源類型專屬服務都有一個可接受 變更 要求的 mutate 方法。這項要求由:
customerId
- 一系列作業
- 回應內容類型設定,可決定應在修改後傳回可變動資源或僅傳回資源名稱。
舉例來說,CampaignService
的 MutateCampaigns
方法接受 MutateCampaignsRequest
,其中包含:
customerId
- 一組
CampaignOperation
物件 response_content_type
欄位表示偏好的回應類型。
作業套件
CampaignOperation
等作業物件可讓您設定 operation
欄位,指定要對單一資源執行的操作。這個欄位是一欄位,由以下屬性組成,其類型為資源類型:
create
- 建立新的資源執行個體。
update
- 更新資源,使其與
update
資源的屬性相符。 設定這個欄位時,您也必須設定作業的update_mask
,告知 Google Ads API 要在更新作業期間修改哪些屬性。每個用戶端程式庫都有公用程式或輔助方法,可為您產生update_mask
,如用戶端程式庫中所示。 remove
- 移除資源。
由於 operation
欄位是 oneof
欄位,因此您無法使用一項作業修改多個物件。舉例來說,如要建立一個廣告活動並移除另一個廣告活動,請在要求中加入兩個 CampaignOperation
的例項:一個已設定 create
,另一個設有 remove
的例項。
批次作業
雖然一項作業只能建立、更新或移除單一資源,但一項 變動 請求可以包含多個作業。建議您將作業組合成單一 change 請求,而不是傳送每個包含一項作業的多項變更請求。
舉例來說,如果要建立 10 個廣告活動,就應傳送單一 MutateCampaignsRequest
,當中含有十個 CampaignOperation
物件。
更改回覆
回應中傳回的內容取決於變更請求的 response_content_type
中傳送的內容。舉例來說,如果指定 MUTABLE_RESOURCE
,則回應只會包含廣告活動中可變動的欄位。接著,您可以針對該資源物件進行後續修改,而不必重建該物件。
更改錯誤
只有在請求中的「每次」作業成功時,特定 change 請求中的作業才會套用到您的 Google Ads 帳戶。請參閱常見錯誤指南,查看常見錯誤清單和解決方法。
使用 get 檢查物件 (已淘汰)
除了變更物件之外,每種資源類型專屬服務也都有 get 方法,可用來擷取單一資源的所有屬性。此方法接受僅屬性為 resource_name
的 get 要求。
取得方法是 Google Ads API 提供的便利方法,方便您擷取單一物件的所有屬性。雖然這是學習 API 或檢查個別物件以進行偵錯或教育用途的絕佳工具,但應用程式不應使用 get 方法擷取物件以進行處理或回報。請改用 GoogleAdsService
,因為您只能擷取物件的特定屬性、支援擷取效能指標,並允許串流處理大型結果集。如果應用程式提交大量取得要求,可能會遇到頻率限制。