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.

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

• A customerId.
• A collection of CampaignOperation objects.

Operations

An operation object such as a CampaignOperation allows you to 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. Where possible, 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

A successful response such as a MutateCampaignsResponse will return the resource name of each created, updated, or removed object, but not the objects themselves. If you need the corresponding objects, you can use the identifiers in the resource names to build a query to retrieve the objects through GoogleAdsService.

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.

Inspecting objects

In addition to changing objects, each resource type-specific service also has a get method for retrieving all attributes of a single resource. This method accepts a get request whose only attribute is resource_name.

Key Point: Use get sparingly.

The get methods are a convenience offered by the Google Ads API to make it easy to retrieve all attributes of a single object. Although this is a great tool for learning the API or inspecting an individual object for debugging or education purposes, your app should not use get methods to retrieve objects for processing or reporting. Instead, use GoogleAdsService, since it allows you to retrieve only specific attributes of objects, supports retrieving performance metrics, and allows for paging through large result sets. If your app submits a large number of get requests, you may encounter rate limits.