本指南將介紹 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 編號 | 全域 | 可 |
廣告編號 | 廣告群組 | 否,但 (AdGroupId 、AdId ) 配對對全域重複 |
AdGroupCriterion 編號 | 廣告群組 | 否,但 (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 伺服器會以非同步的方式執行作業,因此可以釋出執行其他作業的程序。您可以定期檢查工作狀態是否完成。
若要進一步瞭解非同步處理,請參閱批次處理指南。
變更驗證
大部分的 UDF 要求皆可供驗證,而不需要實際對實際資料執行呼叫。您可以測試要求是否缺少參數和不正確的欄位值,而不需要實際執行作業。
如要使用這項功能,請將要求的選用 validate_only
布林值欄位設為 true
。之後,該要求會經過完整驗證,就如同即將執行一樣,但會略過最終的執行作業。如果找不到任何錯誤,則會傳回空白的回應。如果驗證失敗,回應中的錯誤訊息會顯示故障點。
validate_only
特別適合用於測試違反一般政策的廣告。系統會自動拒登違反特定字詞、標點符號、大小寫或長度等政策的廣告。單一不良廣告可能會導致整個批次失敗。在 validate_only
要求中測試新廣告可找出任何違規項目。請參閱處理違反政策的錯誤的程式碼範例,瞭解實際操作情形。
取得物件和效能統計資料
GoogleAdsService
是一個整合式物件服務,可用於擷取物件和效能統計資料。
所有來自 GoogleAdsService
的 Search
和 SearchStream
要求都需要指定要查詢的資源、要擷取的資源屬性和效能指標、用於篩選要求的述詞,以及用於進一步細分效能統計資料的區隔。若要進一步瞭解查詢格式,請參閱 Google Ads 查詢語言指南。
擷取中繼資料
GoogleAdsFieldService
會擷取 Google Ads API 中資源的中繼資料,例如資源的可用屬性及其資料類型。
這項服務會提供建構查詢到 GoogleAdsService
的必要資訊。為方便起見,您也可以在欄位參考說明文件中找到 GoogleAdsFieldService
回傳的資訊。