本指南介绍了 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
Service
通过服务,您可以检索和修改 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
返回的信息。