本指南將介紹 Google Ads API 的主要元件。Google Ads API 包含「資源」和「服務」。資源代表 Google Ads 實體,服務則擷取及操控 Google Ads 實體。
物件階層
Google Ads 帳戶可視為物件階層,
客戶的帳戶頂層資源是「客戶」。
每個客戶都包含一或多個有效的廣告活動。
每個廣告活動都包含一或多個廣告群組,用來按邏輯將廣告分組。
廣告群組廣告代表您正在放送的廣告。除了每個廣告群組只能有一個廣告群組廣告以外,其他廣告群組包含一或多個廣告群組廣告。
您可以將一或多個 AdGroupCriterion
或 CampaignCriterion
附加至廣告群組或廣告活動。這些條件定義了廣告的觸發方式。
條件類型有很多種,例如關鍵字、年齡層和地點。在廣告活動層級定義的條件會影響廣告活動中的所有其他資源。也可以指定廣告活動層級的預算和日期。
最後,您可以在帳戶、廣告活動或廣告群組層級附加額外資訊。額外資訊能讓您在廣告中提供額外資訊,例如電話號碼、街道地址或促銷活動。
資源
資源代表 Google Ads 帳戶中的實體。Campaign
和 AdGroup
是兩個資源範例。
物件 ID
Google Ads 中的每個物件都是以專屬 ID 識別。有些 ID 在所有 Google Ads 帳戶中都不重複,有些則在限定範圍內。
物件 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
因此,如果 Google Ads 帳戶中 ID 為 987654
的廣告活動 (客戶 ID 為 1234567
),resource_name
會是:
customers/1234567/campaigns/987654
服務
您可透過「服務」擷取及修改 Google Ads 實體。服務有三種類型:修改、物件和統計資料擷取,以及中繼資料擷取服務。
修改 (mut) 物件
這些服務會使用 mutate
要求來修改關聯資源類型的執行個體。這些 API 也提供擷取單一資源執行個體的 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 的 mut 方法為同步性質。只有物件變更才會傳回 API 呼叫,因此您必須等待每個要求的回應。雖然這種方法對程式碼來說相對簡單,但若程序強制等待呼叫完成,它可能會對負載平衡和資源浪費造成負面影響。
另一種方法是使用 BatchJobService
以非同步方式變更物件,無須等待完成即可對多項服務執行批次作業。提交批次工作後,Google Ads API 伺服器會非同步執行作業,讓執行其他作業的程序更加繁雜。您可以定期檢查工作狀態以確認是否完成。
如要進一步瞭解非同步處理,請參閱批次處理指南。
變更驗證
大部分的 change 請求都可以驗證,不需要實際對實際資料執行呼叫。您可以測試要求,確認是否有遺漏參數和不正確的欄位值,而不必實際執行作業。
如要使用這項功能,請將要求的選用的 validate_only
布林值欄位設為 true
。接著,系統會將要求完全通過驗證,就像實際執行一樣,但系統會略過最終的執行作業。如未發現錯誤,系統會傳回空白回應。如果驗證失敗,回應中的錯誤訊息會指出失敗點。
validate_only
特別適合用來測試常見的政策違規廣告。如果廣告違反政策規定 (例如內含特定字詞、標點符號、大小寫或長度),就會自動拒絕。一個惡質廣告可能會導致整批作業失敗。在 validate_only
請求中測試新廣告,即可找出任何這類違規行為。如需查看處理政策違規錯誤的實例,請參閱這裡的程式碼範例。
取得物體和效能統計資料
GoogleAdsService
是單一整合式服務,可擷取物件和效能統計資料。
針對 GoogleAdsService
的所有 Search
和 SearchStream
要求,您都需要查詢以下查詢:指定要查詢的資源、要擷取的資源屬性和效能指標、篩選要求的述詞,以及用來進一步細分效能統計資料的區隔。如要進一步瞭解查詢格式,請參閱 Google Ads 查詢語言指南。
擷取中繼資料
GoogleAdsFieldService
會擷取 Google Ads API 中的資源相關中繼資料,例如資源的可用屬性及其資料類型。
這項服務會提供建構 GoogleAdsService
查詢時所需的資訊。為了方便起見,您也可以在欄位參考說明文件中取得 GoogleAdsFieldService
傳回的資訊。