如 API 結構指南中所述,Google Ads API 中的每個頂層資源都有對應的資源類型特定服務,支援以下服務:
- 修改資源執行個體
- 擷取資源的單一執行個體以供檢查
本指南會使用 CampaignService
來示範修改和檢查 Campaign
物件,但相同的概念同樣適用於所有其他資源類型的特定服務。
變更物件
每個資源類型專屬的服務都有一個 承包方法,可接受 Variant 要求。這項要求包含:
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
。
批次處理作業
雖然單一作業只能建立、更新或移除單一資源,但單一變更要求中可以包含多項作業。您應該將作業結合成一個 變更 要求,而不是傳送多個 單項 要求,且每個 要求都包含一個 作業。
舉例來說,如果您要建立 10 個廣告活動,應傳送包含 10 個 CampaignOperation
物件的單一 MutateCampaignsRequest
。
修改回應
回應中傳回的內容取決於 var 要求的 response_content_type
中傳送的內容。例如,如果指定 MUTABLE_RESOURCE
,則 response 只會包含廣告活動中的可變動欄位。然後,您可以在該資源物件上進行後續追蹤,且不必重新建構。
異動錯誤
請求的「所有」作業都成功後,只有特定「要求」請求中的作業才會套用至 Google Ads 帳戶。請參閱常見錯誤指南瞭解常見錯誤清單及解決方法。
使用 get 檢查物件 (已淘汰)
除了變更物件之外,每項資源類型專屬的服務都有 get 方法,可用來擷取單一資源的所有屬性。此方法可接受只有 resource_name
屬性的 get 要求。
get 方法是 Google Ads API 提供的便利工具,可讓您輕鬆擷取單一物件的所有屬性。雖然這是學習 API 或檢查個別物件以偵錯或教育用途的絕佳工具,但您的應用程式不應使用 get 方法擷取物件以處理或回報。而是使用 GoogleAdsService
,因為您可以只擷取物件的特定屬性、支援擷取效能指標,並允許透過大型結果集進行串流。如果您的應用程式提交大量 get 要求,則可能會受到頻率限制。