正如 API 结构指南中所述,Google Ads API 中的每个顶级资源都有相应的特定于资源类型的服务,且该服务支持以下操作:
- 修改资源的实例
- 检索资源的单个实例以进行检查
本指南将使用 CampaignService
来演示如何修改和检查 Campaign
对象,但这些概念同样适用于所有其他特定于资源类型的服务。
更改对象
每个特定于资源类型的服务都有一个 mutate 方法,可接受 mutate 请求。mutate此请求包括:
customerId
- 操作的集合
- 响应内容类型设置,用于确定应在更改后返回可变资源还是仅返回资源名称。
例如,CampaignService
的 MutateCampaigns
方法接受包含以下内容的 MutateCampaignsRequest
:
customerId
CampaignOperation
对象的集合response_content_type
字段,用于指示首选响应类型。
运维
借助 CampaignOperation
等操作对象,您可以通过设置其 operation
字段来指定要对单个资源执行的操作。此字段是 oneof 字段,由以下类型为资源类型的属性组成:
create
- 创建资源的新实例。
update
- 更新资源以匹配
update
资源的特性。设置此字段后,您还必须设置操作的update_mask
,以告知 Google Ads API 在更新操作期间修改哪些属性。每个客户端库都有一个实用程序或辅助方法,可为您生成update_mask
,如我们的客户端库所示。 remove
- 移除资源。
由于 operation
字段是 oneof
字段,因此您无法使用单个操作来修改多个对象。例如,如果您要制作一个广告系列并移除另一个广告系列,请在请求中添加两个 CampaignOperation
实例:一个设置了 create
,另一个设置了 remove
。
批处理操作
虽然一个操作只能创建、更新或移除一个资源,但是一个 mutate 请求中可包含多个操作。您应将各项操作合并为一个 mutate 请求,而不是发送多个 mutate 请求,让每个请求包含一项操作。
例如,如果您要制作 10 个广告系列,则应发送包含 10 个 CampaignOperation
对象的一个 MutateCampaignsRequest
。
Mutate 响应
响应中返回的内容取决于 mutate 请求的 response_content_type
中发送的内容。例如,如果指定了 MUTABLE_RESOURCE
,则响应将只包含广告系列中的可变字段。然后,您可以在该资源对象上进行后续 mutate 操作,而无需重新构造。
Mutate 错误
只有当给定 mutate 请求中的每个操作都获得成功时,该请求中的操作才会应用于您的 Google Ads 账号。有关常见错误列表及解决方法,请查看常见错误指南。
使用 get 检查对象(已弃用)
除了更改对象之外,每个特定于资源类型的服务还有一个 get 方法,可用于检索单个资源的所有属性。此方法接受唯一属性为 resource_name
的 get 请求。
get 方法是 Google Ads API 提供的一种便捷方法,可让您轻松检索单个对象的所有属性。虽然这是学习 API 或出于调试或指导目的检查单个对象的绝佳工具,但您的应用不应使用 get 方法来检索对象,以便进行处理或报告。建议改用 GoogleAdsService
,因为它可让您仅检索对象的特定属性,支持检索性能指标,并且支持流式传输大型结果集。如果您的应用提交大量 get 请求,则可能会遇到速率限制。