本指南介绍了构成 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 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 为 1234567 的 Google Ads 账号中 ID 为 987654 的广告系列，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。
异步 mutate 与同步 mutate
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 返回的信息。