本指南將介紹 Google Ads API 的主要組成元件。Google Ads API 包含資源和服務。資源代表 Google Ads 實體，而服務則會擷取及操控 Google Ads 實體。
物件階層
Google Ads 帳戶可視為物件階層。
帳戶的頂層資源是客戶。
每個客戶都包含一或多個有效的廣告活動。
每個廣告活動都包含一或多個廣告群組，用於將廣告分門別類。
廣告群組廣告代表您在廣告群組中放送的廣告。除了應用程式廣告活動 (每個廣告群組只能有一個廣告群組廣告) 之外，每個廣告群組都包含一或多個廣告群組廣告。
最高成效廣告活動的結構與其他廣告活動類型不同：最高成效廣告活動不含廣告群組和廣告群組廣告，而是包含素材資源群組。您可以使用 AssetGroupAsset 將廣告素材資源連結至素材資源群組，並使用 AssetGroupSignal 附加目標對象或搜尋主題信號。
您可以將一或多個 AdGroupCriterion 或 CampaignCriterion 資源附加至廣告群組或廣告活動。這些條件定義了廣告的觸發方式。
條件類型有很多種，例如關鍵字、年齡層和地區。在廣告活動層級定義的條件會影響廣告活動中的所有其他資源。您也可以使用 AdGroupAd.start_date_time 和 AdGroupAd.end_date_time，為廣告活動或個別廣告指定預算，以及開始和結束日期與時間。
最後，您可以在帳戶、廣告活動、廣告群組或素材資源群組層級附加素材資源。素材資源可讓您在廣告中提供額外資訊，例如電話號碼、街道地址或促銷活動。請參閱「素材資源總覽」。
資源
資源代表 Google Ads 帳戶中的實體。Campaign 和 AdGroup 是兩種資源範例。
物件 ID
Google Ads 中的每個物件都有專屬 ID。其中部分 ID 在所有 Google Ads 帳戶中都是全域不重複，其他 ID 則僅在限定範圍內不重複。
| 物件 ID | 獨特性範圍 | 是否具有全域獨特性？ |
|---|---|---|
| 預算編號 | 全域 | 是 |
| 廣告活動編號 | 全域 | 是 |
| AdGroup 編號 | 全域 | 是 |
| 廣告 ID | 廣告群組 | 否，但 (AdGroupId、AdId) 組合在全域中是唯一的。禁止在多個廣告群組中共用AdId。 |
| AdGroupCriterion 編號 | 廣告群組 | 否，但 (AdGroupId、CriterionId) 組合在全球是唯一的 |
| CampaignCriterion 編號 | 廣告活動 | 否，但 (CampaignId、CriterionId) 組合在全球是唯一的 |
| 標籤 ID | 客戶 | 否，但 (CustomerId、LabelId) 組合在全球是唯一的 |
| UserList ID | 全球 | 是 |
| 資產 ID | 全球 | 是 |
為 Google Ads 物件設計本機儲存空間時，這些 ID 規則會很有幫助。
部分物件可用於多種實體類型。在這種情況下，物件會包含說明內容的 type 欄位。舉例來說，AdGroupAd 可以指回應式搜尋廣告、飯店廣告或需求開發廣告等物件。這個值可透過 AdGroupAd.ad.type 欄位存取，並傳回 AdType 列舉中的值。注意：
可變動性可能因版本而異 (例如，Ad 上的 VideoResponsiveAdInfo 在 v24 及更新版本中
可變)。
資源名稱
每項資源都有專屬的 resource_name 字串，可將資源及其父項串連成路徑。舉例來說，廣告活動資源名稱的格式如下：
customers/customer_id/campaigns/campaign_id
因此，如果廣告活動 ID 為 987654，且 Google Ads 帳戶的客戶 ID 為 1234567，則 resource_name 為：
customers/1234567/campaigns/987654
服務
服務可讓您擷取及修改 Google Ads 實體。服務分為三種：修改、物件和統計資料擷取，以及中繼資料擷取服務。
修改 (變更) 物件
資源專屬服務會使用 mutate 要求，修改相關聯資源類型的執行個體。您也可以使用 GoogleAdsService.Mutate，在單一要求中對多種資源類型執行原子異動 (例如同時建立廣告活動預算、廣告活動和廣告群組)。
資源專屬服務範例：
CustomerService：用於修改客戶。
每個 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。系統會完整驗證要求，就像要執行要求一樣，但會略過最終執行。如果未發現任何錯誤，系統會傳回回應，但不會填入任何異動結果 (results 為空白)。如果驗證失敗，要求預設會失敗，並傳回 GoogleAdsFailure RPC 錯誤 (partial_failure = false)，或在 partial_failure = true 時傳回正常回應，並在 partial_failure_error 中傳回作業專屬錯誤。
validate_only 特別適合用來測試廣告是否違反常見政策。如果廣告違反政策 (例如含有特定字詞、標點符號、大寫字母或長度不符規定)，系統會自動拒登。只要有一則惡質廣告，就可能導致整批廣告失敗。在 validate_only 請求中測試新廣告，可找出這類違規情形。請參閱處理違反政策錯誤的程式碼範例，瞭解實際運作方式。
取得物件和效能統計資料
GoogleAdsService 是單一、統一的服務，用於擷取物件和效能統計資料。
GoogleAdsService 的所有 Search 和 SearchStream 要求，都必須包含查詢，指定要查詢的資源、要擷取的資源屬性和成效指標、用於篩選要求的述詞，以及用於進一步細分成效統計資料的區隔。如要進一步瞭解查詢格式，請參閱 Google Ads 查詢語言指南。
擷取中繼資料
GoogleAdsFieldService 會擷取 Google Ads API 中資源的中繼資料，例如資源的可用屬性及其資料類型。如要瞭解如何查詢這項服務，請參閱資源中繼資料指南。
這項服務會提供建構 GoogleAdsService 查詢所需的資訊。為方便起見，GoogleAdsFieldService 傳回的資訊也可在欄位參考文件中找到。