Change Objects

Page Summary

outlined_flag

• Google Ads API resources can be modified using resource-type-specific services that have a mutate method.

• The mutate method accepts a request including a customerId, a collection of operations, and a response_content_type setting.

• An operation object specifies the action (create, update, or remove) for a single resource.

• Multiple operations can be combined into a single mutate request for efficiency.

• Mutate operations are all applied only if every operation in the request succeeds.

As discussed in the API structure guide, each top-level resource in the Google Ads API has a corresponding resource-type-specific service that supports modifying instances of the resource.

This guide will use CampaignService to demonstrate modifying Campaign objects, but the same concepts apply to all other resource-type-specific services.

Change objects

Each resource-type-specific service will have a mutate method that accepts a mutate request. This request consists of:

• A customerId
• A collection of operations
• A response content-type setting that determines whether the mutable resource or just the resource name should be returned post mutation.

For example, the MutateCampaigns method of CampaignService accepts a MutateCampaignsRequest that consists of:

• A customerId
• A collection of CampaignOperation objects
• The response_content_type field indicating the preferred response type.

Operations

An operation object such as a CampaignOperation lets you specify the action that you want to perform on a single resource by setting its operation field. This field is a oneof field consisting of the following attributes whose type is the resource type:

create

Creates a new instance of the resource.

update

Updates the resource to match the attributes of the update

resource. When this field is set, you must also set the update_mask of the operation, which tells the Google Ads API which attributes to modify during the update operation. Each client library has a utility or helper method that will generate the update_mask for you, as demonstrated in our client libraries.

remove

Removes the resource.

Since the operation field is a oneof field, you cannot use a single operation to modify multiple objects. For example, if you want to create one campaign and remove another campaign, add two instances of CampaignOperation to your request: one with create set, and another with remove set.

Batch operations

Although a single operation can only either create, update, or remove a single resource, a single mutate request can contain multiple operations. You should combine your operations into a single mutate request instead of sending multiple mutate requests that each contain a single operation.

For example, if you want to create ten campaigns, you should send a single MutateCampaignsRequest that has ten CampaignOperation objects.

Mutate responses

What is returned in the response depends on what was sent in the response_content_type of the mutate request. For example, if MUTABLE_RESOURCE was specified, then the response would contain just the mutable fields in the campaign. You can then make follow-up mutates on that resource object without having to reconstruct it.

Mutate errors

The operations in a given mutate request will only be applied to your Google Ads account if every operation in the request succeeds. Check out the common errors guide for a list of common errors and how to address them.

Track changes

To track changes made to objects in your Google Ads account, or to retrieve the current state of objects, you can use the change_status and change_event resources.

• change_status provides a summary of which resources have changed within a given time period.
• change_event provides a detailed history of the changes, including the old and new values of the changed fields.

To query these resources, use the GoogleAdsService.SearchStream or GoogleAdsService.Search method. Read more about Report streaming using GoogleAdsService.