本指南將介紹 Google Ads API 的主要元件。Google Ads API 由資源和服務組成。資源代表了 Google Ads 實體,而服務可擷取並操控 Google Ads 實體。
物件階層
Google Ads 帳戶可視為物件階層。
每個帳戶都包含一或多個有效的廣告活動。
每個
Campaign
都包含一或多個廣告群組,用來將廣告分為邏輯集合。每個
AdGroup
都包含一或多個廣告群組廣告。AdGroupAd
代表您所放送的廣告。
您可以將一或多個 AdGroupCriterion
或 CampaignCriterion
附加到廣告群組或廣告活動。這些標準代表了廣告觸發廣告的條件。
條件類型有許多種,例如關鍵字、年齡層和地區。在廣告活動層級定義的條件會影響廣告活動中的所有其他資源。您也可以指定廣告活動層級的預算和日期
最後,您可以在帳戶、廣告活動或廣告群組層級附加額外資訊。您可以利用額外資訊為廣告提供額外資訊,例如電話號碼、街道地址或促銷活動。
資源
資源代表 Google Ads 帳戶中的實體。
Campaign
和 AdGroup
是兩個資源範例。
物件 ID
Google Ads 中的每個物件都有專屬的編號。其中部分 ID 在所有 Google Ads 帳戶中均不可重複,其他 ID 則只在限定範圍內。
物件 ID | 獨特性範圍 | 全域獨一無二? |
---|---|---|
預算 ID | 全域 | 是 |
廣告活動 ID | 全球 | 是 |
AdGroup 編號 | 全域 | 是 |
廣告編號 | Ad Group | 否,但 (AdGroupId 、AdId ) 配對為全域不重複 |
AdGroupCriterion 編號 | Ad Group | 否,但 (AdGroupId 、CriterionId ) 配對為全域不重複 |
CampaignCriterion 編號 | 廣告活動 | 否,但 (CampaignId 、CriterionId ) 配對為全域不重複 |
廣告額外資訊 | 廣告活動 | 否,但 (CampaignId 、AdExtensionId ) 配對為全域不重複 |
動態饋給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
要求,以擷取單一資源執行個體,對於檢查資源的結構很有用。
服務範例:
CustomerService
可用來修改客戶。CampaignService
可用來修改廣告活動。AdGroupService
可用來修改廣告群組。
每個 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
發出的 Search
和 SearchStream
要求都需要查詢以指定資源查詢、要擷取的資源屬性和效能指標、用來篩選要求的述詞,以及用來進一步細分統計資料的區隔。如要進一步瞭解查詢格式,請參閱 Google Ads 查詢語言指南。
擷取中繼資料
GoogleAdsFieldService
可擷取 Google Ads API 中資源的相關中繼資料,例如資源的可用屬性及其資料類型。
這項服務會提供建構查詢到 GoogleAdsService
所需的資訊。此外,欄位參考資料說明文件中也會提供 GoogleAdsFieldService
傳回的資訊。