Tên tài nguyên tạm thời
GoogleAdsService.Mutate hỗ trợ 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. Ví dụ: bạn có thể tạo một chiến dịch và các nhóm quảng cáo, quảng cáo, từ khoá, v.v. liên kết với chiến dịch đó 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 âm. Ví dụ: nếu tạo một chiến dịch và chỉ định tên tài nguyên là customers/<YOUR_CUSTOMER_ID>/campaigns/-1, thì khi tạo nhóm quảng cáo trong một 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 bạn chỉ định sẽ tự động được thay thế bằng mã nhận dạng thực tế của chiến dịch đã tạo.
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:
- Bạn 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 tài nguyên. Trong ví dụ bên dưới, thao tác nhóm quảng cáo phải xuất hiện sau thao tác chiến dịch trong danh sách thao tác.
- Tên tài nguyên tạm thời không được ghi nhớ trên các công việc hoặc yêu cầu thay đổi; để tham chiếu đến một tài nguyên được tạo trong một công việc hoặc yêu cầu thay đổi trước đó, hãy sử dụng tên tài nguyên thực tế của tài nguyên đó.
- Đối với một 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 một số âm duy nhất, ngay cả khi chúng thuộc 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 công việc hoặc yêu cầu thay đổi, thì lỗi sẽ được trả về.
Ví dụ:
Để đưa ra ví dụ cụ thể hơn về trường hợp nêu trên, giả sử bạn muốn thêm một chiến dịch, một nhóm quảng cáo và một quảng cáo trong một yêu cầu API. Bạn sẽ tạo một cấu trúc cho yêu cầu 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"
...
}
}
},
]
Lưu ý rằng một mã tạm thời mới được dùng cho nhóm quảng cáo, vì chúng ta không thể sử dụng lại -1 mà chúng ta đã dùng cho chiến dịch. Chúng ta cũng tham chiếu nhóm quảng cáo này khi tạo quảng cáo 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 ta đã thiết lập cho chiến dịch trong một thao tác trước đó trong yêu cầu, trong khi resource_name trong ad_group_ad_operation là không cần thiết vì không có thao tác nào khác tham chiếu đến tên này.
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 toán tử lại với nhau theo tài nguyên của chúng trong mảng toán tử lặp lại. Về cơ bản, phương thức biến đổi này đóng vai trò là một cách để tự động gọi tuần tự phương thức biến đổi của từng tài nguyên riêng lẻ. Để thực hiện việc này, trình đọc sẽ đọc các thao tác cho đến khi tìm thấy một thao tác cho một loại tài nguyên khác, sau đó gộp tất cả cá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 thao tác chiến dịch, theo sau là 10 thao tác 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 2 lệnh gọi trong phần phụ trợ, một lệnh gọi đến CampaignService cho 5 thao tác và lệnh gọi tiếp theo đến AdGroupService cho 10 thao tác.
Tuy nhiên, nếu bạn nhóm các thành phần này theo cách khác, hiệu suất có thể kém hơn rất nhiều. Nếu bạn chỉ tạo 2 chiến dịch và 2 nhóm quảng cáo, nhưng đan xen các chiến dịch và nhóm quảng cáo đó để các thao tác được sắp xếp theo thứ tự [chiến dịch, nhóm quảng cáo, chiến dịch, nhóm quảng cáo], thì tổng cộng sẽ có 4 lệnh gọi trong phần phụ trợ. Điều này sẽ làm giảm hiệu suất của API và trong 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 từ 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 các giá trị của tất cả các trường có thể thay đổi cho mọi đối tượng do yêu cầu tạo hoặc cập nhật. Hãy sử dụng tính năng này để tránh yêu cầu search hoặc searchStream bổ sung sau mỗi yêu cầu thay đổi.
Nếu bạn không đặt response_content_type, thì API Google Ads sẽ mặc định là 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 đã tạo hoặc cập nhật.
Dưới đây là ví dụ về cách truy xuất tài nguyên có thể thay đổi từ lệnh gọi API:
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); } }
/// <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.V19.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); }
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]; }
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]
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
sub create_experiment_arms { my ($api_client, $customer_id, $base_campaign_id, $experiment) = @_; my $operations = []; push @$operations, Google::Ads::GoogleAds::V19::Services::ExperimentArmService::ExperimentArmOperation ->new({ create => Google::Ads::GoogleAds::V19::Resources::ExperimentArm->new({ # The "control" arm references an already-existing campaign. control => "true", campaigns => [ Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign( $customer_id, $base_campaign_id ) ], experiment => $experiment, name => "control arm", trafficSplit => 40 })}); push @$operations, Google::Ads::GoogleAds::V19::Services::ExperimentArmService::ExperimentArmOperation ->new({ create => Google::Ads::GoogleAds::V19::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]; }