API 結構

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

影片:觀看 2019 年研討會的服務和資源講座

本指南將介紹 Google Ads API 的組成要素。Google Ads API 包含資源服務。資源代表 Google Ads 實體,服務則擷取並操控 Google Ads 實體。

物件階層

Google Ads 帳戶可以檢視為物件階層。

  • 帳戶的頂層資源是「客戶」

  • 每個帳戶都包含一個或多個有效的廣告活動

  • 每個 Campaign 都包含一個或多個廣告群組,可用來將廣告按邏輯分類。

  • 每個AdGroup包含一個或多個廣告群組廣告AdGroupAd 代表您所放送的廣告。

您可以將一或多個 AdGroupCriterionCampaignCriterion 附加至廣告群組或廣告活動。這些條件可定義廣告的觸發方式。

有多種條件類型,例如關鍵字、年齡層和地區。廣告活動層級定義的條件會影響廣告活動中的所有其他資源。您也可以指定廣告活動層級的預算和日期。

最後,您可以在帳戶、廣告活動或廣告群組層級附加額外資訊。使用額外資訊,您就能為廣告提供 額外資訊,例如電話號碼、街道地址或促銷訊息。

資源

資源代表 Google Ads 帳戶中的實體。 CampaignAdGroup 是兩個資源範例。

物件 ID

Google Ads 中的每個物件都有各自的編號,其中部分 ID 在所有 Google Ads 帳戶中全域唯一,其他 ID 則只會在限定範圍內。

物件 ID 唯一性範圍 全域唯一?
預算 ID 全域
廣告活動 ID 全域
AdGroup 編號 全域
廣告編號 廣告群組 否,但 (AdGroupIdAdId) 配對對全域重複
AdGroupCriterion 編號 廣告群組 否,但 (AdGroupIdCriterionId) 配對對全域重複
CampaignCriterion 編號 廣告活動 否,但 (CampaignIdCriterionId) 配對對全域重複
廣告額外資訊 廣告活動 否,但 (CampaignIdAdExtensionId) 配對對全域重複
動態饋給ID 全域
資訊提供項目編號 全域
資訊提供屬性編號 資訊提供
資訊提供對應編號 全域
標籤編號 全域
使用者名單 ID 全域

為 Google Ads 物件設計本機儲存空間時,這些 ID 規則會很有幫助。

部分物件可用於多個實體類型。在這類情況下,物件會包含描述其內容的 type 欄位。舉例來說,AdGroupAd 可參照文字廣告、飯店廣告、區域廣告等。您可以透過 AdGroupAd.ad.type 欄位存取這個值,並在 AdType 列舉中傳回一個值。

資源名稱

每個資源都由 resource_name 字串唯一識別,這會將資源及其父項串連成路徑。例如,廣告活動資源名稱的格式如下:

customers/customer_id/campaigns/campaign_id

因此,對於 ID 為 987654 的 Google Ads 帳戶 (客戶 ID 為 1234567) 的廣告活動,resource_name 會是:

customers/1234567/campaigns/987654

服務

「服務」可讓您擷取及修改 Google Ads 實體。服務有三種類型:修改、物件和統計資料擷取,以及中繼資料擷取服務。

修改 (變化) 物件

這些服務使用 mutate 要求修改相關資源類型的執行個體。也提供提供單一資源執行個體的 get 要求,可用於檢查資源結構。

服務範例:

每個 mutate 要求都必須包含對應的 operation 物件。舉例來說,CampaignService.MutateCampaigns 方法預期一或多個 CampaignOperation 執行個體。如需作業的詳細討論,請參閱變更及檢查物件

同時變更

Google Ads 物件無法同時由多個來源修改,如果有多位使用者透過應用程式更新同一個物件,或是您使用多個執行緒同時變更 Google Ads 物件,則可能會產生錯誤。其中包括透過相同應用程式或多個應用程式 (例如您的應用程式與同時 Google Ads UI 工作階段) 的多個執行緒更新物件。

API 並未提供在更新前鎖定物件的方法;如果兩個來源嘗試同時變更物件,API 會引發 DatabaseError.CONCURRENT_MODIFICATION_ERROR

非同步和同步變更

Google Ads API 變更方法為同步程序。只有在物件發生變更時,API 呼叫才會傳回回應,因此您必須等待每個要求的回應。雖然這個方法對程式碼而言相對簡單,但如果作業被迫等待呼叫完成,就會對負載平衡和廢棄資源產生負面影響。

另一種方法是使用 BatchJobService 以非同步的方式變更物件,該物件會在多項服務中執行批次作業,不必等待完成。送出批次工作後,Google Ads API 伺服器會以非同步的方式執行作業,因此可以釋出執行其他作業的程序。您可以定期檢查工作狀態是否完成。

若要進一步瞭解非同步處理,請參閱批次處理指南

變更驗證

大部分的 UDF 要求皆可供驗證,而不需要實際對實際資料執行呼叫。您可以測試要求是否缺少參數和不正確的欄位值,而不需要實際執行作業。

如要使用這項功能,請將要求的選用 validate_only 布林值欄位設為 true。之後,該要求會經過完整驗證,就如同即將執行一樣,但會略過最終的執行作業。如果找不到任何錯誤,則會傳回空白的回應。如果驗證失敗,回應中的錯誤訊息會顯示故障點。

validate_only 特別適合用於測試違反一般政策的廣告。系統會自動拒登違反特定字詞、標點符號、大小寫或長度等政策的廣告。單一不良廣告可能會導致整個批次失敗。在 validate_only 要求中測試新廣告可找出任何違規項目。請參閱處理違反政策的錯誤的程式碼範例,瞭解實際操作情形。

取得物件和效能統計資料

GoogleAdsService 是一個整合式物件服務,可用於擷取物件和效能統計資料。

所有來自 GoogleAdsServiceSearchSearchStream 要求都需要指定要查詢的資源、要擷取的資源屬性和效能指標、用於篩選要求的述詞,以及用於進一步細分效能統計資料的區隔。若要進一步瞭解查詢格式,請參閱 Google Ads 查詢語言指南

擷取中繼資料

GoogleAdsFieldService 會擷取 Google Ads API 中資源的中繼資料,例如資源的可用屬性及其資料類型。

這項服務會提供建構查詢到 GoogleAdsService 的必要資訊。為方便起見,您也可以在欄位參考說明文件中找到 GoogleAdsFieldService 回傳的資訊。