Лучшие практики и ограничения

При использовании BatchJobService учитывайте следующие рекомендации.

Повышение пропускной способности

  • Предпочтение отдается меньшему количеству крупных заказов, чем множеству мелких.

  • Упорядочивайте загружаемые операции по типу операции (за исключением взаимозависимых операций, которые должны быть сгруппированы последовательно в атомарные подпакеты ). Например, если ваше задание содержит операции по добавлению стандартных кампаний, групп объявлений и критериев групп объявлений, упорядочите операции в загружаемом файле таким образом, чтобы сначала были операции с кампаниями , затем все операции с группами объявлений и, наконец, все операции с критериями групп объявлений .

  • Внутри операций одного типа группировка по родительскому ресурсу может повысить производительность. Например, если у вас есть серия объектов AdGroupCriterionOperation , эффективнее группировать операции по группам объявлений, чем смешивать операции, влияющие на критерии групп объявлений в разных группах.

Атомарность при разделении пакетов

API Google Ads разделяет операции в отправленном пакетном задании на более мелкие подпакеты для обработки. В то время как стандартные подпакеты выполняются с включенной возможностью частичного сбоя, подпакеты для определенных взаимозависимых операций обрабатываются атомарно как единая транзакция:

Для подпакетов создания как AssetGroup , так и Performance Max Campaign (до 1000 операций в каждом подпакете; любые дочерние операции create , превышающие 999, переносятся в следующий неатомарный подпакет):

  • Родительская операция create ( resource_name в AssetGroup или Campaign ) и последующие дочерние операции create ( asset_group в AssetGroupAsset или campaign в CampaignAsset ) должны указывать один и тот же отрицательный временный идентификатор .
  • Размещайте все необходимые операции AssetOperation ( create ) для новых ресурсов Asset перед родительской AssetGroupOperation или CampaignOperation ( create ), никогда не между родительской операцией create и ее дочерней операцией link create (что немедленно закроет атомарный подпакет и отделит создание родительского ресурса от связанных с ним ресурсов).

При сбое атомарного подпакета BatchJobResult.status проблемной операции содержится информация о лежащей в основе ошибке проверки, а оставшиеся операции в этом подпакете откатываются с соответствующей ошибкой транзакции для этого подпакета. Проверьте смежные записи BatchJobResult , имеющие одинаковый идентификатор AdGroup , AssetGroup или Campaign ID, чтобы определить первопричину ошибки.

Если связанные операции в любой из этих групп не добавляются последовательно, API Google Ads разделяет их на отдельные подпакеты, что приводит к несоответствию минимальным требованиям к ресурсам или оставляет деревья групп объявлений неполными. Подробнее см. разделы «Использование фильтров групп объявлений в пакетных заданиях» и «Пакетная обработка Performance Max» .

Логическая группировка

При изменении иерархии таргетинга по продуктам ( AssetGroupListingGroupFilterOperation в кампаниях Performance Max или AdGroupCriterionOperation в торговых кампаниях) или создании новой AssetGroup или Campaign Performance Max, группируйте все операции, нацеленные на один и тот же родительский ресурс ( AssetGroup , AdGroup или Campaign ), последовательно. Это уменьшает конфликты блокировок на бэкэнде и сохраняет взаимозависимые деревья вместе.

Согласованность данных

Поскольку проверка деревьев фильтров групп и требований к ресурсам Performance Max выполняется в конце каждой атомарной подпакетной транзакции, избегайте разделения обновлений одного и того же родительского ресурса на несовпадающие диапазоны в рамках задания или между параллельными заданиями.

Избегайте проблем, связанных с параллельным доступом.

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

  • Не следует отправлять несколько операций, изменяющих один и тот же объект, в рамках одного и того же задания, поскольку результат может быть непредсказуемым.

Получение результатов оптимальным способом

  • Не следует слишком часто проверять статус задания, иначе вы рискуете столкнуться с ошибками, связанными с превышением лимита запросов.

  • Оставьте page_size неустановленным (или установите его на максимальное значение 1000 ) при вызове ListBatchJobResults , чтобы минимизировать количество обращений к функции пагинации, и устанавливайте response_content_type в значение MUTABLE_RESOURCE только в том случае, если ваше приложение проверяет возвращаемые поля ресурса, выходящие за рамки resource_name .

  • Порядок отображения результатов совпадает с порядком загрузки.

Дополнительные рекомендации по использованию

  • Вы можете установить верхний предел времени выполнения пакетного задания до его отмены. При создании нового пакетного задания установите поле metadata.execution_limit_seconds на желаемый временной лимит в секундах. Если metadata.execution_limit_seconds не задано, по умолчанию ограничение по времени отсутствует.

  • Хотя протокол ограничивает количество операций до 10 000 на один запрос, мы рекомендуем добавлять не более 1000 операций в один AddBatchJobOperationsRequest и использовать sequence_token для загрузки остальных операций в то же задание. В зависимости от размера операций, отправка слишком большого количества операций в одном AddBatchJobOperationsRequest может привести к ошибке BatchJobError.REQUEST_TOO_LARGE . Вы можете обработать эту ошибку, уменьшив количество операций и повторив AddBatchJobOperationsRequest .

Ограничения

  • Каждый BatchJob поддерживает до одного миллиона операций. Превышение этого лимита при вызове AddBatchJobOperations приводит к ошибке ResourceCountLimitExceededError.RESOURCE_LIMIT (с ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB в ErrorDetails.resource_count_details ).

  • В каждой учетной записи может одновременно находиться до 100 активных или ожидающих заданий. Превышение этого лимита при создании пакетного задания с помощью MutateBatchJob приводит к ошибке ResourceCountLimitExceededError.RESOURCE_LIMIT (с ResourceLimitType.BATCH_JOBS_PER_CUSTOMER в ErrorDetails.resource_count_details ).

  • Задания, ожидающие выполнения более 7 дней, автоматически удаляются.

  • Для каждого запроса AddBatchJobOperationsRequest установлено жесткое ограничение в 10 000 операций изменения за один запрос. Превышение 10 000 операций в одном запросе приводит к ошибке BatchJobError.REQUEST_TOO_LARGE .

  • Для поля page_size в ListBatchJobResultsRequest :

    • Если page_size не задан или равен 0 , по умолчанию используется максимальное значение 1000 .
    • Если page_size превышает 1000 или меньше 0 , API возвращает ошибку BatchJobError.INVALID_PAGE_SIZE .

  • Каждый AddBatchJobOperationsRequest имеет максимальный размер 41 937 920 байт. Если вы превысите этот лимит, вы получите ошибку BatchJobError.REQUEST_TOO_LARGE (или INTERNAL_ERROR если запрос отклонен на транспортном уровне). Вы можете определить сериализованный размер запроса перед отправкой и предпринять соответствующие действия, если он окажется слишком большим:

    Java 

    
static final int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.getSerializedSize();

    C# 

    
const int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.CalculateSize();

    PHP 

    
const MAX_REQUEST_BYTES = 41937920;

// ... (code to get the AddBatchJobOperationsRequest object)

$size_in_bytes = $request->byteSize();

    Python 

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = type(request).pb(request).ByteSize()

    Руби 

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = request.to_proto.bytesize

    Perl 

    
use JSON::XS;
use constant MAX_REQUEST_BYTES => 41937920;

# ... (code to get the AddBatchJobOperationsRequest object)

# The Perl client library uses REST/JSON; UTF-8 JSON byte length provides a
# conservative upper-bound estimate of the serialized request size.
my $json_encoder = JSON::XS->new->utf8->convert_blessed;
my $size_in_bytes = length($json_encoder->encode($request));

Размер операции одиночной мутации

Хотя общий размер запроса может достигать 41 937 920 байт, сериализованный размер одной MutateOperation в пакете ограничен 10 484 504 байтами (10 МиБ минус 1256 байт). Превышение этого предела приводит к ошибке BatchJobError.REQUEST_TOO_LARGE . Обратите внимание, что хотя в справочной документации для BatchJobError.REQUEST_TOO_LARGE указан порог в 10 484 504 байта, AddBatchJobOperations возвращает тот же код ошибки, когда превышен любой из трех пороговых значений запроса (41 937 920 байт общего запроса, 10 484 504 байта одной операции или 10 000 операций за вызов), при этом в поле message об ошибке указывается, какой именно предел был нарушен.

Назад
Вывод групповых фильтров