API 结构

视频:查看 2019 年研讨会的“服务和资源”演讲

本指南介绍了 Google Ads API 的主要组成部分。Google Ads API 由多个资源和服务组成。资源表示 Google Ads 实体,而服务则用于检索和操纵 Google Ads 实体。

对象层次结构

Google Ads 帐号可以视为对象层次结构。

  • 帐号的顶级资源是客户

  • 每个帐号包含一个或多个有效的广告系列

  • 每个 Campaign 包含一个或多个广告组,用于按逻辑将您的广告分组。

  • 每个 AdGroup 包含一个或多个广告组广告AdGroupAd 表示您正在投放的广告。

您可以将一个或多个 AdGroupCriterionCampaignCriterion 附加到广告组或广告系列。它们代表着定义广告触发方式的条件。

有很多条件类型,如关键字、年龄段和地理位置。在广告系列一级定义的条件会影响广告系列中的所有其他资源。您还可以指定整个广告系列的预算和日期。

最后,您可以在帐号、广告系列或广告组级别附加附加信息。通过附加信息,您可以向广告提供额外的信息,例如电话号码、街道地址或促销信息。

资源

资源表示 Google Ads 帐号中的实体。 CampaignAdGroup 是两个资源示例。

对象 ID

Google Ads 中的每个对象都由自己的 ID 标识。其中一些 ID 在所有 Google Ads 帐号中具有全局唯一性,而其他 ID 仅在限定范围内是唯一的。

对象 ID 唯一性范围 全局唯一?
预算 ID 全局
广告系列 ID 全球
AdGroup ID 全球
广告 ID 广告组 否,但 (AdGroupId, AdId) 对是全局唯一的
AdGroupCriterion ID 广告组 否,但 (AdGroupId, CriterionId) 对是全局唯一的
CampaignCriterion ID Campaign 否,但 (CampaignId, CriterionId) 对是全局唯一的
广告附加信息 Campaign 否,但 (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 服务检索和修改 Google Ads 实体。有三种类型的服务:修改、对象和统计信息检索以及元数据检索服务。

修改 (mutate) 对象

这些服务使用 mutate 请求修改关联资源类型的实例。它们还提供 get 请求,用于检索单个资源实例,这对于检查资源结构非常有用。

服务示例:

每个 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 是统一的对象服务,用于检索对象和性能统计信息。

针对 GoogleAdsService 的所有 SearchSearchStream 请求都需要一个查询来指定要查询的资源、要检索的资源特性和性能指标、用于过滤请求的谓词,以及用于进一步细分性能统计信息的细分。如需详细了解查询格式,请参阅 Google Ads 查询语言指南

检索元数据

GoogleAdsFieldService 用于检索有关 Google Ads API 中资源的元数据,例如资源的可用属性及其数据类型。

此服务提供了构造 GoogleAdsService 查询所需的信息。为方便起见,字段参考文档中也提供了 GoogleAdsFieldService 返回的信息。