使用字段掩码进行更新

在 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 方法开始 包含更新的块。在这个代码块的末尾， 将屏蔽后的广告系列的当前状态与最初的 广告系列的状态，系统会自动生成一个字段， 枚举已更改字段的掩码。您可以在为更改调用构建操作时向该操作提供该字段掩码，如下所示：

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

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

手动创建遮罩

要从头开始创建字段掩码，而不使用任何库实用程序， 需要先创建一个 Google::Protobuf::FieldMask，然后创建一个数组 其中填充了您想要更改的所有字段的名称 将该数组分配到字段掩码的 path 字段。

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

更新消息字段及其子字段

MESSAGE 字段可以包含子字段（例如 MaximizeConversions，其中包含三个： target_cpa_micros、cpc_bid_ceiling_micros 和 cpc_bid_floor_micros），或 也可以完全没有参数（例如 ManualCpm）。

没有已定义子字段的消息字段

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

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

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

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

在此示例中，使用 FieldMaskUtil 的内置比较项不会 实现预期目标。

以下代码会生成包含 maximize_conversions 的字段掩码。 不过，为防止滥用，Google Ads API 不允许 意外清除了字段 FieldMaskError.FIELD_HAS_SUBFIELDS 错误。

# 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 字段。