Práticas recomendadas e limitações

Considere estas diretrizes ao usar o BatchJobService.

Melhorar a capacidade de processamento

  • É melhor ter menos jobs maiores do que muitos jobs menores.

  • Ordene as operações enviadas por upload por tipo (exceto as interdependentes, que precisam ser agrupadas consecutivamente em sublotes atômicos). Por exemplo, se seu trabalho contiver operações para adicionar campanhas padrão, grupos de anúncios e critérios de grupo de anúncios, ordene as operações no upload para que todas as operações de campanha sejam primeiro, 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.

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

Atomicidade na divisão em lotes

A API Google Ads divide as operações em um job em lote enviado em sub-lotes menores para processamento. Enquanto os subbatches padrão são executados com falha parcial ativada, os subbatches de determinadas operações interdependentes são processados atomicamente como uma única transação:

Para AssetGroup e subbatches de criação de campanhas Performance Max Campaign (até 1.000 operações no total por subbatch; todas as operações filhas create além de 999 são transferidas para o próximo subbatch não atômico):

  • A operação create principal (resource_name em AssetGroup ou Campaign) e as operações create filhas consecutivas (asset_group em AssetGroupAsset ou campaign em CampaignAsset) precisam especificar o mesmo ID temporário negativo.
  • Coloque as operações de AssetOperation (create) de pré-requisito para novos recursos Asset antes do AssetGroupOperation ou CampaignOperation (create) principal, nunca entre o create principal e as operações de link filho create, que fechariam imediatamente o subgrupo atômico e separariam a criação do recurso principal dos recursos vinculados.

Quando um sub-lote atômico falha, o BatchJobResult.status da operação com falha contém o erro de validação subjacente, enquanto as operações restantes nesse sub-lote são revertidas com o erro de transação correspondente. Inspecione as entradas BatchJobResult adjacentes que compartilham o mesmo ID de 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 subbatches separadas, fazendo com que a modificação não atenda aos requisitos mínimos de recursos ou deixando as árvores de grupo de produtos anunciados incompletas. Consulte Usar filtros de 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 por produto (AssetGroupListingGroupFilterOperation em campanhas Performance Max ou AdGroupCriterionOperation em campanhas do Shopping) ou criar um novo AssetGroup ou Performance Max Campaign, agrupe todas as operações que segmentam o mesmo recurso principal (AssetGroup, AdGroup ou Campaign) consecutivamente. Isso reduz a disputa de bloqueio de back-end e mantém juntas as árvores interdependentes.

Consistência de dados

Como as árvores de filtro de grupo de produtos anunciados e os requisitos de recursos das campanhas Performance Max são validados no final de cada transação de sub-lote atômica, evite dividir atualizações para o mesmo recurso principal 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 tamanhos grandes de jobs. Muitos jobs não concluídos com o status RUNNING que tentam mudar o mesmo conjunto de objetos podem levar a condições semelhantes a deadlock, resultando em lentidão grave e até mesmo falhas de job.

  • Não envie várias operações que mudam 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 para não atingir erros de limitação de taxa.

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

  • A ordem dos resultados é a mesma da ordem de upload.

Outras orientações de uso

  • É possível definir um limite máximo para a duração de um job em lote antes de ser cancelado. Ao criar um job em lote, defina o campo metadata.execution_limit_seconds como seu limite de tempo preferido, em segundos. Não há um 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 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 oferece suporte a 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 sete dias são removidos automaticamente.

  • Cada AddBatchJobOperationsRequest tem um limite fixo 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). Você pode determinar o tamanho serializado da solicitação antes de enviar e tomar as medidas adequadas 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 para BatchJobError.REQUEST_TOO_LARGE cite o limite de 10.484.504 bytes, AddBatchJobOperations retorna o mesmo código de erro quando qualquer um dos três limites de solicitação (41.937.920 bytes totais de solicitação, 10.484.504 bytes de operação única ou 10.000 operações por chamada) é excedido. O campo message do erro especifica qual limite foi violado.

Anterior
Filtros de grupo de produtos anunciados