Google Ads API is returning to beta status. Please read our blog post for more details.

更改和检查对象

正如 API 结构指南中所述,Google Ads API 中的每个顶级资源都有相应的特定于资源类型的服务,且该服务支持以下操作:

  • 修改资源实例。
  • 检索单个资源实例供检查使用。

本指南将使用 CampaignService 演示如何修改和检查 Campaign 对象,不过这些概念同样适用于所有其他特定于资源类型的服务。

更改对象

每个特定于资源类型的服务都有一个 mutate 方法,可接受 mutate 请求。此请求包括:

  • 一个 customerId
  • 操作的集合。

例如,CampaignServiceMutateCampaigns 方法接受包含以下内容的 MutateCampaignsRequest

  • 一个 customerId
  • CampaignOperation 对象的集合。

操作

CampaignOperation 等操作对象支持您指定自己希望在单个资源上执行的操作,具体方法是设置其 operation 字段。此字段是 oneof 字段,由以下类型为资源类型的属性组成:

create
创建新的资源实例。
update
更新资源以匹配 update 资源的属性。设置此字段后,您还必须设置相关操作的 update_mask,让 Google Ads API 了解应在更新操作期间修改哪些属性。每个客户端库都有一个实用程序或帮助程序方法,可为您生成 update_mask,一如我们的客户端库中所示。
remove
移除资源。

由于 operation 字段为 oneof 字段,您无法使用单个操作来修改多个对象。例如,如果要制作一个广告系列并移除另一个广告系列,那么应在您的请求中添加两个 CampaignOperation 实例,并将其中一个设置为 create,另一个设置为 remove

批处理操作

虽然一个操作只能创建、更新或移除一个资源,但是一个 mutate 请求中可包含多个操作。如果可能,您应尽量将多个操作组合到一个 mutate 请求中,而不是发送多个 mutate 请求,让其中每个请求只包含一个操作。

例如,如果您想制作 10 个广告系列,则应该发送一个 MutateCampaignsRequest 请求,让其中包含 10 个 CampaignOperation 对象。

Mutate 响应

成功的响应(如 MutateCampaignsResponse)会返回已创建、更新或移除的每个对象的资源名称,但不返回对象本身。如果需要对应的对象,您可以使用资源名称中的标识符构建一个查询,以便通过 GoogleAdsService 检索该对象。

Mutate 错误

只有当给定 mutate 请求中的每个操作都获得成功时,该请求中的操作才会应用于您的 Google Ads 帐号。有关常见错误列表及其解决方法,请查看常见错误指南

检查对象

除了更改对象之外,每个特定于资源类型的服务还拥有 get 方法,可用于检索单个资源的所有属性。此方法接受只有一个 resource_name 属性的 get 请求。

get 方法是 Google Ads API 提供的一种方便措施,可让您轻松检索单个对象的所有属性。虽然这是一个绝佳的工具,可用于学习 API 或出于调试或培训目的而检查单个对象,但是您的应用不应为了进行处理或报告而使用 get 方法检索对象。此时,应改为使用 GoogleAdsService,因为它可让您只检索对象的特定属性,支持检索效果指标,并且允许对较大的结果集进行分页。如果您的应用提交了大量的 get 请求,那么您可能会遇到速率限制问题。