Temporäre Ressourcennamen
GoogleAdsService.Mutate unterstützt temporäre Ressourcennamen, auf die später in derselben Anfrage verwiesen werden kann. So können Sie beispielsweise eine Kampagne und die zugehörigen Anzeigengruppen, Anzeigen, Keywords usw. in einer einzigen Anfrage erstellen.
Geben Sie dazu in der resource_name der neuen Ressource eine negative ID an. Wenn Sie beispielsweise eine Kampagne erstellen und den Ressourcennamen customers/<YOUR_CUSTOMER_ID>/campaigns/-1 angeben, können Sie beim Erstellen der Anzeigengruppe in einem späteren Vorgang mit diesem Ressourcennamen darauf verweisen. Der von Ihnen angegebene -1 wird dann automatisch durch die tatsächliche ID der erstellten Kampagne ersetzt.
Beachten Sie bei der Verwendung temporärer Ressourcennamen Folgendes:
- Ein temporärer Ressourcenname kann erst verwendet werden, nachdem er in einer Ressource definiert wurde. Im folgenden Beispiel muss der Anzeigengruppenvorgang nach dem Kampagnenvorgang in der Liste der Vorgänge angezeigt werden.
- Namen temporärer Ressourcen werden nicht in verschiedenen Jobs oder mutate-Anfragen gespeichert. Um auf eine Ressource zu verweisen, die in einem vorherigen Job oder einer vorherigen mutate-Anfrage erstellt wurde, verwenden Sie ihren tatsächlichen Ressourcennamen.
- Für einen einzelnen Job oder eine einzelne mutate-Anfrage muss für jeden temporären Ressourcennamen eine eindeutige negative Zahl verwendet werden, auch wenn er zu unterschiedlichen Ressourcentypen gehört. Wird eine temporäre ID in einem einzelnen Job oder einer einzelnen mutate-Anfrage wiederverwendet, wird ein Fehler zurückgegeben.
Beispiel
Ein konkreteres Beispiel für die oben genannte Situation wäre, wenn Sie einer einzelnen API-Anfrage eine Kampagne, eine Anzeigengruppe und eine Anzeige hinzufügen möchten. In diesem Fall würden Sie eine Struktur für Ihre Anfrage erstellen, die so aussieht:
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"
...
}
}
},
]
Für die Anzeigengruppe wird eine neue temporäre ID verwendet, da wir das für die Kampagne verwendete -1 nicht wiederverwenden können und wir beim Erstellen einer Anzeigengruppenanzeige auf diese Anzeigengruppe verweisen. Die Anzeigengruppe selbst verweist auf den Ressourcennamen, den wir in einem früheren Vorgang für die Kampagne für die Kampagne festgelegt haben. resource_name in ad_group_ad_operation ist hingegen nicht erforderlich, da kein weiterer Vorgang darauf verweist.
Vorgänge des gleichen Typs gruppieren
Wenn Sie GoogleAdsService.Mutate verwenden, ist es wichtig, Vorgänge gemäß ihrer Ressource im Array für wiederkehrende Vorgänge zu gruppieren. Diese mutate-Methode dient im Wesentlichen dazu, die eigene mutate-Methode jeder einzelnen Ressource automatisch nacheinander aufzurufen. Dazu liest er Vorgänge ein, bis er eine für einen anderen Ressourcentyp findet, und fasst dann alle Vorgänge desselben Typs in einer Anfrage zusammen.
Beispiel: Bei 5 Kampagnenvorgängen gefolgt von 10 Anzeigengruppenvorgängen im wiederholten Feld operations des Mutate-Aufrufs führt das System insgesamt zwei Aufrufe im Back-End aus: einen für CampaignService für 5 Vorgänge und einen neben AdGroupService für 10 Vorgänge.
Wenn Sie sie jedoch unterschiedlich gruppieren, könnte sich die Leistung erheblich verschlechtern. Wenn Sie nur zwei Kampagnen und zwei Anzeigengruppen erstellen, diese aber so miteinander vermischen, dass die Vorgänge als [campaign, ad group, campaign, ad group] angeordnet werden, führt dies zu vier Aufrufen insgesamt im Backend. Dies beeinträchtigt die API-Leistung und kann in extremen Fällen sogar zu Zeitüberschreitungen führen.
Änderbare Attribute aus der Antwort abrufen
Wenn Sie das response_content_type Ihrer Änderungsanfrage auf MUTABLE_RESOURCE setzen, enthält die Antwort die Werte aller änderbaren Felder für jedes Objekt, das durch die Anfrage erstellt oder aktualisiert wird. Mit dieser Funktion können Sie nach jeder Änderungsanfrage eine zusätzliche search- oder searchStream-Anfrage vermeiden.
Wenn Sie response_content_type nicht festlegen, verwendet die Google Ads API standardmäßig RESOURCE_NAME_ONLY und die Antwort enthält nur den Ressourcennamen jeder erstellten oder aktualisierten Ressource.
Hier ist ein Beispiel für das Abrufen einer änderbaren Ressource aus einem API-Aufruf:
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];
}