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. You can also use GoogleAdsService.Mutate to mutate multiple resource types atomically in a single request.

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

Mutate requests

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

• A customer_id (or customerId in REST URLs)
• A collection of operations
• Optional execution settings such as partial_failure, validate_only, and response_content_type (which determines whether the mutable resource or only the resource name is returned after mutation)

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

• A customer_id
• A collection of CampaignOperation objects (operations)
• Optional execution settings (partial_failure, validate_only, and response_content_type 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:

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 includes a field mask utility or helper method that generates the update_mask for you.

remove

Removes the resource specified by its resource name string (for example, customers/1234567890/campaigns/987654321).

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. To group operations across different resource types into a single request, use GoogleAdsService.Mutate or mutating resources.

Mutate responses

What is returned in the response depends on what was sent in the response_content_type field of the mutate request. For example, if MUTABLE_RESOURCE is specified, then the response contains both the resource's resource_name and the mutable fields of the campaign in campaign. By default (RESOURCE_NAME_ONLY), only the resource_name is populated in each MutateCampaignResult.

Mutate errors

By default (partial_failure = false), the operations in a mutate request are applied to your Google Ads account only if every operation in the request succeeds; if any operation fails, the entire request is rolled back. For mutate requests that support partial failure (those with a partial_failure field on the request message), setting partial_failure = true commits valid operations while failed operations return operation-specific errors in the response's partial_failure_error field. See the partial failure guide and the common errors guide for details on handling errors.

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.