字段掩码

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

FieldMasks 实用程序

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

下面是一个更新广告系列的示例：

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

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

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

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

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

field_mask(Google::Ads::GoogleAds::V19::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、cpc_bid_ceiling_micros 和 cpc_bid_floor_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::V19::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V19::Resources::MaximizeConversions->new()
    });

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

# Sends the operation in a mutate request that will result 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::V19::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    )
  });

# Creates a field mask from the existing campaign and adds all of the fields
# on the MaximizeConversions bidding strategy to the field mask. Because these
# fields are included in the field mask but excluded from the campaign object,
# the Google Ads API will set 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.
#
# Learn more about standard and portfolio bidding strategies here:
# https://developers.google.com/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::V19::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::V19::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V19::Resources::MaximizeConversions->new({
      targetCpaMicros => 0
    })
  });

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

请注意，只有清除每个子字段，才能清除包含嵌套子字段的字段，如包含已定义子字段的对象字段中所示。