Nama resource sementara
GoogleAdsService.Mutate
didukung
nama resource sementara yang dapat direferensikan nanti
dalam permintaan yang sama. Ini memungkinkan Anda, misalnya, membuat kampanye dan
grup iklan, iklan, kata kunci, dll. yang terkait, semuanya dalam satu permintaan.
Anda dapat melakukannya dengan menentukan resource_name
resource baru untuk menggunakan
ID negatif. Misalnya, jika Anda membuat kampanye dan menentukan nama resource-nya
sebagai customers/<YOUR_CUSTOMER_ID>/campaigns/-1
, maka saat Anda membuat
grup iklan dalam operasi berikutnya, Anda dapat mereferensikannya melalui nama sumber daya dan
-1
yang Anda tentukan akan diganti dengan ID sebenarnya dari kampanye yang dibuat
secara otomatis.
Berikut adalah beberapa hal yang perlu diingat saat menggunakan nama resource sementara:
- Nama resource sementara hanya dapat digunakan setelah didefinisikan dalam resource Anda Pada contoh di bawah, operasi grup iklan harus muncul setelah operasi kampanye dalam daftar operasi.
- Nama resource sementara tidak diingat di seluruh tugas atau permintaan mutasi; untuk mereferensikan resource yang dibuat dalam tugas sebelumnya atau bermutasi, gunakan nama resource yang sebenarnya.
- Untuk satu tugas atau permintaan mutasi, setiap nama resource sementara harus menggunakan angka negatif unik, meskipun berasal dari jenis resource yang berbeda. Jika ID sementara digunakan kembali dalam satu tugas atau bermutasi permintaan, maka error akan dikembalikan.
Contoh
Untuk memberikan contoh yang lebih konkret untuk situasi yang disebutkan di atas, misalkan Anda ingin menambahkan kampanye, grup iklan, dan iklan dalam satu permintaan API. Anda akan membuat struktur untuk permintaan Anda yang serupa dengan berikut ini:
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"
...
}
}
},
]
Perhatikan bahwa ID sementara yang baru digunakan untuk grup iklan, karena kita tidak dapat menggunakannya kembali
-1
yang digunakan untuk kampanye, dan kami juga mereferensikan grup iklan ini saat
membuat iklan grup iklan. Grup iklan itu sendiri merujuk ke
nama sumber daya yang kita
ditetapkan untuk kampanye dalam operasi sebelumnya dalam permintaan, sedangkan
resource_name
di ad_group_ad_operation
tidak diperlukan karena tidak diperlukan
sebenarnya yang mereferensikannya.
Mengelompokkan operasi yang berjenis sama
Saat menggunakan GoogleAdsService.Mutate
,
penting untuk melakukan
operasi grup
sesuai dengan sumber dayanya dalam himpunan operasi berulang. Ini
pada dasarnya berfungsi sebagai cara
untuk secara otomatis memanggil
setiap metode mutate masing-masing resource. Untuk melakukan ini, DHCP membaca dalam operasi
sampai menemukan satu untuk jenis sumber
daya yang berbeda, lalu mengelompokkan semua
operasi berjenis sama secara bersamaan
dalam satu permintaan.
Misalnya, jika Anda memiliki 5 operasi kampanye, diikuti dengan 10 grup iklan
operasi di kolom operations
berulang dalam panggilan Mutate
Anda, kemudian
sistem akan melakukan total dua panggilan di backend, satu ke
CampaignService
untuk 5 operasi, dan di samping AdGroupService
untuk 10 operasi.
Namun, jika Anda mengelompokkannya secara berbeda, kinerja bisa jauh lebih
lebih buruk. Jika Anda hanya membuat 2 kampanye dan 2 grup iklan, tetapi menggabungkannya
operasi diurutkan sebagai [kampanye, grup iklan, kampanye, grup iklan], maka
akan menghasilkan total empat panggilan di backend. Hal ini akan menyebabkan API menjadi lebih lambat
performa dan dalam kasus ekstrem, bahkan dapat menyebabkan waktu tunggu habis.
Mengambil atribut yang dapat diubah dari respons
Jika Anda menetapkan response_content_type
permintaan mutasi ke
MUTABLE_RESOURCE
,
respons akan berisi nilai semua kolom yang dapat diubah untuk setiap objek
yang dibuat atau diperbarui
oleh permintaan. Gunakan fitur ini untuk menghindari
Permintaan search
atau searchStream
setelah setiap permintaan mutasi.
Jika Anda tidak menetapkan response_content_type
, Google Ads API secara default akan disetel ke
RESOURCE_NAME_ONLY
dan responsnya hanya akan berisi nama resource dari
setiap resource yang dibuat atau diperbarui.
Berikut adalah contoh pengambilan resource yang dapat diubah dari panggilan 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]; }