כדי לבצע אופטימיזציה של הביצועים, לנהל את יחסי התלות בין הפעולות ולטפל בתגובות כשמשנים משאבים ב-Google Ads API, כדאי לפעול לפי השיטות המומלצות הבאות.
שמות משאבים זמניים
גם GoogleAdsService.Mutate וגם BatchJobService תומכים בשמות משאבים זמניים שאפשר להפנות אליהם בפעולות הבאות. כך אפשר ליצור קמפיין ואת הקבוצות של המודעות, המודעות ומילות המפתח שמשויכות אליו באמצעות בקשת שינוי אחת או עבודת אצווה אחת.
כדי להפנות למשאב חדש שנוצר באותה בקשה לשינוי נתונים או באותו batch job, מציינים מזהה של מספר שלם שלילי (כמו -1 או -2, לא כולל 0) בשדה resource_name של המשאב החדש. לדוגמה, כשיוצרים קמפיין בבקשת Batch, מגדירים את שם המשאב שלו ל-customers/CUSTOMER_ID/campaigns/-1.
כשיוצרים קבוצת מודעות בפעולה מאוחרת יותר באותה בקשה,
מציינים את customers/CUSTOMER_ID/campaigns/-1 כקמפיין האב. ה-API מחליף באופן אוטומטי את -1 במזהה הקמפיין שנוצר בפועל.
מגבלות שימוש
כשמשתמשים בשמות זמניים של משאבים, חשוב לזכור את הכללים הבאים:
- הסדר חשוב: אפשר להפנות לשם זמני של משאב רק אחרי שמגדירים אותו. ברשימה של פעולות, הפעולה התלויה (כמו יצירת קבוצת מודעות) חייבת להופיע אחרי הפעולה שיוצרת את משאב ההורה שלה (כמו יצירת קמפיין).
- היקף של בקשה יחידה או של משימה באצווה: שמות משאבים זמניים לא נשמרים בין משימות נפרדות או בקשות לשינוי נתונים. כדי להפנות למשאב שנוצר בעבודה קודמת או בבקשת שינוי, צריך להשתמש בשם המשאב בפועל שנוצר על ידי המערכת.
- ייחודיות גלובלית: בכל משימה או בקשה לשינוי נתונים, לכל שם זמני של משאב צריך להיות מספר שלם שלילי ייחודי בכל סוגי המשאבים.
לדוגמה, אי אפשר להקצות את
-1גם לקמפיין וגם לקבוצת מודעות באותה בקשה. אם תשתמשו שוב במזהה זמני באותה בקשה או באותו batch job, תוחזר השגיאהNewResourceCreationError.DUPLICATE_TEMP_IDS.
דוגמה למטען ייעודי (payload)
נניח שרוצים להוסיף קמפיין, קבוצת מודעות ומודעה בבקשת API אחת או במשימה באצווה אחת. אפשר ליצור את מערך mutateOperations במטען ייעודי (payload) של בקשת GoogleAdsService.Mutate או BatchJobService.AddBatchJobOperations, כמו בדוגמה הבאה של JSON ב-REST (השמטנו שדות אחרים של משאבים שנדרשים כדי שהדוגמה תהיה קצרה יותר):
{
"mutateOperations": [
{
"campaignOperation": {
"create": {
"resourceName": "customers/CUSTOMER_ID/campaigns/-1"
}
}
},
{
"adGroupOperation": {
"create": {
"resourceName": "customers/CUSTOMER_ID/adGroups/-2",
"campaign": "customers/CUSTOMER_ID/campaigns/-1"
}
}
},
{
"adGroupAdOperation": {
"create": {
"adGroup": "customers/CUSTOMER_ID/adGroups/-2"
}
}
}
]
}
הדוגמה הזו ממחישה את הפרטים החשובים הבאים:
- קבוצת המודעות משתמשת במזהה זמני חדש (
-2) כי המזהה-1כבר הוקצה לקמפיין. - קבוצת המודעות מפנה אל
customers/CUSTOMER_ID/campaigns/-1כדי לקשר את עצמה לקמפיין שנוצר בפעולה הקודמת. - הבקשה
adGroupAdOperationמפנה אלcustomers/CUSTOMER_ID/adGroups/-2ומשמיטה אתresourceNameכי אין פעולה נוספת בבקשה שמפנה למודעה החדשה.
קיבוץ פעולות מאותו סוג
כשמשתמשים ב-GoogleAdsService.Mutate, מקבצים את הפעולות לפי סוג המשאב במערך החוזר mutate_operations, תוך שמירה על יחסי התלות בין הורה לצאצא. השיטה הזו קוראת פעולות ברצף עד שהיא נתקלת בסוג משאב אחר, ואז מקבצת את כל הפעולות הרציפות מאותו סוג לבקשת שירות אחת לשירות קצה עורפי.
לדוגמה, אם תכללו 5 פעולות של קמפיינים ואחריהן 10 פעולות של קבוצות של מודעות בשדה החוזר mutate_operations, המערכת תבצע שתי קריאות לקצה העורפי: אחת אל CampaignService בשביל 5 הפעולות של הקמפיינים, והשנייה אל AdGroupService בשביל 10 הפעולות של קבוצות המודעות.
לעומת זאת, אם נבצע פעולות שזירה על ידי סידורן כ-[campaign, ad group,
campaign, ad group], יתבצעו ארבע קריאות נפרדות לשרת העורפי. קריאות משולבות פוגעות בביצועי ה-API ויכולות לגרום לפסק זמן בבקשות של קבוצות גדולות.
טיפול בכשלים חלקיים ובמגבלות על חבילות
כברירת מחדל, GoogleAdsService.Mutate מבטל את כל הבקשה אם פעולה אחת נכשלת. כדי לבצע פעולות תקינות גם אם פעולות אחרות באותה בקשה נכשלות, צריך להגדיר את partial_failure ל-true בבקשה ולבדוק את partial_failure_error בתגובה. כשהערך של partial_failure הוא true, אם פעולת הורה שמגדירה מזהה זמני (כמו customers/CUSTOMER_ID/campaigns/-1) נכשלת באימות, גם כל פעולות הצאצא התלויות שמפנות לאותו מזהה זמני באותה בקשה נכשלות עם השגיאה NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. פרטים נוספים זמינים במדריך בנושא שגיאות חלקיות.
חשוב לזכור גם את גודל הבקשה, את חלוקת הבקשות לקבוצות משנה ואת מגבלות הקצב:
- מגבלות על גודל הבקשה והנתונים: בקשה אחת של
GoogleAdsService.Mutateיכולה לכלול עד 10,000 פעולות שינוי (או עד 20,000 אם כל הפעולות בבקשה הןAdGroupCriterionOperation, והמערכת מחזירהRequestError.TOO_MANY_MUTATE_OPERATIONSאם חורגים מהמגבלה), ולכל היותר 100 פעולות שלRequestError.TOO_MANY_ACTION_OPERATIONS. בקשה שלBatchJobService.AddBatchJobOperationsיכולה לכלול עד 10, 000 פעולות לכל קריאה,10,484, 504 בייט לכלMutateOperationו-41,937,920 בייט לכלAddBatchJobOperationsRequest(המערכת מחזירהBatchJobError.REQUEST_TOO_LARGEאם חורגים מהמגבלה, ויכולות להיות עד 1,000,000 פעולות בסך הכול לכל עבודת אצווה). שינויים בו-זמניים שמטרגטים את אותו קמפיין או חשבון עלולים להפעיל שגיאותDatabaseError.CONCURRENT_MODIFICATION. - יצירת קבוצות משנה אטומיות ב-
BatchJobService: למרות שמשימות באצווה מבוצעות לפי סמנטיקה של כשל חלקי (כברירת מחדל, 1,000 פעולות לכל קבוצת משנה פנימית),BatchJobServiceמקבץ באופן אוטומטי פעולות תלויות רציפות מסוימות לאותו מזהה הורה לקבוצות משנה אטומיות:-
AssetGroupOperation(create) ואחריו רצף שלAssetGroupAssetOperation(create) פעולות לאותו מזההAssetGroup(עד 1,000 פעולות בסך הכול, עם ביצוע אטומי שנכשל עםBatchJobError.ASSET_GROUP_AND_ASSET_GROUP_ASSET_TRANSACTION_FAILURE; כלAssetGroupOperationupdateאוremoveמבוצעים כקבוצת משנה עצמאית של פעולה אחת). - פעולה אחת של
CampaignOperationבקמפיין למיקסום הביצועים (create, כשספר המותג מופעל – זו ברירת המחדל, אלא אםbrand_guidelines_enabledמוגדר כ-falseאו ש-hotel_property_asset_setמוגדר) ואחריה פעולות רציפות שלCampaignAssetOperation(create) באותו מזההCampaign(עד 1,000 פעולות בסך הכול, שנכשלות באופן אטומי עםBatchJobError.CAMPAIGN_AND_CAMPAIGN_ASSET_TRANSACTION_FAILURE). - פעולות עוקבות של
AssetGroupListingGroupFilterOperation(max 10,000, נכשלות באופן אטומי עםBatchJobError.ASSET_GROUP_LISTING_GROUP_FILTER_TRANSACTION_FAILURE) אוAdGroupCriterionOperation(listing_group, max 20,000, נכשלות באופן אטומי עםCriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION) לאותו רכיב אב (AssetGroupאוAdGroup).
-
שליפת מאפיינים שניתנים לשינוי מהתשובה
אם מגדירים את response_content_type של הבקשה לשינוי נתונים לערך MUTABLE_RESOURCE, התגובה מכילה את resource_name ואת אובייקט המשאב שמאוכלס בשדות הניתנים לשינוי שלו (וגם שדות מפתח שמאוכלסים על ידי המערכת במשאב המוחזר, כמו ExperimentArm.in_design_campaigns) לכל אובייקט נתמך שנוצר או עודכן (לא הוסר) על ידי הבקשה. בפעולות remove, או בסוגי משאבים שלא תומכים בהחזרת MUTABLE_RESOURCE, התגובה תמיד מחזירה רק את resource_name. כדאי להשתמש בתכונה הזו כדי להימנע משליחת בקשה נוספת מסוג Search או SearchStream אחרי כל קריאה לשינוי.
אם לא מגדירים את response_content_type, ברירת המחדל של Google Ads API היא RESOURCE_NAME_ONLY, ומוחזר רק resource_name של כל משאב שעבר שינוי.
בדוגמה הבאה אפשר לראות איך מאחזרים משאב שניתן לשינוי מקריאה ל-mutate:
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( // In standard campaign experiments, creating the treatment arm automatically // generates a draft campaign 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#
private static (MutateExperimentArmResult, MutateExperimentArmResult) CreateExperimentArms(GoogleAdsClient client, long customerId, long baseCampaignId, string experimentResourceName) { // Get the ExperimentArmService. ExperimentArmServiceClient experimentService = client.GetService( Services.V25.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. // In standard campaign experiments, creating the treatment arm automatically // generates a draft campaign 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: 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) # In standard campaign experiments, creating the treatment arm automatically # generates a draft campaign 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]
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::V25::Services::ExperimentArmService::ExperimentArmOperation ->new({ create => Google::Ads::GoogleAds::V25::Resources::ExperimentArm->new({ # The "control" arm references an already-existing campaign. control => "true", campaigns => [ Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign( $customer_id, $base_campaign_id ) ], experiment => $experiment, name => "control arm", trafficSplit => 40 })}); push @$operations, Google::Ads::GoogleAds::V25::Services::ExperimentArmService::ExperimentArmOperation ->new({ create => Google::Ads::GoogleAds::V25::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]; }