Tên tài nguyên tạm thời
Hỗ trợ GoogleAdsService.Mutate
tên tài nguyên tạm thời có thể được tham chiếu sau
trong cùng một yêu cầu. Điều này cho phép bạn, ví dụ: tạo chiến dịch và
các nhóm quảng cáo, quảng cáo, từ khoá được liên kết, v.v.
tất cả trong một yêu cầu duy nhất.
Bạn có thể thực hiện việc này bằng cách chỉ định resource_name của tài nguyên mới để sử dụng
mã nhận dạng phủ định. Ví dụ: nếu bạn tạo một chiến dịch và chỉ định tên tài nguyên của chiến dịch
dưới dạng customers/<YOUR_CUSTOMER_ID>/campaigns/-1, thì khi bạn tạo
nhóm quảng cáo trong thao tác sau này, bạn có thể tham chiếu nhóm quảng cáo theo tên tài nguyên đó và
-1 mà bạn đã chỉ định sẽ được thay thế bằng mã thực tế của chiến dịch đã tạo
tự động.
Sau đây là một số điều cần lưu ý khi sử dụng tên tài nguyên tạm thời:
- Chỉ có thể sử dụng tên tài nguyên tạm thời sau khi tên đó được xác định trong nguồn. Trong ví dụ bên dưới, hoạt động của nhóm quảng cáo sẽ phải xuất hiện sau hoạt động của chiến dịch trong danh sách hoạt động.
- Tên tài nguyên tạm thời không được ghi nhớ trong các công việc hoặc các yêu cầu thay đổi; để tham chiếu một tài nguyên được tạo trong một công việc trước đó hoặc yêu cầu thay đổi, hãy sử dụng tên tài nguyên thực tế.
- Đối với một yêu cầu công việc hoặc yêu cầu thay đổi, mỗi tên tài nguyên tạm thời phải sử dụng số âm duy nhất, ngay cả khi chúng từ các loại tài nguyên khác nhau. Nếu một mã nhận dạng tạm thời được sử dụng lại trong một yêu cầu công việc hoặc yêu cầu thay đổi, sau đó xảy ra lỗi bị trả về.
Ví dụ:
Để có ví dụ cụ thể hơn cho trường hợp nêu trên, giả sử bạn muốn thêm chiến dịch, nhóm quảng cáo và quảng cáo trong một yêu cầu API duy nhất. Bạn sẽ tạo một cấu trúc cho yêu cầu của bạn tương tự như sau:
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"
...
}
}
},
]
Xin lưu ý rằng mã nhận dạng tạm thời mới được sử dụng cho nhóm quảng cáo, vì chúng tôi không thể sử dụng lại
-1 mà chúng tôi đã sử dụng cho chiến dịch, đồng thời chúng tôi cũng tham chiếu đến nhóm quảng cáo này khi
tạo một nhóm quảng cáo. Bản thân nhóm quảng cáo đó tham chiếu đến tên tài nguyên mà chúng tôi
được thiết lập cho chiến dịch trong thao tác trước đó trong yêu cầu, trong khi
Không cần resource_name trong ad_group_ad_operation vì không có gì khác
tham chiếu đến nó.
Nhóm các thao tác cùng loại
Khi sử dụng GoogleAdsService.Mutate,
điều quan trọng là phải nhóm
các hoạt động
cùng với nhau theo tài nguyên trong mảng hoạt động lặp lại. Chiến dịch này
về cơ bản, phương thức mutate là một cách để tự động gọi tuần tự
phương thức thay đổi riêng của mỗi tài nguyên. Để thực hiện việc này, mã sẽ đọc trong các toán tử
cho đến khi tìm thấy một tài nguyên cho loại tài nguyên khác, sau đó nhóm tất cả
thao tác cùng loại với nhau trong một yêu cầu.
Ví dụ: nếu bạn có 5 hoạt động chiến dịch, tiếp theo là 10 nhóm quảng cáo
trong trường operations lặp lại trong lệnh gọi Mutate, thì
hệ thống sẽ thực hiện tổng cộng hai lệnh gọi trong phần phụ trợ, một lệnh gọi đến
CampaignService
cho 5 hoạt động và hoạt động bên cạnh AdGroupService
cho 10 phép toán.
Tuy nhiên, nếu bạn nhóm chúng theo cách khác, hiệu suất có thể sẽ
tệ hơn. Nếu bạn chỉ tạo 2 chiến dịch và 2 nhóm quảng cáo, nhưng hãy kết hợp chúng để
các hoạt động được sắp xếp là [chiến dịch, nhóm quảng cáo, chiến dịch, nhóm quảng cáo], thì
sẽ dẫn đến tổng cộng 4 lệnh gọi trong phần phụ trợ. Điều này sẽ khiến API chậm hơn
và trong các trường hợp nghiêm trọng thậm chí có thể dẫn đến hết thời gian chờ.
Truy xuất các thuộc tính có thể thay đổi qua phản hồi
Nếu bạn đặt response_content_type của yêu cầu thay đổi thành
MUTABLE_RESOURCE,
phản hồi sẽ chứa giá trị của tất cả các trường có thể biến đổi cho mọi đối tượng
được tạo hoặc cập nhật theo yêu cầu. Hãy sử dụng tính năng này để tránh
Yêu cầu search hoặc searchStream sau mỗi yêu cầu thay đổi.
Nếu bạn không đặt response_content_type, thì API Google Ads mặc định sẽ
RESOURCE_NAME_ONLY và phản hồi sẽ chỉ chứa tên tài nguyên của
từng tài nguyên được tạo hoặc cập nhật.
Sau đây là ví dụ về cách truy xuất một tài nguyên có thể thay đổi qua lệnh gọi 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];
}