本指南将介绍构成 Google Ads API 的主要组件。Google Ads API 由资源和服务组成。资源表示 Google Ads 实体，而服务用于检索和操纵 Google Ads 实体。
对象层次结构
Google Ads 账号可以视为一个对象层次结构。
账号的顶级资源是 customer。
每个客户都包含一个或多个有效广告系列。
每个广告系列都包含一个或多个广告组，用于将广告分组为逻辑集合。
广告组广告是指您在广告组中投放的广告。除了每个广告组只能包含一个广告组广告的应用广告系列之外，每个广告组都包含一个或多个广告组广告。
效果最大化广告系列的结构与其他广告系列类型不同：效果最大化广告系列包含素材资源组，而不是广告组和广告组广告。您可以使用 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 | 唯一性的范围 | 是否在全局级别具有唯一性？ |
|---|---|---|
| 预算 ID | 全局 | 是 |
| 广告系列 ID | 全局 | 是 |
| AdGroup ID | 全局 | 是 |
| 广告 ID | Google Ads 广告组 | 否，但 (AdGroupId, AdId) 对是全局唯一的。禁止在多个广告组中共享 AdId。 |
| AdGroupCriterion ID | Google Ads 广告组 | 否，但 (AdGroupId, CriterionId) 对在全球范围内是唯一的 |
| CampaignCriterion ID | 广告系列 | 否，但 (CampaignId, CriterionId) 对在全球范围内是唯一的 |
| 标签 ID | 客户 | 否，但 (CustomerId, LabelId) 对在全球范围内是唯一的 |
| 用户名单 ID | 全球 | 是 |
| 资产 ID | 全球 | 是 |
在为 Google Ads 对象设计本地存储时，这些 ID 规则可能很有用。
某些对象可用于多种实体类型。在这种情况下，对象包含一个 type 字段，用于描述其内容。例如，AdGroupAd 可以指自适应搜索广告、酒店广告或需求开发广告等对象。可以通过 AdGroupAd.ad.type 字段访问此值，并返回 AdType 枚举中的值。请注意，可变性可能因版本而异（例如，VideoResponsiveAdInfo 在 Ad 上在 v24 及更高版本中是可变的）。
资源名称
每项资源都由一个 resource_name 字符串唯一标识，该字符串将资源及其父项串联成一个路径。例如，广告系列资源名称采用以下格式：
customers/customer_id/campaigns/campaign_id
因此，对于客户 ID 为 1234567 的 Google Ads 账号中 ID 为 987654 的广告系列，resource_name 将为：
customers/1234567/campaigns/987654
服务
您可以使用服务检索和修改 Google Ads 实体。服务分为三种类型：修改服务、对象和统计信息检索服务以及元数据检索服务。
修改 (mutate) 对象
特定于资源的服务使用 mutate 请求修改关联资源类型的实例。您还可以使用 GoogleAdsService.Mutate 在单个请求中对多种资源类型执行原子性更改（例如，同时创建广告系列预算、广告系列和广告组）。
特定于资源的服务示例：
CustomerService用于修改客户。CampaignService用于修改广告系列。AdGroupService，用于修改广告组。
每个 mutate 请求都必须包含相应的 operation 对象。例如，CampaignService.MutateCampaigns 方法需要一个或多个 CampaignOperation 实例。如需详细了解操作，请参阅更改对象。
并发转变
不能同时由多个来源并行修改 Google Ads 对象。如果您有多个用户通过您的应用更新同一对象，或者您使用多个线程并行更改 Google Ads 对象，则可能会出现错误。这包括从同一应用中的多个线程更新对象，或从不同应用（例如，您的应用和同时进行的 Google Ads 界面会话）更新对象。
该 API 不提供在更新之前锁定对象的方法；如果两个来源尝试同时更改某个对象，该 API 会引发 DatabaseError.CONCURRENT_MODIFICATION_ERROR。
异步与同步突变
Google Ads API mutate 方法是同步的。API 调用仅在对象发生变异后才返回响应，因此您需要等待每个请求的响应。虽然这种方法在编码方面相对简单，但如果进程被迫等待调用完成，可能会对负载平衡产生负面影响并浪费资源。
另一种方法是使用 BatchJobService 异步更改对象，该方法可对多个服务执行批量操作，而无需等待这些操作完成。提交批量作业后，Google Ads API 服务器会异步执行操作，从而释放进程以执行其他操作。您可以定期检查作业状态，了解作业是否已完成。
如需详细了解异步处理，请参阅批量处理指南。
转变验证
大多数 mutate 请求都可以进行验证，而无需针对实际数据执行调用。您可以测试缺少参数和字段值不正确的请求，而无需实际执行操作。
如需使用此功能，请将请求的可选 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 返回的信息也可在字段参考文档中找到。