Page Summary
-
Field masks in the Google Ads API specify which fields to update in an API request, ignoring any fields not listed.
-
The recommended way to generate field masks is using the
FieldMaskUtilclass, specificallyFieldMasks.AllSetFieldsOffor new objects andFieldMasks.FromChangesfor existing objects. -
To clear a field, you must manually include it in the field mask without setting the field value in the object, as setting it to a default value won't clear it.
In the Google Ads API, a field mask is used to provide a list of fields that an API request should update. Any field that is not specified in the field mask will be ignored, even if sent to the server.
FieldMaskUtil class
The recommended way to generate field masks is to use the built-in FieldMaskUtil
class, which lets you generate field masks from a modified
object instead of building them from scratch.
Here's an example for updating a campaign, that uses the FieldMasks.AllSetFieldsOf
method to produce a field mask that enumerates all
the set fields. You can then pass the generated field mask directly to the
update call.
// 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
});
Sometimes, you may need to work with an existing object, and update a few
fields. In such cases, you'd modify the code to use the FieldMasks.FromChanges
method instead. This method generates a field mask that represents the
difference between two objects.
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
)
};
How to handle FieldMaskError.FIELD_HAS_SUBFIELDS
errors
On rare occasions, you may need to set a field without updating any of the sub-fields of that type. Consider the following example:
// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign
campaign
=
new
Campaign
()
{
ResourceName
=
ResourceNames
.
Campaign
(
customerId
,
campaignId
),
MaximizeConversions
=
new
MaximizeConversions
()
};
CampaignOperation
operation
=
new
CampaignOperation
()
{
Update
=
campaign
,
UpdateMask
=
FieldMasks
.
AllSetFieldsOf
(
campaign
)
};
MutateCampaignsResponse
response
=
campaignService
.
MutateCampaigns
(
customerId
.
ToString
(),
new
CampaignOperation
[]
{
operation
});
This API call will fail with an FieldMaskError.FIELD_HAS_SUBFIELDS
error.
Since MaximizeConversions
has three
sub-fields, the Google Ads API server expects field masks for those fields to be
present in the request. However, FieldMaskUtil
cannot generate field masks
correctly in this situation, since the request is not setting these fields.
In such cases, you can manually edit the field mask as follows:
// Creates a Campaign object with the proper resource name.
Campaign
campaign
=
new
Campaign
()
{
ResourceName
=
ResourceNames
.
Campaign
(
customerId
,
campaignId
),
};
FieldMask
fieldMask
=
FieldMasks
.
AllSetFieldsOf
(
campaign
);
// 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
fieldMask
.
Paths
.
AddRange
(
new
string
[]
{
"maximize_conversions.target_cpa_micros"
,
});
// Creates an operation to update the campaign with the specified fields.
CampaignOperation
operation
=
new
CampaignOperation
()
{
Update
=
campaign
,
UpdateMask
=
fieldMask
};
How to clear fields
Google Ads API supports clearing some field values. To clear a field, you must manually set the field mask for that field. Setting a field to its default value (such as zero for an int64 field) won't clear the field.
The following code example shows how to clear the target_cpa_micros
field of MaximizeConversions
bidding strategy.
Correct code
The following code clears the target_cpa_micros
field because we are
setting the maximize_conversions.target_cpa_micros
in the field mask and
not setting the campaign.MaximizeConversions.TargetCpaMicros
field.
// Creates a Campaign object with the proper resource name.
Campaign
campaign
=
new
Campaign
()
{
ResourceName
=
ResourceNames
.
Campaign
(
customerId
,
campaignId
),
};
// Constructs a field mask from the existing campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which will
// clear this field from the bidding strategy without impacting any other fields
// on the bidding strategy.
FieldMask
fieldMask
=
FieldMasks
.
AllSetFieldsOf
(
campaign
);
fieldMask
.
Paths
.
AddRange
(
new
string
[]
{
"maximize_conversions.target_cpa_micros"
,
});
// Creates an operation to update the campaign with the specified field.
CampaignOperation
operation
=
new
CampaignOperation
()
{
Update
=
campaign
,
UpdateMask
=
fieldMask
};
Incorrect code
The following code doesn't clearthe target_cpa_micros
field, since we
are setting this field to zero. Both the FieldMaskUtils
and the Google Ads API
server will ignore this value. In addition, you may also not receive an
error in this case, since the value was ignored by the server.
// Creates a campaign with the proper resource name and a MaximizeConversions
// object. Attempt to clear the target_cpa_micros field by setting it to 0.
Campaign
campaign
=
new
Campaign
()
{
ResourceName
=
ResourceNames
.
Campaign
(
customerId
,
campaignId
),
MaximizeConversions
=
new
MaximizeConversions
()
{
TargetCpaMicros
=
0
}
};
// Constructs an operation, using the FieldMasks' AllSetFieldsOf utility to
// derive the update mask. However, the field mask will NOT include
// 'maximize_conversions.target_cpa_micros'.
CampaignOperation
operation
=
new
CampaignOperation
()
{
Update
=
campaign
,
UpdateMask
=
FieldMasks
.
AllSetFieldsOf
(
campaign
)
};
// Sends the operation in a mutate request that will succeed but will NOT update
// the 'target_cpa_micros' field because 'maximize_conversions.target_cpa_micros'
// was not included in the field mask.
MutateCampaignsResponse
response
=
campaignService
.
MutateCampaigns
(
customerId
.
ToString
(),
new
CampaignOperation
[]
{
operation
});
