In the Google Ads API, updates are done using a field mask. The field mask lists
all the fields you intend to change with the update, and any specified fields
that are not in the field mask are ignored, even if sent to the server.

## FieldMasks utility

The recommended way to generate field masks is using our built-in field mask
utility ([`FieldMasks`](https://github.com/googleads/google-ads-perl/blob/HEAD/lib/Google/Ads/GoogleAds/Utils/FieldMasks.pm)), which lets you generate field masks
from a modified object instead of building them from scratch.

Here's an example for updating a campaign:

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

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

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

This example first creates a `Campaign` object by setting its resource name
using the [`ResourceNames`](https://developers.google.com/google-ads/api/docs/client-libs/perl/resource-names) utility, so that the API knows
which campaign is being updated.

The example uses the [`FieldMasks::all_set_fields_of()`](https://github.com/googleads/google-ads-perl/blob/HEAD/lib/Google/Ads/GoogleAds/Utils/FieldMasks.pm#L46)
method on the campaign to automatically produce a field mask that enumerates all
set fields. You can then pass the returned mask directly to the update call.

`FieldMasks::all_set_fields_of()` is a convenience method for
[`FieldMasks::field_mask()`](https://github.com/googleads/google-ads-perl/blob/HEAD/lib/Google/Ads/GoogleAds/Utils/FieldMasks.pm#L37). It compares your passed object to
an empty object of the same class. In the preceding code, you could also use:

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

instead of `all_set_fields_of($campaign)`.

## Manually create a mask

To create a field mask from scratch, you first create a
[`Google::Ads::GoogleAds::Common::FieldMask`](https://github.com/googleads/google-ads-perl/blob/HEAD/lib/Google/Ads/GoogleAds/Common/FieldMask.pm) object, then
make an array reference populated with the names of all the fields you intend to
change, and finally assign the array reference to the field mask's `paths`
field:

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

## Update object fields and their subfields

Object fields can have subfields (such as
[`MaximizeConversions`](https://developers.google.com/google-ads/api/reference/rpc/v26/MaximizeConversions), which includes subfields such as
`target_cpa_micros`), or they can have none at all (such as
[`ManualCpm`](https://developers.google.com/google-ads/api/reference/rpc/v26/ManualCpm)).

### Object fields with no defined subfields

An object field in Perl is equivalent to a protobuf `MESSAGE` in client
libraries running on gRPC. When updating an object field that isn't defined
with any subfields, use the `FieldMasks` utility to generate a field mask, as
described in the preceding section.

### Object fields with defined subfields

When updating an object field that is defined with subfields without explicitly
setting any of the subfields on that message, you must manually add each of the
**mutable** object subfields to the `FieldMask`, similar to the earlier example
that creates a field mask from scratch.

One common example is updating a campaign's bidding strategy without setting any
of the fields on the new bidding strategy. The following example demonstrates
how to update a campaign to use the
[`MaximizeConversions`](https://developers.google.com/google-ads/api/reference/rpc/v26/MaximizeConversions) bidding strategy without setting
any of the subfields on the bidding strategy.

In this case, using the `all_set_fields_of()` and `field_mask()` methods of the
`FieldMasks` utility does not achieve the intended goal.

The following example generates a field mask that includes
`maximize_conversions`. However, the Google Ads API doesn't allow for this behavior to
prevent accidentally clearing fields, and produces a
[`FieldMaskError.FIELD_HAS_SUBFIELDS`](https://developers.google.com/google-ads/api/reference/rpc/v26/FieldMaskErrorEnum.FieldMaskError#field_has_subfields) error.

> [!WARNING]
> **Warning:** The following code produces an error.

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

The following example demonstrates how to properly update a campaign to use the
`MaximizeConversions` bidding strategy without setting any of its subfields.

> [!TIP]
> **Success:** The following code successfully updates the campaign bidding strategy.

    # Creates a campaign with the proper resource name.
    my $campaign =
      Google::Ads::GoogleAds::V26::Resources::Campaign->new({
        resourceName =>
          Google::Ads::GoogleAds::V26::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::V26::Services::CampaignService::CampaignOperation
      ->new({
        update     => $campaign,
        updateMask => $field_mask,
      });

## Clear fields

Fields can be cleared explicitly by adding them to the field mask as shown in
the preceding example, or by setting the field to an empty or undefined value.
For example, assume you have a campaign that uses a `MaximizeConversions`
bidding strategy and that the `target_cpa_micros` field is set with a value that
is greater than `0`.

> [!TIP]
> **Success:** The following code clears the `target_cpa_micros` field.

    # Creates a campaign with the proper resource name and a MaximizeConversions
    # object with target_cpa_micros set to 0.
    my $campaign =
      Google::Ads::GoogleAds::V26::Resources::Campaign->new({
        resourceName =>
          Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
            $customer_id, $campaign_id
          ),
        maximizeConversions =>
          Google::Ads::GoogleAds::V26::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::V26::Services::CampaignService::CampaignOperation
      ->new({
        update     => $campaign,
        updateMask => all_set_fields_of($campaign),
      });

Note that fields with nested subfields can only be cleared by clearing each of
the individual subfields, as demonstrated in [Object fields with defined
subfields](https://developers.google.com/google-ads/api/docs/client-libs/perl/field-masks#object-fields).