Updates Using 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 will be ignored, even if sent to the server.

FieldMasks

The recommended way to generate field masks is using our built-in field mask utility (FieldMasks), which hides a lot of the specific details and allows you to generate field masks automatically by monitoring the changes you make to the entity's fields.

Here's an example for updating a campaign:

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

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

First we create a Campaign object, by setting its resource name using ResourceNames utility, so that the API will know exactly which campaign it is we are updating.

Then, the code creates a CampaignOperation object and sets the previously created campaign to it. After that, we use FieldMasks::all_set_fields_of() to create a field mask for the campaign by using all changed fields. Then, we pass the returned mask to the campaign operation object.

Note that FieldMasks::all_set_fields_of() is a convenient method for FieldMasks::field_mask(). It compares your passed object to an empty object of the same class. For instance, in the above code, you can also use field_mask(Google::Ads::GoogleAds::V4::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 path field.

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