一時リソース名
GoogleAdsService.Mutate は、後で同じリクエストで参照できる一時的なリソース名をサポートしています。これにより、たとえば、1 つのリクエストでキャンペーンを作成し、それに関連する広告グループ、広告、キーワードなどを作成できます。
これを行うには、負の ID を使用するように新しいリソースの resource_name を指定します。たとえば、キャンペーンを作成して、そのリソース名を customers/<YOUR_CUSTOMER_ID>/campaigns/-1 として指定した場合、後のオペレーションで広告グループを作成するときに、そのリソース名でそれを参照できます。指定した -1 は、作成されたキャンペーンの実際の ID で自動的に置き換えられます。
一時的なリソース名を使用する際は、次の点に注意してください。
- 一時リソース名は、リソース内で定義した名前でのみ使用できます。以下の例では、広告グループのオペレーションはオペレーションのリストでキャンペーン オペレーションの後に表示する必要があります。
- 一時リソース名は、ジョブ間や変更リクエスト間で記憶されません。前のジョブまたは変更リクエストで作成されたリソースを参照するには、実際のリソース名を使用します。
- 単一のジョブまたは変更リクエストでは、異なるリソースタイプの場合でも、各一時リソース名で一意の負の数値を使用する必要があります。一時 ID が単一のジョブまたは変更リクエストで再利用されると、エラーが返されます。
例
上記の状況について、より具体的な例を挙げると、1 つの API リクエストにキャンペーン、広告グループ、広告を追加するとします。次のようなリクエストの構造を作成します。
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"
...
}
}
},
]
広告グループには新しい仮 ID が使用されています。キャンペーンで使用した -1 は再利用できないためです。また、広告グループ広告の作成時にも、この広告グループを参照します。広告グループ自体は、リクエストの前のオペレーションでキャンペーン用に設定したリソース名を参照しますが、それ以上のオペレーションでは参照されないため、ad_group_ad_operation の resource_name は必要ありません。
同じタイプのオペレーションをグループ化する
GoogleAdsService.Mutate を使用する場合は、繰り返しオペレーションの配列で、リソースに応じてオペレーションをグループ化することが重要です。この mutate メソッドは基本的には、個々のリソース固有の mutate メソッドを自動的に順番に呼び出す方法として機能します。そのために、異なるタイプのリソースに対応するオペレーションが見つかるまでオペレーションを読み取り、その後、同じタイプのオペレーションをすべて 1 つのリクエストにまとめます。
たとえば、5 つのキャンペーン オペレーションがあり、その後に Mutate 呼び出しの繰り返し operations フィールドに 10 件の広告グループ オペレーションが続く場合、バックエンドで合計 2 回の呼び出しが実行されます。1 つは CampaignService への 5 つのオペレーション、もう 1 つは AdGroupService の 10 オペレーションの呼び出しです。ただし、異なる方法でグループ化すると、パフォーマンスが大幅に低下する可能性があります。2 つのキャンペーンと 2 つの広告グループのみを作成し、オペレーションを「キャンペーン、広告グループ、キャンペーン、広告グループ」の順に並べると、バックエンドで合計 4 回の呼び出しが発生します。これにより、API のパフォーマンスが低下し、極端な場合はタイムアウトにつながることさえあります。
レスポンスから変更可能な属性を取得する
変換リクエストの response_content_type を MUTABLE_RESOURCE に設定すると、そのリクエストによって作成または更新されたすべてのオブジェクトのすべての可変フィールドの値がレスポンスに含まれます。この機能を使用すると、変更リクエストの後に search リクエストや searchStream リクエストを追加する必要がなくなります。
response_content_type を設定しない場合、Google Ads API はデフォルトで RESOURCE_NAME_ONLY に設定され、レスポンスには作成または更新された各リソースのリソース名のみが含まれます。
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.V16.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::V16::Services::ExperimentArmService::ExperimentArmOperation
->new({
create => Google::Ads::GoogleAds::V16::Resources::ExperimentArm->new({
# The "control" arm references an already-existing campaign.
control => "true",
campaigns => [
Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
$customer_id, $base_campaign_id
)
],
experiment => $experiment,
name => "control arm",
trafficSplit => 40
})});
push @$operations,
Google::Ads::GoogleAds::V16::Services::ExperimentArmService::ExperimentArmOperation
->new({
create => Google::Ads::GoogleAds::V16::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];
}