本指南將介紹 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 | 全球 | 是 |
| 資產 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 使用者介面工作階段)。
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 傳回的資訊也提供於欄位參考說明文件。