Field Masks

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), which lets you generate field masks from a modified object instead of building them from scratch.

Here's an example for updating a campaign:

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

my $campaign_operation =
  Google::Ads::GoogleAds::V18::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 utility, so that the API knows which campaign is being updated.

The example uses the FieldMasks::all_set_fields_of() 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(). It compares your passed object to an empty object of the same class. So in the code above, you could also use

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

instead of all_set_fields_of($campaign).

Manually creating a mask

To create a field mask from scratch, you would first create a Google::Ads::GoogleAds::Common::FieldMask 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"]
  });

Updating object fields and their subfields

Object fields can have subfields (such as MaximizeConversions which has three: target_cpa_micros, cpc_bid_ceiling_micros, and cpc_bid_floor_micros); or they can have none at all (such as 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 above.

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 example above 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 example below demonstrates how to update a campaign to use the 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 error.

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::V18::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V18::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V18::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::V18::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]
  });

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

Success: The code below successfully updates the campaign bidding strategy.

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

Clearing fields

Fields can be cleared explicitly by adding them to the field mask as shown above, 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.

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::V18::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V18::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V18::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::V18::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.