Most resources are modified (created, updated, or removed) using a Mutate
method. The Mutate method is invoked as an HTTP POST to a resource-specific
URL that matches the resource-name pattern, without the trailing resource ID.
The IDs of the resources to be mutated are instead sent in the JSON request
body. This lets you send a single API call that contains multiple operations on
different resources.
For example, a campaign's resource name uses the following format:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
To derive the URL used for mutating campaigns, omit the trailing resource ID and
append :mutate:
https://googleads.googleapis.com/v18/customers/CUSTOMER_ID/campaigns:mutate
A Mutate message contains a top-level JSON object with an operations array
that can contain many operation objects. Each operation, in turn, can be one
of: create, update, or remove. These are the only possible mutate
operations.
POST /v18/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ ... ] }
Most services support thousands of operations in a single API call. The System Limits guide documents the limitations on request sizes.
Operations within a single API request are executed as one set of actions by
default, meaning they either all succeed together or the whole batch fails if
any single operation fails. Some services support a
partialFailure attribute
to change this behavior. See Mutating Resources
for more detailed information on mutate operation semantics.
Create
Create operations produce new entities and must include a full JSON representation of the resource you intend to create.
POST /v18/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "create": { "name": "An example campaign", "status": "PAUSED", "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/CAMPAIGN_BUDGET_ID", "advertisingChannelType": "SEARCH", "networkSettings": { "targetGoogleSearch": true, "targetSearchNetwork": true, "targetContentNetwork": true, "targetPartnerSearchNetwork": false }, "target_spend": {} } } ] }
Update
Update operations perform sparse updates to an existing resource. You only need to specify the fields you want to modify.
To specify the fields that you want to update, set the updateMask attribute to
a comma-separated list of field names. This is particularly useful if you
already have a fully formed JSON representation of an object (for instance, as
returned by a previous API call), but only want to change certain fields.
Instead of pruning the JSON object, you can just list the field names to be
modified in the updateMask and send the entire JSON object.
The example below changes the name and status of an existing campaign having
the given resourceName.
POST /v18/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "updateMask": "name,status", "update": { "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID", "name": "My renamed campaign", "status": "PAUSED", } } ] }
Remove
Remove operations effectively delete an object, setting its Google Ads status to
REMOVED. Only the resourceName to be removed is required.
POST /v18/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID" } ] }