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

Mutate 最佳做法

临时名称

GoogleAdsService.Mutate 支持使用临时名称,以便稍后在同一个请求中进行引用。这样,您就可以在一个请求中(例如)制作广告系列及其关联的广告组、广告、关键字等。

为此,您可以指定新资源的 resource_name 使用负 ID。例如,如果您制作了一个广告系列,并将其资源名称指定为 customers/[CID]/campaigns/-1,那么在以后的操作中创建广告组时,就可以通过该资源名称进行引用,而您指定的 -1 会被自动替换为已制作广告系列的实际 ID。

使用临时名称时,请注意以下事项:

  • 在使用资源前,必须先创建资源。在上例的操作列表中,广告组操作必须显示在广告系列操作之后。
  • 系统无法跨请求记住临时名称;所以,要引用在此前的请求中创建的资源,请使用真实的资源名称。
  • 一个请求中的临时名称个数没有限制。
  • 每个临时名称都必须使用具有唯一性的负数,即使它们来自不同的资源类型。
  • 针对多种资源类型发出单个 API 请求可以获得些许的性能提升,主要是因为节省了与多个请求有关的网络开销。

示例

为了针对上述情况给出更具体的例子,我们假设您希望在单个 API 请求中添加一个广告系列,并向该广告系列添加一个新的广告组。您可以为该请求创建一个类似如下内容的结构:

mutate_operations: [
  {
    campaign_operation: {
      create: {
        resource_name: "customers/[CID]/campaigns/-1",
        ...
      }
    }
  },
  {
    ad_group_operation: {
      create: {
        resource_name: "customers/[CID]/adGroups/-2",
        campaign: "customers/[CID]/campaigns/-1"
        ...
      }
    }
  }
]

请注意,广告组使用了新的临时 ID,这是因为我们无法重复利用广告系列已使用的 -1,而我们后期可能会在制作广告组广告时引用此广告组。广告组本身会引用资源名称,而该资源名称是我们为该请求的早期操作中的广告系列确定的。

组合相同类型的操作

在使用 GoogleAdsService.Mutate 时,请务必根据重复操作数组中的资源将操作组合在一起。作为一种方式,该 mutate 方法发挥的作用其实是自动依序调用每个资源的自有 mutate 方法。为此,它会在操作中进行读取,直到找到一项面向不同资源类型的操作,然后在一个请求中批处理所有相同类型的操作。

例如,如果您在 Mutate 调用的重复 operations 字段中有 5 项广告系列操作,后跟 10 项广告组操作,那么系统会在后端总共执行 2 次调用,一次调用 CampaignService 执行 5 项操作,另一次调用 AdGroupService 执行 10 项操作。不过,如果您采取其他的组合方式,则性能可能会差很多。比如,假设您只制作 2 个广告系列,并仅创建 2 个广告组,虽然数量都比前例少,但按 [广告系列, 广告组, 广告系列, 广告组] 的操作顺序进行排列后,会导致系统一共要在后端执行 4 次调用。这会导致 API 性能降低,在极端情况下甚至会导致超时。