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