變更及檢查物件

API 結構指南中所述,Google Ads API 中的每個頂層資源都有對應的資源類型特定服務,支援以下服務:

  • 修改資源執行個體
  • 擷取資源的單一執行個體以供檢查

本指南會使用 CampaignService 來示範修改和檢查 Campaign 物件,但相同的概念同樣適用於所有其他資源類型的特定服務。

變更物件

每個資源類型專屬的服務都有一個 承包方法,可接受 Variant 要求。這項要求包含:

  • customerId
  • 運算集合
  • 回應的內容類型設定,決定可變動後是否應傳回可變動資源,或只傳回資源名稱。

例如,CampaignServiceMutateCampaigns 方法接受由以下元件組成的 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 要求,則可能會受到頻率限制。