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 編號 全域
廣告編號 Ad Group 否,但 (AdGroupIdAdId) 配對為全域不重複
AdGroupCriterion 編號 Ad Group 否,但 (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 伺服器會以非同步的方式執行作業,讓處理程序得以執行其他作業。您可以定期檢查工作狀態以完成工作。

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

變更驗證

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

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

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

取得物件和效能統計資料

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

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

擷取中繼資料

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

這項服務會提供建構查詢到 GoogleAdsService 所需的資訊。此外,欄位參考資料說明文件中也會提供 GoogleAdsFieldService 傳回的資訊。