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.
Each resource-type-specific service will have a mutate method that accepts a mutate request. This request consists of:
- A collection of operations.
For example, the
MutateCampaigns method of
CampaignService accepts a
MutateCampaignsRequest that consists of:
- A collection of
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
field. This field is a oneof field
consisting of the following attributes whose type is the resource type:
- Creates a new instance of the resource.
- Updates the resource to match the attributes of the
updateresource. When this field is set, you must also set the
update_maskof 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_maskfor you, as demonstrated in the code examples.
- Removes the resource.
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
to your request: one with
create set, and another with
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
MutateCampaignsRequest that has ten
A successful response such as a
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
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.
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
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
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
- Continue to the next guide in this series: Retrieving Objects.