Следуйте этим рекомендациям, чтобы оптимизировать производительность, управлять зависимостями между операциями и обрабатывать ответы при изменении ресурсов в API Google Ads.
Временные имена ресурсов
Как GoogleAdsService.Mutate , так и BatchJobService поддерживают временные имена ресурсов, на которые можно ссылаться в последующих операциях. Это позволяет создавать кампанию и связанные с ней группы объявлений, объявления и ключевые слова в рамках одного запроса на изменение или пакетного задания.
Чтобы сослаться на вновь созданный ресурс в рамках того же запроса на изменение или пакетного задания, укажите отрицательный целочисленный идентификатор (например, -1 или -2 , за исключением 0 ) в поле resource_name нового ресурса. Например, при создании кампании в пакетном запросе задайте имя ресурса customers/CUSTOMER_ID/campaigns/-1 . При создании группы объявлений в последующей операции в рамках того же запроса укажите customers/CUSTOMER_ID/campaigns/-1 в качестве родительской кампании. API автоматически заменит -1 на фактический идентификатор кампании, сгенерированный при создании.
Ограничения использования
При использовании временных имен ресурсов следует учитывать следующие правила:
- Порядок имеет значение: вы можете ссылаться на имя временного ресурса только после того, как определите его. В списке операций зависимая операция (например, создание группы объявлений) должна располагаться после операции, которая создает родительский ресурс (например, создание кампании).
- Область действия — отдельный запрос или пакетное задание: временные имена ресурсов не сохраняются между отдельными заданиями или запросами на изменение. Для ссылки на ресурс, созданный в предыдущем задании или запросе на изменение, используйте его фактическое имя, сгенерированное системой.
- Глобальная уникальность: в рамках одного задания или запроса на изменение каждое имя временного ресурса должно использовать уникальное отрицательное целое число для всех типов ресурсов. Например, нельзя присвоить
-1одновременно кампании и группе объявлений в одном запросе. Повторное использование временного идентификатора в одном запросе или пакетном задании приводит к ошибкеNewResourceCreationError.DUPLICATE_TEMP_IDS.
Пример полезной нагрузки
Предположим, вы хотите добавить кампанию, группу объявлений и объявление в одном API-запросе или пакетном задании. Вы можете структурировать массив mutateOperations в полезной нагрузке запроса GoogleAdsService.Mutate или BatchJobService.AddBatchJobOperations , как показано в следующем примере REST JSON (другие обязательные поля ресурсов опущены для краткости):
{
"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 , при этом соблюдаются зависимости между родительскими и дочерними элементами. Этот метод последовательно считывает операции до тех пор, пока не встретит другой тип ресурса, а затем объединяет все смежные операции одного типа в один запрос к бэкэнд-сервису.
Например, если вы укажете в поле repeated mutate_operations 5 операций кампании, за которыми последуют 10 операций группы объявлений, система выполнит два вызова бэкэнда: один к 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, размер каждого отдельногоMutateOperation— 10 484 504 байта, а размер каждогоAddBatchJobOperationsRequest— 41 937 920 байт (возвращаяBatchJobError.REQUEST_TOO_LARGEв случае превышения любого из ограничений, всего до 1 000 000 операций на пакетное задание). Одновременные изменения, затрагивающие одну и ту же кампанию или учетную запись, могут вызывать ошибкиDatabaseError.CONCURRENT_MODIFICATION. - Атомарная подгруппировка
BatchJobService: Хотя пакетные задания выполняются с семантикой частичного сбоя (по умолчанию 1000 операций на внутренний подпакет),BatchJobServiceавтоматически группирует определенные смежные зависимые операции для одного и того же родительского идентификатора в атомарные подпакеты:- Операция
AssetGroupOperation(create), за которой следуют последовательные операцииAssetGroupAssetOperation(create) для одного и того же идентификатораAssetGroup(всего до 1000 операций, завершающихся атомарно с ошибкойBatchJobError.ASSET_GROUP_AND_ASSET_GROUP_ASSET_TRANSACTION_FAILURE; каждоеupdateилиremoveAssetGroupOperationвыполняется в отдельном подпакете, состоящем из одной операции). - Операция Performance Max
CampaignOperation(create, когда включены рекомендации по бренду — это значение по умолчанию, если толькоbrand_guidelines_enabledне установлено вfalseилиhotel_property_asset_setне установлено), за которой следуют смежные операцииCampaignAssetOperation(create) для того же идентификатораCampaign(всего до 1000 операций, завершающихся атомарной ошибкой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 после каждого вызова mutate.
Если response_content_type не задан, API Google Ads по умолчанию использует значение 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]
Руби
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]; }