本指南將介紹 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 | 全域 | 是 |
| 廣告活動編號 | 全域 | 是 |
| 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 為 1234567) 中的廣告活動 ID 為 987654，resource_name 會是：
customers/1234567/campaigns/987654
服務
服務可讓您擷取及修改 Google Ads 實體。服務分為三種類型：修改、物件和統計資料擷取，以及中繼資料擷取服務。
修改 (變異) 物件
這些服務會使用 mutate 要求修改相關資源類型的執行個體。它們也會提供 get 要求，用於擷取單一資源例項，這對於檢查資源結構很有幫助。
服務範例：
CustomerService：用於修改客戶。如要修改廣告活動，請使用
CampaignService。
每個 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 伺服器會以非同步方式執行作業，釋出可執行其他作業的程序。您可以定期檢查工作狀態，確認工作是否已完成。
如要進一步瞭解非同步處理作業，請參閱批次處理指南。
變更驗證
大多數的變異要求都可以驗證，而不需要實際對實際資料執行呼叫。因此，您可以在不實際執行作業的情況下，測試遺漏的參數和不正確的欄位值。
如要使用這項功能，請將要求的選用 validate_only 布林值欄位設為 true。系統會對要求進行完整驗證，就像要執行要求一樣，但會略過最終執行作業。如果沒有發現任何錯誤，系統會傳回空白回應。如果驗證失敗，回應中的錯誤訊息會指出失敗點。
validate_only 特別適合用於測試廣告是否違反常見的政策。如果廣告違反政策 (例如含有特定字詞、標點符號、大寫字母或長度)，系統會自動拒登。單一廣告有問題，可能會導致整個批次失敗。在 validate_only 要求中測試新廣告，即可找出任何違規情形。如要瞭解這項功能的實際運作方式，請參閱處理政策違規錯誤的程式碼範例。
取得物件和成效統計資料
GoogleAdsService 是用於擷取物件和成效統計資料的單一整合服務。
所有 Search 和 SearchStream 要求 (適用於 GoogleAdsService) 都需要查詢，以指定要查詢的資源、要擷取的資源屬性和成效指標、用於篩選要求的述詞，以及用於進一步細分成效統計資料的區隔。如要進一步瞭解查詢格式，請參閱 Google Ads 查詢語言指南。
擷取中繼資料
GoogleAdsFieldService 會擷取 Google Ads API 中資源的中繼資料，例如資源的可用屬性和資料類型。
這項服務會提供建構 GoogleAdsService 查詢所需的資訊。為方便起見，GoogleAdsFieldService 傳回的資訊也提供於欄位參考說明文件中。