使用字段掩码进行更新

在 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 库工厂方法：

campaign_resource_name = client.path.campaign(customer_id, campaign_id)

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

如果给定资源名称字符串，此方法会自动创建一个新 广告系列资源，并填充 resource_name，根据您在块中所做的更改构建字段掩码 ，构建更新操作，并 返回最终操作，其中已填充 update 和 update_mask。 您还可以传递现有的 Campaign proto 实例，而不是资源名称字符串，以指定广告系列的起始状态。此模式适用于所有支持更新操作的资源。

手动创建字段掩码

如需从头开始创建字段掩码而不使用库实用程序，请创建一个 Google::Protobuf::FieldMask，创建一个包含您打算更改的所有字段名称的数组，并将该数组分配给字段掩码的 paths 字段：

mask = Google::Protobuf::FieldMask.new
mask.paths = ['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 results 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]
)

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask starts empty. You can modify
# other fields in this block, except the message field intended to have a
# blank subfield.
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。

在 proto3 中，将非可选标量字段设置为其默认值 (0) 与在新消息实例中将其保留为未设置状态是无法区分的。因此， FieldMaskUtil 会将 maximize_conversions 添加到字段掩码，而不是 maximize_conversions.target_cpa_micros，这会导致 FieldMaskError.FIELD_HAS_SUBFIELDS 错误。

# 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 includes 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it results 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 fails because the field mask is invalid.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation]
)

# Create a campaign including the maximize conversions fields right away, since
# they are manually added 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 can add a block here with
# other changes that are automatically 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 succeeds because the correct field mask is specified.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation]
)

请注意，对于在 Google Ads API 协议缓冲区中定义 为 optional的字段，自动比较方法会按预期工作。由于 target_cpa_micros不是optional中的 MaximizeConversions字段，因此需要明确将路径附加到update_mask.paths才能清除它。