Temporary names
GoogleAdsService.Mutate supports temporary names that can be referenced later
on in the same request. This allows you to, for example, create a campaign and
its associated ad groups, ads, keywords, etc. all in a single request.
You can do this by specifying the new resource's resource_name to use a
negative ID. For example, if you create a campaign and specify its resource name
as customers/<YOUR_CUSTOMER_ID>/campaigns/-1, then when you are creating the
ad group in a later operation, you can reference it by that resource name and
the -1 you specified will be replaced by the actual ID of the created campaign
automatically.
Here are some things to keep in mind when using temporary names:
- A temporary name can only be used after it's been defined in a resource. In the example below, the ad group operation would have to appear after the campaign operation in the list of operations.
- Temporary names are not remembered across jobs; to reference a resource created in a previous job, use its actual resource name.
- Each temporary name must use a unique negative number, even if they are from different resource types.
Example
To give a more concrete example to the situation mentioned above, suppose you want to add a campaign, an ad group, and an ad in a single API request. You would create a structure for your request analogous to the following:
mutate_operations: [
{
campaign_operation: {
create: {
resource_name: "customers/<YOUR_CUSTOMER_ID>/campaigns/-1",
...
}
}
},
{
ad_group_operation: {
create: {
resource_name: "customers/<YOUR_CUSTOMER_ID>/adGroups/-2",
campaign: "customers/<YOUR_CUSTOMER_ID>/campaigns/-1"
...
}
}
},
{
ad_group_ad_operation: {
create: {
ad_group: "customers/<YOUR_CUSTOMER_ID>/adGroups/-2"
...
}
}
},
]
Notice that a new temporary ID is used for the ad group, since we can't reuse
the -1 that we used for the campaign, and we also reference this ad group when
creating an ad group ad. The ad group itself references the resource name we
established for the campaign in an earlier operation in the request, while
resource_name in ad_group_ad_operation is not necessary since no further
operation is referencing it.
Group same-type operations
When using GoogleAdsService.Mutate, it is important to group operations
together according to their resource in the repeated operations array. This
mutate method essentially serves as a way to automatically sequentially call
each individual resource's own mutate method. To do this, it reads in operations
until it finds one for a different type of resources, then batches all the
same-type operations together in one request.
For example, if you have 5 campaign operations, followed by 10 ad group
operations in the repeated operations field in your Mutate call, then the
system will perform two total calls in the backend, one to the CampaignService
for 5 operations, and the next to the AdGroupService for 10 operations.
However, if you were to group them differently, performance could be a lot
worse. If you only create 2 campaigns and 2 ad groups, but weave them so the
operations are ordered as [campaign, ad group, campaign, ad group], then this
will result in four total calls in the backend. This will result in slower API
performance and in extreme cases can even lead to timeouts.
Need help? Visit our