Changing and Inspecting Objects

Objective: Understand how to modify and inspect objects using the Google Ads API.

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
• Retrieving a single instance of the resource for inspection

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

Key Term: A top-level resource is a resource whose name does not include a period (.). For example, Campaign is a top-level resource, but Campaign.NetworkSettings is not.

Changing 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.

Batching 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.