本指南將說明組成 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 | 全域 | 是 |
| 廣告活動 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用於修改廣告活動。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 伺服器就會以非同步的方式執行作業，讓相關作業得以執行其他作業。您可以定期檢查工作狀態以確認已完成。
若要進一步瞭解非同步處理，請參閱批次處理指南。
變更驗證
大多數的 mut 要求可以在未經實際資料的情況下執行呼叫。您可以測試要求是否缺少參數和不正確的欄位值，而不必實際執行作業。
如要使用這項功能，請將要求的選用 validate_only 布林值欄位設為 true。系統接著會完整驗證該要求是否繼續執行，但系統會略過最終執行作業。如果找不到任何錯誤，系統會傳回空白回應。如果驗證失敗，回應中的錯誤訊息會顯示失敗點。
validate_only 尤其用於測試廣告是否違反政策。如果廣告違反特定字詞、標點符號、大寫字母或長度等政策，就會自動拒絕。單一惡質廣告可能會導致整個批次失敗。您可以在 validate_only 要求中測試新廣告，藉此找出任何這類違規事項。請參閱處理違反政策錯誤的程式碼範例，瞭解實際運作情形。
取得物件和效能統計資料
GoogleAdsService 是整合式的單一服務，可用於擷取物件和效能統計資料。
所有 GoogleAdsService 的 Search 和 SearchStream 要求都需要指定查詢的查詢、要擷取的資源屬性和效能指標、用於篩選要求的述詞，以及用於進一步細分效能統計資料的區段。如要進一步瞭解查詢格式，請參閱 Google Ads 查詢語言指南。
擷取中繼資料
GoogleAdsFieldService 會擷取 Google Ads API 中的資源中繼資料，例如資源的可用屬性及其資料類型。
這項服務提供建立 GoogleAdsService 查詢時所需的資訊。為了方便起見，您也可以在欄位參考說明文件中找到 GoogleAdsFieldService 傳回的資訊。