API 結構

影片：查看 2019 年講習課程的「服務」與「資源」講座

本指南將介紹 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 要求，以擷取單一資源執行個體，對於檢查資源的結構很有用。

服務範例：

每個 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 傳回的資訊。

上一頁
總覽
下一頁
實體關係