臨時資源名稱
GoogleAdsService.Mutate 支援臨時資源名稱，可在同一項要求中稍後參照。舉例來說，您可以建立廣告活動及相關的廣告群組、廣告、關鍵字等，只需要一個要求就能完成。
方法是指定新資源的 resource_name 使用負 ID。舉例來說，如果您建立一個廣告活動，並將其資源名稱指定為 customers/<YOUR_CUSTOMER_ID>/campaigns/-1，則在後續作業中建立廣告群組時，您可以使用該資源名稱來參照它，而您指定的 -1 會自動替換成所建立廣告活動的實際 ID。
使用臨時資源名稱時，請注意下列事項：
- 您必須在資源中定義臨時資源名稱，才能使用。在以下範例中，廣告群組作業必須在作業清單中的廣告活動作業完成後顯示。
- 系統不會記住所有工作或變更要求中的臨時資源名稱；如要參照在先前工作或修改要求中建立的資源，請使用實際資源名稱。
- 如果是單一工作或 change 請求，每個臨時資源名稱都必須使用唯一的負數，即使它們來自不同的資源類型也一樣。如果在單一工作或變更要求中重複使用臨時 ID，系統會傳回錯誤。
範例
為了讓有關上述情況的具體範例，假設您想在單一 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 時，請務必根據重複運算陣列中的資源將作業分組。這個 change 方法主要是自動依序呼叫各資源各自的 change 方法。做法是在作業中讀取作業，直到找到不同類型的資源適用的作業為止，然後將所有相同的類型作業批次處理到單一要求中。
舉例來說，如果您有 5 項廣告活動作業，並在 Mutate 呼叫的重複 operations 欄位中進行 10 項廣告群組作業，則系統會在後端執行總共兩次呼叫，一個是 CampaignService 的 5 項作業，接下來則是 10 項作業位於 AdGroupService 旁。不過，如果以不同方式分組，效能可能會大幅降低。如果您只建立 2 個廣告活動和 2 個廣告群組，但將它們分類為 [campaign、ad group、campaign、ad group]，這樣後端就會產生四次呼叫。這會導致 API 效能變慢，在極端的情況下甚至可能導致逾時。
從回應中擷取可變動的屬性
如果將 change 要求的 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];
}