API 結構

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

本指南將說明組成 Google Ads API 的主要元件,Google Ads API 由資源服務組成。資源代表 Google Ads 實體,而服務則負責擷取及操控 Google Ads 實體。

物件階層

Google Ads 帳戶可做為物件階層結構。

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

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

  • 每個廣告活動都包含一或多個廣告群組,可將廣告分成多個邏輯群組。

  • 廣告群組廣告代表您正在放送的廣告。除了每個廣告群組以外,每個廣告群組都只能包含一個廣告群組廣告,但每個廣告群組只包含一或多個廣告群組廣告。

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

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

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

資源

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

物件 ID

Google Ads 中的每個物件都是透過專屬 ID 來識別。其中部分 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

因此,如果是 Google Ads 帳戶 (客戶 ID:1234567) 中廣告活動的 ID 為 987654,則 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 伺服器就會以非同步的方式執行作業,讓相關作業得以執行其他作業。您可以定期檢查工作狀態以確認已完成。

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

變更驗證

大多數的 mut 要求可以在未經實際資料的情況下執行呼叫。您可以測試要求是否缺少參數和不正確的欄位值,而不必實際執行作業。

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

validate_only 尤其用於測試廣告是否違反政策。如果廣告違反特定字詞、標點符號、大寫字母或長度等政策,就會自動拒絕。單一惡質廣告可能會導致整個批次失敗。您可以在 validate_only 要求中測試新廣告,藉此找出任何這類違規事項。請參閱處理違反政策錯誤的程式碼範例,瞭解實際運作情形。

取得物件和效能統計資料

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

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

擷取中繼資料

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

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