使用字段掩码进行更新

在 Google Ads API 中,更新是使用字段掩码完成的。字段掩码会列出您打算在更新后更改的所有字段,并且字段掩码中未包含的任何指定字段都将被忽略,即使发送到服务器也是如此。

FieldMaskUtil

建议使用我们的内置字段掩码实用程序生成字段掩码,该实用程序隐藏许多特定详细信息,并允许您通过监控对实体字段所做的更改来自动生成字段掩码。

若要生成用于更新广告系列的字段掩码,请按以下步骤操作:

campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)

mask = client.field_mask.with campaign do
  campaign.status = :PAUSED
  campaign.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

该代码会先创建一个空的 Campaign 对象,然后设置其资源名称以通知 API 即将更新广告系列。

此示例对广告系列使用 client.field_mask.with 方法,以开始包含更新的代码块。在此块的末尾,该实用程序会将该块之后的广告系列的当前状态与该块之前的广告系列的初始状态进行比较,并自动生成一个字段掩码,以枚举已更改的字段。在为 mutate 调用构建操作时,您可以为操作提供该字段掩码,如下所示:

operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask

如果您要进行复杂的操作并希望对每个步骤进行精细控制,建议您使用此方法。不过,在大多数情况下,您可以使用更简单的 Ruby 库实用程序:

operation = client.operation.update_resource.campaign do |c|
  c.status = :PAUSED
  c.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

此方法会自动创建一个新的空广告系列资源,根据您在该块中所做的更改来构建字段掩码,构建更新操作,并返回已填充 updateupdate_mask 的最终操作。您还可以将广告系列传递给 campaign 方法,以指定广告系列的开始状态。此模式适用于所有支持更新操作的资源。

手动创建遮罩

如需从头开始创建字段掩码(不使用任何库实用程序),您首先要创建一个 Google::Protobuf::FieldMask,然后创建一个数组,在其中填充要更改的所有字段的名称,最后将该数组分配给字段掩码的 path 字段。

mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]

更新消息字段及其子字段

MESSAGE 字段可以有子字段(例如 MaximizeConversions,它有三个:target_cpa_microscpc_bid_ceiling_microscpc_bid_floor_micros),也可以根本没有子字段(例如 ManualCpm)。

未定义子字段的消息字段

更新未使用任何子字段定义的 MESSAGE 字段时,请使用 FieldMaskUtil 生成字段掩码,如前所述。

包含已定义子字段的消息字段

更新使用子字段定义的 MESSAGE 字段时,如果未为该消息明确设置任何子字段,则必须手动将每个可变的 MESSAGE 子字段添加到 FieldMask,这与前面从头开始创建字段掩码的示例类似。

一个常见的示例是,在没有为新出价策略设置任何字段的情况下更新广告系列的出价策略。以下示例演示了如何将广告系列更新为使用 MaximizeConversions 出价策略,而无需在出价策略中设置任何子字段。

对于此示例,使用 FieldMaskUtil 的内置比较无法实现预期目标。

以下代码会生成包含 maximize_conversions 的字段掩码。但是,为防止意外清除字段并产生 FieldMaskError.FIELD_HAS_SUBFIELDS 错误,Google Ads API 不允许这种行为。

# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# Update the maximize conversions field within the update block, so it's
# captured in the field mask
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions
end

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
# be included in a field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

以下代码演示了如何正确更新广告系列,以使用 MaximizeConversions 出价策略,而无需设置广告系列的任何子字段。

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}

# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << "maximize_conversions.target_cpa_micros"

# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

正在清除字段

某些字段可以明确清除。与上一个示例类似,您必须将这些字段明确添加到字段掩码中。例如,假设您有一个使用 MaximizeConversions 出价策略的广告系列,并且 target_cpa_micros 字段的值设置为大于 0 的值。

运行以下代码;不过,由于系统不会将 maximize_conversions.target_cpa_micros 添加到字段掩码中,因此也未对 target_cpa_micros 字段进行任何更改:

# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# The field mask in this operation will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Operation will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

以下代码演示了如何正确清除 MaximizeConversions 出价策略的 target_cpa_micros 字段。

# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them to the field mask.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Create the operation with an empty field mask. You may add a block here with
# other changes that will automatically get added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}

# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'

# Operation will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

请注意,“错误”代码确实适用于在 Google Ads API protocol buffers 中定义为 optional 的字段。但是,由于 target_cpa_micros 不是 optional 字段,因此“错误”代码不会更新出价策略以清除 target_cpa 字段。