Práticas recomendadas e limitações

Considere estas diretrizes ao usar o BatchJobService.

Melhorar a capacidade de processamento

  • É preferível ter menos jobs maiores do que muitos jobs menores.

  • Ordene as operações enviadas por tipo de operação (exceto as operações interdependentes que precisam ser agrupadas consecutivamente em sublotes atômicos). Por exemplo, se o job tiver operações para adicionar campanhas padrão, grupos de anúncios e critérios de grupos de anúncios, ordene as operações no upload para que todas as operações de campanha sejam as primeiras, seguidas por todas as operações de grupo de anúncios e, por fim, todas as operações de critério de grupo de anúncios.

  • Nas operações do mesmo tipo, é possível melhorar o desempenho agrupando-as por recurso pai. Por exemplo, se você tiver uma série de objetos AdGroupCriterionOperation, é mais eficiente agrupar as operações por grupo de anúncios do que misturar operações que afetam os critérios de grupos de anúncios em diferentes grupos de anúncios.

Atomicidade na divisão em lote

A API Google Ads divide as operações em um job em lote enviado em sublotes menores para processamento. Enquanto os sublotes padrão são executados com a falha parcial ativada, os sublotes de determinadas operações interdependentes são processados de forma atômica como uma única transação:

Para sub-lotes de criação de AssetGroup e de campanhas Performance Max Campaign (até 1.000 operações no total por sub-lote; qualquer operação filha create além de 999 é transferida para o próximo sub-lote não atômico):

Quando um sublote atômico falha, o BatchJobResult.status da operação ofensiva contém o erro de validação subjacente, enquanto as operações restantes nesse sublote são revertidas com o erro de transação correspondente para esse sublote. Inspecione as entradas BatchJobResult adjacentes que compartilham o mesmo ID AdGroup, AssetGroup ou Campaign para identificar o erro de causa raiz.

Se as operações relacionadas em qualquer um desses grupos não forem adicionadas consecutivamente, a API Google Ads as dividirá em sublotes separados, fazendo com que a modificação não atenda aos requisitos mínimos de recursos ou deixando as árvores de grupos de produtos anunciados incompletas. Consulte Usar filtros do grupo de produtos anunciados em jobs em lote e Processamento em lote das campanhas Performance Max para mais detalhes.

Agrupamento lógico

Ao modificar uma hierarquia de segmentação de produtos (AssetGroupListingGroupFilterOperation em campanhas Performance Max ou AdGroupCriterionOperation em campanhas do Shopping) ou criar um novo AssetGroup ou Campaign Performance Max, agrupe todas as operações que segmentam o mesmo recurso pai (AssetGroup, AdGroup ou Campaign) consecutivamente. Isso reduz a contenção de bloqueio de back-end e mantém as árvores interdependentes juntas.

Consistência de dados

Como as árvores de filtros do grupo de produtos anunciados e os requisitos de recursos das campanhas Performance Max são validados no final de cada transação de sublote atômico, evite dividir as atualizações do mesmo recurso pai em intervalos descontínuos em um job ou em jobs simultâneos.

Evitar problemas de simultaneidade

  • Ao enviar vários jobs simultâneos para a mesma conta, reduza a probabilidade de jobs operarem nos mesmos objetos ao mesmo tempo, mantendo jobs grandes. Muitos jobs inacabados com o status RUNNING que tentam modificar o mesmo conjunto de objetos podem levar a condições semelhantes a um impasse, resultando em lentidão severa e até mesmo falhas de job.

  • Não envie várias operações que modificam o mesmo objeto no mesmo job, porque o resultado pode ser imprevisível.

Recuperar resultados de maneira ideal

  • Não consulte o status do job com muita frequência, ou você poderá receber erros de limite de taxa.

  • Deixe page_size sem definição (ou defina-o como o máximo de 1000) ao chamar ListBatchJobResults para minimizar as idas e voltas de paginação e defina apenas response_content_type como MUTABLE_RESOURCE se o aplicativo inspecionar os campos de recursos retornados além de resource_name.

  • A ordem dos resultados é a mesma do upload.

Orientações adicionais de uso

  • É possível definir um limite máximo para o tempo de execução de um job em lote antes que ele seja cancelado. Ao criar um job em lote, defina o campo metadata.execution_limit_seconds com o limite de tempo de sua preferência, em segundos. Não há limite de tempo padrão se metadata.execution_limit_seconds não estiver definido.

  • Embora o limite do protocolo seja de 10.000 operações por solicitação, recomendamos adicionar no máximo 1.000 operações por AddBatchJobOperationsRequest e usar o sequence_token para fazer upload do restante das operações para o mesmo job. Dependendo do tamanho das operações, o envio de muitas operações em um único AddBatchJobOperationsRequest pode causar um erro BatchJobError.REQUEST_TOO_LARGE. Para resolver esse erro, reduza o número de operações e tente novamente o AddBatchJobOperationsRequest.

Limitações

  • Cada BatchJob aceita até um milhão de operações. Exceder esse limite ao chamar AddBatchJobOperations retorna um erro ResourceCountLimitExceededError.RESOURCE_LIMIT (com ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB em ErrorDetails.resource_count_details).

  • Cada conta pode ter até 100 jobs ativos ou pendentes ao mesmo tempo. Exceder esse limite ao criar um job em lote com MutateBatchJob retorna um erro ResourceCountLimitExceededError.RESOURCE_LIMIT (com ResourceLimitType.BATCH_JOBS_PER_CUSTOMER em ErrorDetails.resource_count_details).

  • Os jobs pendentes com mais de 7 dias são removidos automaticamente.

  • Cada AddBatchJobOperationsRequest tem um limite rígido de 10.000 operações de mutação por solicitação. Exceder 10.000 operações em uma única solicitação retorna um erro BatchJobError.REQUEST_TOO_LARGE.

  • Para o campo page_size em ListBatchJobResultsRequest:

  • Cada AddBatchJobOperationsRequest tem um tamanho máximo de 41.937.920 bytes. Se você exceder esse limite, vai receber um erro BatchJobError.REQUEST_TOO_LARGE (ou um INTERNAL_ERROR se for rejeitado na camada de transporte). É possível determinar o tamanho serializado da solicitação antes de enviá-la e tomar as medidas apropriadas se ela for muito grande:

    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()

    Ruby

    
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));

Tamanho de uma única operação de mutação

Embora a solicitação geral possa ter até 41.937.920 bytes, o tamanho serializado de um único MutateOperation no lote é limitado a 10.484.504 bytes (10 MiB menos 1.256 bytes). Exceder esse limite retorna um erro BatchJobError.REQUEST_TOO_LARGE. Embora a documentação de referência de BatchJobError.REQUEST_TOO_LARGE cite o limite de 10.484.504 bytes, AddBatchJobOperations retorna esse mesmo código de erro quando qualquer um dos três limites de solicitação (41.937.920 bytes de solicitação total, 10.484.504 bytes de operação única ou 10.000 operações por chamada) é excedido, com o campo message do erro especificando qual limite foi violado.

Anterior
Filtros de grupo de produtos anunciados