本指南將介紹 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
Service
您可以使用「服務」擷取及修改 Google Ads 實體。服務有三種類型：修改、物件和統計資料擷取，以及中繼資料擷取服務。
修改 (變更) 物件
這些服務會使用 mutate 要求修改相關聯資源類型的執行個體。也會提供 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 的 變更 方法為同步性質。API 呼叫只會在物件變更後才會傳回回應，因此您必須等待每個要求的回應。雖然此方法相對易於編寫程式碼，但如果程序必須等待呼叫完成，就會對負載平衡造成負面影響，並浪費資源。
另一種方法是使用 BatchJobService 以非同步方式變更物件，這樣就能在多項服務上執行批次作業，不必等待作業完成。提交批次工作後，Google Ads API 伺服器會以非同步方式執行作業，釋出執行其他作業的程序。您可以定期檢查工作狀態是否完成。
如要進一步瞭解非同步處理，請參閱批次處理指南。
變更驗證
大多數 變動要求都可以驗證，不需要實際對實際資料執行呼叫。此時，您可以在不實際執行作業的情況下，測試要求是否有參數和欄位值有誤。
如要使用這項功能，請將要求的選用 validate_only 布林值欄位設為 true。接著，系統會像將執行要求一樣完整驗證要求，但會略過最後的執行作業。如果未發現錯誤，則會傳回空白回應。如果驗證失敗，回應中的錯誤訊息會指出失敗點。
validate_only 特別適合用來測試違反常見政策的廣告。如果廣告違反政策 (例如含有特定字詞、標點符號、大小寫或長度等)，就會自動拒絕。單一錯誤廣告可能會導致整個批次失敗。在 validate_only 請求中測試新廣告，有助於找出任何這類違規行為。如要瞭解處理政策違規錯誤的方式，請參閱處理政策違規錯誤的程式碼範例。
取得物件和效能統計資料
GoogleAdsService 是單一的整合式服務，用於擷取物件和效能統計資料。
GoogleAdsService 的所有 Search 和 SearchStream 要求都需要下列查詢：指定要查詢的資源、要擷取的資源屬性和效能指標、篩選要求的述詞，以及用來進一步細分效能統計資料的區隔。如要進一步瞭解查詢格式，請參閱 Google Ads 查詢語言指南。
擷取中繼資料
GoogleAdsFieldService 會擷取 Google Ads API 中資源的相關中繼資料，例如資源的可用屬性及其資料類型。
這項服務提供建構查詢至 GoogleAdsService 所需的資訊。為方便起見，您也可以在欄位參考說明文件中取得 GoogleAdsFieldService 傳回的資訊。