字段掩码

在 Google Ads API 中，更新是通过字段掩码完成的。字段掩码会列出您打算通过更新更改的所有字段，并且系统会忽略字段掩码中未包含的任何指定字段，即使这些字段已发送到服务器也是如此。

FieldMasks 实用程序

生成字段掩码的推荐方法是使用我们的内置字段掩码实用程序 (FieldMasks)，该实用程序可让您从修改后的对象生成字段掩码，而无需从头构建。

以下是更新广告系列的示例：

use Google::Ads::GoogleAds::Utils::FieldMasks qw(all_set_fields_of field_mask);

my $campaign =
  Google::Ads::GoogleAds::V25::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    status => "PAUSED",
    networkSettings =>
      Google::Ads::GoogleAds::V25::Resources::NetworkSettings
      ->new({
        targetSearchNetwork => "false",
      }),
  });

my $campaign_operation =
  Google::Ads::GoogleAds::V25::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign),
  });

此示例首先使用 ResourceNames 实用程序设置资源名称，从而创建一个 Campaign 对象，以便 API 知道要更新哪个广告系列。

该示例使用广告系列中的 FieldMasks::all_set_fields_of() 方法自动生成一个枚举所有已设置字段的字段掩码。然后，您可以将返回的掩码直接传递给更新调用。

FieldMasks::all_set_fields_of() 是 FieldMasks::field_mask() 的便捷方法。它会将您传递的对象与同一类的空对象进行比较。在上述代码中，您还可以使用：

field_mask(
  Google::Ads::GoogleAds::V25::Resources::Campaign->new({}),
  $campaign
)

而非 all_set_fields_of($campaign)。

手动创建遮罩

如需从头开始创建字段掩码，请先创建一个 Google::Ads::GoogleAds::Common::FieldMask 对象，然后创建一个填充了您打算更改的所有字段名称的数组引用，最后将该数组引用分配给字段掩码的 paths 字段：

my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
  paths => ["status", "name"],
});

更新对象字段及其子字段

对象字段可以包含子字段（例如 MaximizeConversions，其中包含 target_cpa_micros 等子字段），也可以不包含任何子字段（例如 ManualCpm）。

未定义子字段的对象字段

Perl 中的对象字段相当于在基于 gRPC 运行的客户端库中的 protobuf MESSAGE。更新未定义任何子字段的对象字段时，请使用 FieldMasks 实用程序生成字段掩码，如上一部分中所述。

具有已定义子字段的对象字段

更新定义了子字段的对象字段时，如果未在该消息中明确设置任何子字段，您必须手动将每个可变对象子字段添加到 FieldMask，这与之前从头开始创建字段掩码的示例类似。

一个常见的示例是更新广告系列的出价策略，而不设置新出价策略上的任何字段。以下示例展示了如何更新广告系列以使用 MaximizeConversions 出价策略，而不设置出价策略的任何子字段。

在这种情况下，使用 FieldMasks 实用程序的 all_set_fields_of() 和 field_mask() 方法无法实现预期目标。

以下示例会生成一个包含 maximize_conversions 的字段掩码。不过，Google Ads API 不允许这种行为，以防止意外清除字段，并会产生 FieldMaskError.FIELD_HAS_SUBFIELDS 错误。

# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign =
  Google::Ads::GoogleAds::V25::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V25::Resources::MaximizeConversions
      ->new(),
  });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask includes 'maximize_conversions',
# which produces a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
  Google::Ads::GoogleAds::V25::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign),
  });

# Sends the operation in a mutate request that results in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty object fields cannot
# be included in a field mask.
my $response = $api_client->CampaignService()->mutate({
  customerId => $customer_id,
  operations => [$campaign_operation],
});

以下示例演示了如何正确更新广告系列以使用 MaximizeConversions 出价策略，而不设置其任何子字段。

# Creates a campaign with the proper resource name.
my $campaign =
  Google::Ads::GoogleAds::V25::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
  });

# Creates a field mask from the existing campaign and adds the mutable subfield
# on the MaximizeConversions bidding strategy to the field mask. Because this
# field is included in the field mask but excluded from the campaign object,
# the Google Ads API sets the campaign's bidding strategy to a
# MaximizeConversions object with none of its subfields set.
# Only include 'maximize_conversions.target_cpa_micros' in the field mask
# as it is the only mutable subfield on MaximizeConversions when used as a
# standard bidding strategy.
#
# See the guide on assigning standard and portfolio bidding strategies
# (/google-ads/api/docs/campaigns/bidding/assign-strategies).
my $field_mask = all_set_fields_of($campaign);
push @{$field_mask->{paths}}, "maximize_conversions.target_cpa_micros";

# Creates an operation to update the campaign with the specified fields.
my $campaign_operation =
  Google::Ads::GoogleAds::V25::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => $field_mask,
  });

清除字段

可以通过将字段添加到字段掩码中（如上例所示）或将字段设置为空值或未定义的值来明确清除字段。例如，假设您有一个广告系列采用的是 MaximizeConversions 出价策略，并且 target_cpa_micros 字段设置的值大于 0。

# Creates a campaign with the proper resource name and a MaximizeConversions
# object with target_cpa_micros set to 0.
my $campaign =
  Google::Ads::GoogleAds::V25::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V25::Resources::MaximizeConversions
      ->new({
        targetCpaMicros => 0,
      }),
  });

# Constructs an operation using all_set_fields_of to derive the update mask,
# which includes 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
  Google::Ads::GoogleAds::V25::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign),
  });

请注意，具有嵌套子字段的字段只能通过清除每个单独的子字段来清除，如具有已定义子字段的对象字段中所述。