Рекомендации по использованию метода mutate

Следуйте этим рекомендациям, чтобы оптимизировать производительность, управлять зависимостями между операциями и обрабатывать ответы при изменении ресурсов в Google Ads API.

Временные названия ресурсов

Как GoogleAdsService.Mutate, так и BatchJobService поддерживают временные названия ресурсов, на которые можно ссылаться в последующих операциях. Это позволяет создать кампанию и связанные с ней группы объявлений, объявления и ключевые слова в одном запросе mutate или пакетном задании.

Чтобы сослаться на только что созданный ресурс в том же запросе mutate или пакетном задании, укажите отрицательное целое число (например, -1 или -2, за исключением 0) в поле resource_name нового ресурса. Например, при создании кампании в пакетном запросе задайте для нее название ресурса customers/CUSTOMER_ID/campaigns/-1. При создании группы объявлений в рамках последующей операции в том же запросе укажите customers/CUSTOMER_ID/campaigns/-1 в качестве родительской кампании. API автоматически заменяет -1 на фактический идентификатор кампании, созданный при ее создании.

Ограничения на использование

При использовании временных названий ресурсов учитывайте следующие правила:

• Порядок имеет значение. Ссылаться на временное название ресурса можно только после того, как вы его определили. В списке операций зависимая операция (например, создание группы объявлений) должна следовать за операцией, которая создает родительский ресурс (например, создание кампании).
• Область действия – один запрос или пакетное задание. Временные названия ресурсов не сохраняются между отдельными заданиями или запросами mutate. Чтобы сослаться на ресурс, созданный в предыдущем задании или запросе mutate, используйте его фактическое название, сгенерированное системой.
• Глобальная уникальность. В рамках одного задания или запроса mutate каждое временное название ресурса должно использовать уникальное отрицательное целое число для всех типов ресурсов. Например, в одном запросе нельзя назначить значение -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, соблюдая зависимости между родительскими и дочерними элементами. Этот метод последовательно считывает операции, пока не встретит другой тип ресурса, а затем объединяет все смежные операции одного типа в один запрос к серверной службе.

Например, если вы включите в повторяющееся поле mutate_operations пять операций с кампаниями, а затем 10 операций с группами объявлений, система выполнит два вызова: один к CampaignService для пяти операций с кампаниями, а второй – к AdGroupService для 10 операций с группами объявлений.

Если же вы будете чередовать операции, например [campaign, ad group, campaign, ad group], то будет выполнено четыре отдельных вызова. Чередующиеся вызовы снижают производительность API и могут привести к истечению времени ожидания запроса при обработке больших пакетов.

Важно! Сгруппируйте все операции с ресурсами одного типа в вызовах GoogleAdsService.Mutate. При этом родительские ресурсы (например, кампании с временными идентификаторами) должны предшествовать зависимым дочерним ресурсам (например, группам объявлений).

Как обрабатывать частичные сбои и ограничения на пакеты

По умолчанию 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. Хотя пакетные задания выполняются с частичным отказом (по умолчанию 1000 операций на внутренний подпакет), BatchJobService автоматически группирует определенные смежные зависимые операции для одного и того же родительского идентификатора в атомарные подпакеты:
  • Операция AssetGroupOperation (create), за которой следуют смежные операции AssetGroupAssetOperation (create) для одного и того же идентификатора AssetGroup (всего до 1000 операций, которые выполняются атомарно с ошибкой BatchJobError.ASSET_GROUP_AND_ASSET_GROUP_ASSET_TRANSACTION_FAILURE; каждая операция AssetGroupOperation update или remove выполняется в отдельном подпакете с одной операцией).
  • Операция 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).

Получение изменяемых атрибутов из ответа

Если в запросе mutate вы зададите для параметра response_content_type значение MUTABLE_RESOURCE, то в ответе будет содержаться параметр resource_name и объект ресурса, заполненный изменяемыми полями (а также ключевыми полями, заполняемыми системой, например ExperimentArm.in_design_campaigns) для каждого поддерживаемого объекта, созданного или обновленного (но не удаленного) в результате запроса. Для операций remove или для типов ресурсов, которые не поддерживают возврат MUTABLE_RESOURCE, ответ всегда возвращает только resource_name. Это позволяет не отправлять дополнительный запрос Search или SearchStream после каждого вызова mutate.

Примечание. Запрос MUTABLE_RESOURCE увеличивает размер полезной нагрузки ответа. Используйте этот вариант, только если приложению нужны возвращаемые значения полей, и не включайте его для очень больших пакетов без необходимости.

Если вы не зададите 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);
  }
}
CreateSearchCustomExperiment.java
      

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);
}
CreateSearchCustomExperiment.cs
      

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];
}
CreateExperiment.php
      

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]
create_search_custom_experiment.py
      

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
create_experiment.rb
      

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];
}
create_experiment.pl
      

curl

Примечание. Хотя здесь не приводится пример кода REST для этого шага, вы можете выполнить его с помощью ручного запроса REST.

Ознакомьтесь с документацией по REST-интерфейсу Google Ads API и справочными страницами по методам. Вам нужно будет создать полезную нагрузку JSON на основе определений протокола.

Полезные ресурсы:

• Использование REST
• Структура интерфейса REST
• Сопоставление полей JSON
• Ознакомьтесь с документацией по REST API для конкретного сервиса и метода.