本指南介绍了 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 ID | 全局 | 是 |
| 广告 ID | 广告组 | 否，但是 (AdGroupId, AdId) 对在全局级别具有唯一性 |
| AdGroupCriterion ID | 广告组 | 否，但是 (AdGroupId, CriterionId) 对在全局级别具有唯一性 |
| CampaignCriterion ID | 广告系列 | 否，但是 (CampaignId, CriterionId) 对在全局级别具有唯一性 |
| 广告附加信息 | 广告系列 | 否，但是 (CampaignId, AdExtensionId) 对在全局级别具有唯一性 |
| Feed ID | 全局 | 是 |
| Feed Item ID | 全局 | 是 |
| Feed Attribute ID | Feed | 否 |
| Feed Mapping ID | 全局 | 是 |
| 标签 ID | 全局 | 是 |
| 用户名单 ID | 全球 | 是 |
在为 Google Ads 设计本地存储时，这些 ID 规则会很有用 对象的操作。
某些对象可用于多种实体类型。在这种情况下，对象
包含描述其内容的 type 字段。例如：
AdGroupAd 可以引用文字广告等对象。
酒店广告或本地广告可以通过
AdGroupAd.ad.type 字段，并在
AdType 枚举。
资源名称
每个资源都由一个 resource_name 字符串唯一标识，
用于将资源及其父项串联到路径中。例如，广告系列
资源名称采用以下格式：
customers/customer_id/campaigns/campaign_id
因此，对于客户 ID 为 987654 的 Google Ads 账号中 ID 为 987654 的广告系列
1234567，则 resource_name 为：
customers/1234567/campaigns/987654
服务
通过服务，您可以检索和修改 Google Ads 实体。服务类型有三种 服务：修改、对象和统计数据检索以及元数据检索 服务。
修改 (mutate) 对象
这些服务使用 mutate 修改关联资源类型的实例
请求。它们还会提供一个 get 请求，用于检索单个资源
实例，这对于检查资源的结构非常有用。
服务示例：
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。然后系统会对请求进行全面验证，就好像
但会跳过最终的执行。如果没有找到错误，则将
响应。如果验证失败，响应中的错误消息将
来指明故障点
validate_only 在测试广告是否符合通用政策时特别有用
违规行为。违反以下政策的广告会自动拒绝：
包含特定字词、标点、大小写或长度。一个不良广告
可能会导致整个批次失败。在 validate_only 中测试新广告
披露任何此类违规行为。请参阅有关处理
“违反合作规范错误”
。
获取对象和效果统计信息
GoogleAdsService 是一个统一的统一平台
用于检索对象和效果统计信息的服务。
针对 GoogleAdsService 的所有 Search 和 SearchStream 请求都需要一个指定相应资源的查询，以便
要检索的资源特性和性能指标、
用于过滤请求的谓词，以及用于进一步
对效果统计信息进行细分如需详细了解查询格式
请查看 Google Ads 查询语言指南。
检索元数据
GoogleAdsFieldService 检索
Google Ads API 中资源的相关元数据，例如
资源及其数据类型。
该服务提供了构建查询所需的信息，以便
GoogleAdsService。为方便起见，
返回的信息
您也可以使用GoogleAdsFieldService
字段参考文档