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. You could create a field mask manually, by creating a Google\Protobuf\FieldMask, making an array populated with the names of all the fields you intend to change, and then assigning that to the field mask's path field.

If you prefer, you could use 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:

    $campaign = new Campaign([
        'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
        'status' => CampaignStatus::PAUSED
    ]);

    $campaignOperation = new CampaignOperation();
    $campaignOperation->setUpdate($campaign);
    $campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

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

Then, the code creates a CampaignOperation object and set the previously created campaign to it. After that, we use FieldMasks::allSetFieldsOf() 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::allSetFieldsOf is a convenient method for FieldMasks::compare(). It compares your passed object to an empty object of the same class. For instance, in the above code, you can also use FieldMasks::compare(new Campaign(), $campaign) instead of allSetFieldsOf().