Google Ads API is returning to beta status. Please read our blog post for more details.

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.

FieldMaskUtil

The recommended way to generate field masks is using our built-in field mask utility, which allows you to generate field masks from a modified object, instead of building them from scratch.

Here's an example for updating a campaign:

// Update campaign by setting its status to paused, and "Search network" to false.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
    NetworkSettings = new NetworkSettings()
    {
        TargetSearchNetwork = false
    }
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

// Update the campaign.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

First, we create an empty Campaign object. Then, we set its resource name so that the API will know exactly which campaign we are updating.

The example uses the FieldMasks.AllSetFieldsOf method on the campaign automatically produce a field mask enumerating all the set fields. You can then pass the returned mask directly to the update call.

Sometimes, you may need to work with an existing object, and update a few fields. In such cases, you'd modify the code as follows:

Campaign existingCampaign;

// Obtain existingCampaign from elsewhere.
...

// Create a new campaign based off the existing campaign for update.
Campaign campaignToUpdate = new Campaign(existingCampaign);

// Update campaign by setting its status to paused, and "Search network" to
// false.
campaignToUpdate.Status = CampaignStatus.Paused;
campaignToUpdate.NetworkSettings = new NetworkSettings()
{
    TargetSearchNetwork = false
}

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.FromChanges(existingCampaign, campaignToUpdate)
};

To create a field mask from scratch, you would first create a FieldMask object, then make an array populated with the names of all the fields you intend to change, and finally append the array contents to the field mask's Path field.

FieldMask fieldMask = new FieldMask();
fieldMask.Paths.AddRange(new string[] { "status", "name" });