Temporary resource names
GoogleAdsService.Mutate
supports
temporary resource names that can be referenced later
on in the same request. This lets you, 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, suppose you create a campaign and specify its resource name
as customers/<YOUR_CUSTOMER_ID>/campaigns/-1
. When you create the
ad group in a later operation, you can then 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 resource names:
- A temporary resource name can only be used after it's been defined in a resource. In the following example, the ad group operation would have to appear after the campaign operation in the list of operations.
- Temporary resource names are not remembered across jobs or mutate requests. To reference a resource created in a previous job or mutate request, use its actual resource name.
- For a single job or mutate request, each temporary resource name must use a unique negative number, even if they are from different resource types. If a temporary ID is reused in a single job or mutate request, then an error is returned.
Example
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"
...
}
}
},
]
A new temporary ID is used for the ad group, since we can't reuse the -1
that
we used for the campaign. 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.
Retrieve mutable attributes from the response
If you set the response_content_type
of your mutate request to MUTABLE_RESOURCE
,
the response will contain the values of all mutable
fields for every object
created or updated by the request. Use this feature to avoid an additional search
or searchStream
request after each mutate request.
If you do not set the response_content_type
, then the Google Ads API defaults to RESOURCE_NAME_ONLY
and the response will only contain the resource name of
each created or updated resource.
Here's an example of retrieving a mutable resource from an API call:
Java
private String createExperimentArms ( GoogleAdsClient googleAdsClient , long customerId , long campaignId , String experiment ) { List<ExperimentArmOperation> operations = new ArrayList <> (); operations . add ( ExperimentArmOperation . newBuilder () . setCreate ( // The "control" arm references an already-existing campaign. ExperimentArm . newBuilder () . setControl ( true ) . addCampaigns ( ResourceNames . campaign ( customerId , campaignId )) . setExperiment ( experiment ) . setName ( "control arm" ) . setTrafficSplit ( 40 ) . build ()) . build ()); operations . add ( ExperimentArmOperation . newBuilder () . setCreate ( // The non-"control" arm, also called a "treatment" arm, will automatically // generate draft campaigns that you can modify before starting the experiment. ExperimentArm . newBuilder () . setControl ( false ) . setExperiment ( experiment ) . setName ( "experiment arm" ) . setTrafficSplit ( 60 ) . build ()) . build ()); try ( ExperimentArmServiceClient experimentArmServiceClient = googleAdsClient . getLatestVersion (). createExperimentArmServiceClient ()) { // Constructs the mutate request. MutateExperimentArmsRequest mutateRequest = MutateExperimentArmsRequest . newBuilder () . setCustomerId ( Long . toString ( customerId )) . addAllOperations ( operations ) // We want to fetch the draft campaign IDs from the treatment arm, so the easiest way to do // that is to have the response return the newly created entities. . setResponseContentType ( ResponseContentType . MUTABLE_RESOURCE ) . build (); // Sends the mutate request. MutateExperimentArmsResponse response = experimentArmServiceClient . mutateExperimentArms ( mutateRequest ); // Results always return in the order that you specify them in the request. Since we created // the treatment arm last, it will be the last result. If you don't remember which arm is the // treatment arm, you can always filter the query in the next section with // `experiment_arm.control = false`. MutateExperimentArmResult controlArmResult = response . getResults ( 0 ); MutateExperimentArmResult treatmentArmResult = response . getResults ( response . getResultsCount () - 1 ); System . out . printf ( "Created control arm with resource name '%s'%n" , controlArmResult . getResourceName ()); System . out . printf ( "Created treatment arm with resource name '%s'%n" , treatmentArmResult . getResourceName ()); return treatmentArmResult . getExperimentArm (). getInDesignCampaigns ( 0 ); } }
C#
/// <summary> /// Creates the experiment arms. /// </summary> /// <param name="client">The Google Ads client.</param> /// <param name="customerId">The customer ID for which the call is made.</param> /// <param name="baseCampaignId">ID of the campaign for which the control arm is /// created.</param> /// <param name="experimentResourceName">Resource name of the experiment.</param> /// <returns>The control and treatment arms.</returns> private static ( MutateExperimentArmResult , MutateExperimentArmResult ) CreateExperimentArms ( GoogleAdsClient client , long customerId , long baseCampaignId , string experimentResourceName ) { // Get the ExperimentArmService. ExperimentArmServiceClient experimentService = client . GetService ( Services . V21 . ExperimentArmService ); // Create the control arm. The control arm references an already-existing campaign. ExperimentArmOperation controlArmOperation = new ExperimentArmOperation () { Create = new ExperimentArm () { Control = true , Campaigns = { ResourceNames . Campaign ( customerId , baseCampaignId ) }, Experiment = experimentResourceName , Name = "Control Arm" , TrafficSplit = 40 } }; // Create the non-control arm. The non-"control" arm, also called a "treatment" arm, // will automatically generate draft campaigns that you can modify before starting the // experiment. ExperimentArmOperation treatmentArmOperation = new ExperimentArmOperation () { Create = new ExperimentArm () { Control = false , Experiment = experimentResourceName , Name = "Experiment Arm" , TrafficSplit = 60 } }; // We want to fetch the draft campaign IDs from the treatment arm, so the // easiest way to do that is to have the response return the newly created // entities. MutateExperimentArmsRequest request = new MutateExperimentArmsRequest { CustomerId = customerId . ToString (), Operations = { controlArmOperation , treatmentArmOperation }, ResponseContentType = ResponseContentType . MutableResource }; MutateExperimentArmsResponse response = experimentService . MutateExperimentArms ( request ); // Results always return in the order that you specify them in the request. // Since we created the treatment arm last, it will be the last result. MutateExperimentArmResult controlArm = response . Results . First (); MutateExperimentArmResult treatmentArm = response . Results . Last (); Console . WriteLine ( $"Created control arm with resource name " + $"'{controlArm.ResourceName}." ); Console . WriteLine ( $"Created treatment arm with resource name" + $" '{treatmentArm.ResourceName}'." ); return ( controlArm , treatmentArm ); }
PHP
private static function createExperimentArms( GoogleAdsClient $googleAdsClient, int $customerId, int $campaignId, string $experimentResourceName ): string { $operations = []; $experimentArm1 = new ExperimentArm([ // The "control" arm references an already-existing campaign. 'control' => true, 'campaigns' => [ResourceNames::forCampaign($customerId, $campaignId)], 'experiment' => $experimentResourceName, 'name' => 'control arm', 'traffic_split' => 40 ]); $operations[] = new ExperimentArmOperation(['create' => $experimentArm1]); $experimentArm2 = new ExperimentArm([ // The non-"control" arm, also called a "treatment" arm, will automatically // generate draft campaigns that you can modify before starting the // experiment. 'control' => false, 'experiment' => $experimentResourceName, 'name' => 'experiment arm', 'traffic_split' => 60 ]); $operations[] = new ExperimentArmOperation(['create' => $experimentArm2]); // Issues a request to create the experiment arms. $experimentArmServiceClient = $googleAdsClient->getExperimentArmServiceClient(); $response = $experimentArmServiceClient->mutateExperimentArms( MutateExperimentArmsRequest::build($customerId, $operations) // We want to fetch the draft campaign IDs from the treatment arm, so the easiest // way to do that is to have the response return the newly created entities. ->setResponseContentType(ResponseContentType::MUTABLE_RESOURCE) ); // Results always return in the order that you specify them in the request. // Since we created the treatment arm last, it will be the last result. $controlArmResourceName = $response->getResults()[0]->getResourceName(); $treatmentArm = $response->getResults()[count($operations) - 1]; print "Created control arm with resource name '$controlArmResourceName'" . PHP_EOL; print "Created treatment arm with resource name '{$treatmentArm->getResourceName()}'" . PHP_EOL; return $treatmentArm->getExperimentArm()->getInDesignCampaigns()[0]; }
