Nomi delle risorse temporanee
GoogleAdsService.Mutate supporta nomi di risorse temporanei a cui è possibile fare riferimento in un secondo momento nella stessa richiesta. Ciò ti consente, ad esempio, di creare una campagna e
i gruppi di annunci, gli annunci, le parole chiave e così via associati, il tutto in un'unica richiesta.
Puoi farlo specificando resource_name della nuova risorsa in modo da utilizzare un ID negativo. Ad esempio, se crei una campagna e specifichi come nome della risorsa customers/<YOUR_CUSTOMER_ID>/campaigns/-1, quando crei il gruppo di annunci in un'operazione successiva puoi farvi riferimento con il nome della risorsa specificato e il valore -1 specificato verrà sostituito automaticamente dall'ID effettivo della campagna creata.
Di seguito sono riportati alcuni aspetti da tenere presente quando utilizzi i nomi temporanei delle risorse:
- Un nome risorsa temporaneo può essere utilizzato solo dopo essere stato definito in una risorsa. Nell'esempio riportato di seguito, l'operazione relativa al gruppo di annunci dovrebbe apparire nell'elenco delle operazioni dopo l'operazione sulla campagna.
- I nomi delle risorse temporanee non vengono memorizzati nei job né nelle richieste di modifica. Per fare riferimento a una risorsa creata in un job precedente o in una richiesta di modifica, utilizza il nome effettivo della risorsa.
- Per un singolo job o una richiesta di modifica, ogni nome di risorsa temporanea deve utilizzare un numero negativo univoco, anche se provengono da tipi di risorse diversi. Se un ID temporaneo viene riutilizzato in un singolo job o in una richiesta di modifica, viene restituito un errore.
Esempio
Per fornire un esempio più concreto alla situazione sopra descritta, supponi di voler aggiungere una campagna, un gruppo di annunci e un annuncio in una singola richiesta API. Crei una struttura per la tua richiesta analoga alla seguente:
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"
...
}
}
},
]
Tieni presente che viene utilizzato un nuovo ID temporaneo per il gruppo di annunci, poiché non possiamo riutilizzare
il -1 che abbiamo utilizzato per la campagna. Inoltre, facciamo riferimento a questo gruppo di annunci quando
creiamo un annuncio del gruppo di annunci. Lo stesso gruppo di annunci fa riferimento al nome della risorsa che abbiamo
stabilito per la campagna in un'operazione precedente nella richiesta, mentre
resource_name in ad_group_ad_operation non è necessario perché non fa riferimento
al'altra operazione.
Operazioni dello stesso tipo di gruppo
Quando utilizzi GoogleAdsService.Mutate, è importante raggruppare le operazioni in base alla risorsa nell'array delle operazioni ripetute. Questo metodo di mutazione serve essenzialmente da modo per richiamare automaticamente in sequenza il metodo di modifica di ogni singola risorsa. Per farlo, legge le operazioni fino a quando non ne trova una per un tipo diverso di risorse, quindi raggruppa tutte le operazioni dello stesso tipo in un'unica richiesta.
Ad esempio, se hai 5 operazioni sulla campagna, seguite da 10 operazioni sul gruppo di annunci nel campo operations ripetuto nella chiamata Mutate, il sistema eseguirà due chiamate totali nel backend, una a CampaignService per 5 operazioni e l'altra a AdGroupService per 10 operazioni.
Tuttavia, raggruppandoli in modo diverso, il rendimento potrebbe essere molto
peggiore. Se crei solo due campagne e due gruppi di annunci, ma li intesse in modo che le operazioni siano ordinate come [campagna, gruppo di annunci, campagna, gruppo di annunci], si avranno quattro chiamate totali nel backend. Questo determina un rallentamento delle prestazioni
dell'API e, in casi estremi, può persino portare a timeout.
Recupera gli attributi mutabili dalla risposta
Se imposti response_content_type della richiesta di modifica su MUTABLE_RESOURCE, la risposta conterrà i valori di tutti i campi modificabili per ogni oggetto creato o aggiornato dalla richiesta. Utilizza questa funzionalità per evitare una richiesta search o searchStream aggiuntiva dopo ogni richiesta di modifica.
Se non imposti response_content_type, l'API Google Ads sarà impostata su RESOURCE_NAME_ONLY per impostazione predefinita e la risposta conterrà solo il nome della risorsa di ogni risorsa creata o aggiornata.
Ecco un esempio di recupero di una risorsa modificabile da una chiamata API:
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.V17.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];
}
Python
def create_experiment_arms(client, customer_id, base_campaign_id, experiment):
"""Creates a control and treatment experiment arms.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
base_campaign_id: the campaign ID to associate with the control arm of
the experiment.
experiment: the resource name for an experiment.
Returns:
the resource name for the new treatment experiment arm.
"""
operations = []
campaign_service = client.get_service("CampaignService")
# The "control" arm references an already-existing campaign.
operation_1 = client.get_type("ExperimentArmOperation")
exa_1 = operation_1.create
exa_1.control = True
exa_1.campaigns.append(
campaign_service.campaign_path(customer_id, base_campaign_id)
)
exa_1.experiment = experiment
exa_1.name = "control arm"
exa_1.traffic_split = 40
operations.append(operation_1)
# The non-"control" arm, also called a "treatment" arm, will automatically
# generate draft campaigns that you can modify before starting the
# experiment.
operation_2 = client.get_type("ExperimentArmOperation")
exa_2 = operation_2.create
exa_2.control = False
exa_2.experiment = experiment
exa_2.name = "experiment arm"
exa_2.traffic_split = 60
operations.append(operation_2)
experiment_arm_service = client.get_service("ExperimentArmService")
request = client.get_type("MutateExperimentArmsRequest")
request.customer_id = customer_id
request.operations = 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.
request.response_content_type = (
client.enums.ResponseContentTypeEnum.MUTABLE_RESOURCE
)
response = experiment_arm_service.mutate_experiment_arms(request=request)
# Results always return in the order that you specify them in the request.
# Since we created the treatment arm second, it will be the second result.
control_arm_result = response.results[0]
treatment_arm_result = response.results[1]
print(
f"Created control arm with resource name {control_arm_result.resource_name}"
)
print(
f"Created treatment arm with resource name {treatment_arm_result.resource_name}"
)
return treatment_arm_result.experiment_arm.in_design_campaigns[0]
Ruby
def create_experiment_arms(client, customer_id, base_campaign_id, experiment)
operations = []
operations << client.operation.create_resource.experiment_arm do |ea|
# The "control" arm references an already-existing campaign.
ea.control = true
ea.campaigns << client.path.campaign(customer_id, base_campaign_id)
ea.experiment = experiment
ea.name = 'control arm'
ea.traffic_split = 40
end
operations << client.operation.create_resource.experiment_arm do |ea|
# The non-"control" arm, also called a "treatment" arm, will automatically
# generate draft campaigns that you can modify before starting the
# experiment.
ea.control = false
ea.experiment = experiment
ea.name = 'experiment arm'
ea.traffic_split = 60
end
response = client.service.experiment_arm.mutate_experiment_arms(
customer_id: customer_id,
operations: 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.
response_content_type: :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.
control_arm_result = response.results.first
treatment_arm_result = response.results.last
puts "Created control arm with resource name #{control_arm_result.resource_name}."
puts "Created treatment arm with resource name #{treatment_arm_result.resource_name}."
treatment_arm_result.experiment_arm.in_design_campaigns.first
end
Perl
sub create_experiment_arms {
my ($api_client, $customer_id, $base_campaign_id, $experiment) = @_;
my $operations = [];
push @$operations,
Google::Ads::GoogleAds::V17::Services::ExperimentArmService::ExperimentArmOperation
->new({
create => Google::Ads::GoogleAds::V17::Resources::ExperimentArm->new({
# The "control" arm references an already-existing campaign.
control => "true",
campaigns => [
Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
$customer_id, $base_campaign_id
)
],
experiment => $experiment,
name => "control arm",
trafficSplit => 40
})});
push @$operations,
Google::Ads::GoogleAds::V17::Services::ExperimentArmService::ExperimentArmOperation
->new({
create => Google::Ads::GoogleAds::V17::Resources::ExperimentArm->new({
# 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 => $experiment,
name => "experiment arm",
trafficSplit => 60
})});
my $response = $api_client->ExperimentArmService()->mutate({
customerId => $customer_id,
operations => $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.
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.
my $control_arm_result = $response->{results}[0];
my $treatment_arm_result = $response->{results}[1];
printf "Created control arm with resource name '%s'.\n",
$control_arm_result->{resourceName};
printf "Created treatment arm with resource name '%s'.\n",
$treatment_arm_result->{resourceName};
return $treatment_arm_result->{experimentArm}{inDesignCampaigns}[0];
}