نامهای منابع موقت
GoogleAdsService.Mutate
از نامهای منبع موقت پشتیبانی میکند که میتوانند بعداً در همان درخواست به آنها ارجاع داده شوند. این به شما امکان میدهد، برای مثال، یک کمپین و گروههای تبلیغاتی، تبلیغات، کلمات کلیدی و غیره مرتبط با آن را در یک درخواست واحد ایجاد کنید.
شما میتوانید این کار را با مشخص کردن resource_name
منبع جدید برای استفاده از یک شناسه منفی انجام دهید. برای مثال، فرض کنید یک کمپین ایجاد میکنید و نام منبع آن را به صورت customers/<YOUR_CUSTOMER_ID>/campaigns/-1
مشخص میکنید. وقتی گروه تبلیغاتی را در عملیات بعدی ایجاد میکنید، میتوانید آن را با آن نام منبع ارجاع دهید و -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"
...
}
}
},
]
یک شناسه موقت جدید برای گروه تبلیغاتی استفاده میشود، زیرا نمیتوانیم از -1
که برای کمپین استفاده کردیم، دوباره استفاده کنیم. همچنین هنگام ایجاد یک تبلیغ در گروه تبلیغاتی، به این گروه تبلیغاتی ارجاع میدهیم. خود گروه تبلیغاتی به نام منبعی که برای کمپین در عملیات قبلی در درخواست ایجاد کردهایم، ارجاع میدهد، در حالی که resource_name
در ad_group_ad_operation
ضروری نیست زیرا هیچ عملیات دیگری به آن ارجاع نمیدهد.
عملیات هم نوع را گروه بندی کنید
هنگام استفاده از GoogleAdsService.Mutate
، گروهبندی عملیاتها بر اساس منابعشان در آرایه عملیات تکراری بسیار مهم است. این متد mutate اساساً به عنوان راهی برای فراخوانی خودکار و متوالی متد mutate هر منبع عمل میکند. برای انجام این کار، عملیاتها را میخواند تا زمانی که یکی را برای نوع متفاوتی از منابع پیدا کند، سپس تمام عملیاتهای از نوع یکسان را در یک درخواست دسته بندی میکند.
برای مثال، اگر ۵ عملیات کمپین و به دنبال آن ۱۰ عملیات گروه تبلیغاتی در فیلد operations
تکراری در فراخوانی Mutate
خود داشته باشید، سیستم در مجموع دو فراخوانی در backend انجام میدهد، یکی برای ۵ عملیات به CampaignService
و دیگری برای ۱۰ عملیات به AdGroupService
. با این حال، اگر آنها را به طور متفاوتی گروهبندی کنید، عملکرد میتواند بسیار بدتر شود. اگر فقط ۲ کمپین و ۲ گروه تبلیغاتی ایجاد کنید، اما آنها را طوری ترکیب کنید که عملیات به صورت [کمپین، گروه تبلیغاتی، کمپین، گروه تبلیغاتی] مرتب شوند، در مجموع چهار فراخوانی در backend انجام میشود. این امر منجر به عملکرد کندتر API میشود و در موارد شدید حتی میتواند منجر به وقفه شود.
بازیابی ویژگیهای قابل تغییر از پاسخ
اگر response_content_type
درخواست mutate خود را روی MUTABLE_RESOURCE
تنظیم کنید، پاسخ شامل مقادیر تمام فیلدهای mutable برای هر شیء ایجاد شده یا بهروزرسانی شده توسط درخواست خواهد بود. از این ویژگی برای جلوگیری از درخواست search
اضافی یا searchStream
پس از هر درخواست mutate استفاده کنید.
اگر response_content_type
تنظیم نکنید، API گوگل ادز به صورت پیشفرض روی RESOURCE_NAME_ONLY
تنظیم میشود و پاسخ فقط شامل نام منبع هر منبع ایجاد شده یا بهروزرسانی شده خواهد بود.
در اینجا مثالی از بازیابی یک منبع تغییرپذیر از یک فراخوانی 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.V22.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: GoogleAdsClient, customer_id: str, base_campaign_id: str, experiment: str, ) -> str: """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: List[ExperimentArmOperation] = [] campaign_service: CampaignServiceClient = client.get_service( "CampaignService" ) # The "control" arm references an already-existing campaign. operation_1: ExperimentArmOperation = client.get_type( "ExperimentArmOperation" ) exa_1: ExperimentArm = 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: ExperimentArmOperation = client.get_type( "ExperimentArmOperation" ) exa_2: ExperimentArm = 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: ExperimentArmServiceClient = client.get_service( "ExperimentArmService" ) request: MutateExperimentArmsRequest = 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: MutateExperimentArmsResponse = ( 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: Any = response.results[0] treatment_arm_result: Any = 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::V22::Services::ExperimentArmService::ExperimentArmOperation ->new({ create => Google::Ads::GoogleAds::V22::Resources::ExperimentArm->new({ # The "control" arm references an already-existing campaign. control => "true", campaigns => [ Google::Ads::GoogleAds::V22::Utils::ResourceNames::campaign( $customer_id, $base_campaign_id ) ], experiment => $experiment, name => "control arm", trafficSplit => 40 })}); push @$operations, Google::Ads::GoogleAds::V22::Services::ExperimentArmService::ExperimentArmOperation ->new({ create => Google::Ads::GoogleAds::V22::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]; }