本指南介绍了构成 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 | 唯一性的范围 | 是否在全局级别具有唯一性？ |
|---|---|---|
| 预算 ID | 全局 | 是 |
| 广告系列 ID | 全局 | 是 |
| AdGroup ID | 全局 | 是 |
| 广告 ID | Google Ads 广告组 | 否，但 (AdGroupId, AdId) 对是全局唯一的。禁止在多个广告组之间共享 AdId。 |
| AdGroupCriterion ID | Google Ads 广告组 | 否，但 (AdGroupId, CriterionId) 对是全局唯一的 |
| CampaignCriterion ID | 广告系列 | 否，但 (CampaignId, CriterionId) 对是全局唯一的 |
| 标签 ID | 客户 | 否，但 (CustomerId, LabelId) 对是全局唯一的 |
| UserList ID | 全局 | 是 |
| 资产 ID | 全局 | 是 |
在为 Google Ads 对象设计本地存储时，这些 ID 规则可能会很有用。
某些对象可用于多种实体类型。在这种情况下，对象包含一个 type 字段，用于描述其内容。例如，
AdGroupAd 可以引用自适应搜索广告、酒店广告或需求开发广告等对象。您可以通过
AdGroupAd.ad.type字段访问此值，并返回
AdType枚举中的值。请注意，
可变性可能因版本而异（例如，VideoResponsiveAdInfo 上的 Ad 在 v24 及更高版本中是
可变的）。
资源名称
每个资源都由一个 resource_name 字符串唯一标识，该字符串将资源及其父项连接成一个路径。例如，广告系列资源名称的格式如下：
customers/customer_id/campaigns/campaign_id
因此，对于 Google Ads 账号中客户 ID 为 1234567 的广告系列（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 转变方法是同步的。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 是用于检索对象和效果统计信息的单一统一服务。
所有 Search 和
SearchStream 请求
GoogleAdsService都需要查询，该查询用于指定要查询的资源、要检索的资源属性和效果指标
、用于过滤请求的谓词，以及用于进一步细分效果统计信息的分段。如需详细了解
查询格式，请参阅Google Ads 查询语言指南。
检索元数据
GoogleAdsFieldService 用于检索 Google Ads API 中有关资源的元数据，例如资源的可用属性及其数据类型。如需详细了解如何查询此服务，请参阅资源元数据
指南。
此服务提供构建
GoogleAdsService查询所需的信息。为方便起见，
字段参考文档中也提供了
GoogleAdsFieldService返回的信息。