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
- 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
- A collection of
response_content_typefield indicating the preferred response type.
An operation object such as a
CampaignOperation lets you 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 our client libraries.
- 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. 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
What is returned in the response depends on what was sent in the
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.
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
GoogleAdsService, since it lets you retrieve only
specific attributes of objects, supports retrieving performance metrics, and
allows for streaming through large result sets. If your app submits a large
number of get requests, you may encounter rate limits.