Usar filtros de grupo de produtos anunciados em jobs em lote

Ao trabalhar com filtros de grupo de produtos anunciados no contexto de um AdGroupCriterion.listing_group ou um AssetGroupListingGroupFilter, considere o seguinte ao criar sua integração.

Divisão em lote

Se houver operações em um job em lote que contenham critérios de grupo de anúncios ou filtros de grupo de produtos anunciados de grupo de recursos, as operações no job em lote serão divididas em vários sublotes quando recebidas pelo servidor da API Google Ads. Ao contrário das operações padrão em um job em lote, cada sublote que contém operações de filtro de grupo de produtos anunciados é tratado de forma atômica.

A maneira como os jobs em lote que contêm filtros de grupo de produtos anunciados são divididos em sub-lotes é determinada pelos seguintes fatores:

1. Tipo de filtro do grupo de produtos anunciados
2. O AdGroup ou AssetGroup que o filtro de grupo de produtos anunciados está segmentando
3. Ordem de operações

Considere como as operações são agrupadas:

• Todas as operações consecutivas AssetGroupListingGroupFilterOperation (create, update e remove) que têm como destino o mesmo AssetGroup são agrupadas em um sub-lote atômico (sem comportamento de falha parcial).
• Todas as operações consecutivas de AdGroupCriterionOperation (create, update e remove) para critérios de LISTING_GROUP (AdGroupCriterion.listing_group) que segmentam o mesmo AdGroup são agrupadas em um sub-lote atômico (sem comportamento de falha parcial).
• Todas as outras operações consecutivas são agrupadas em sub-lotes não atômicos (comportamento de falha parcial).

O diagrama a seguir ilustra esse conceito. Cada uma das caixas cinzas representa um job em lote enviado usando a API Google Ads. Dentro das caixas cinzas, as operações individuais são agrupadas por cor para representar os subbatches que o servidor da API Google Ads cria. A ordem das operações em cada uma das caixas cinzas corresponde à ordem em que as operações teriam sido adicionadas ao job em lote.

Limitações

Ao trabalhar com filtros de grupo de produtos anunciados no contexto de jobs em lote, as seguintes limitações se aplicam:

• Um único sublote atômico de operações consecutivas AdGroupCriterionOperation (create, update e remove) para critérios de LISTING_GROUP (AdGroupCriterion.listing_group) que segmentam o mesmo AdGroup não pode exceder 20.000 operações de comprimento. No entanto, recomendamos não exceder 10.000 operações. Como cada AddBatchJobOperationsRequest tem um limite de 10.000 operações, um sublote AdGroup de 10.001 a 20.000 operações precisa ser enviado em pelo menos dois pedidos AddBatchJobOperations consecutivos.
• Um único sub-lote atômico de operações consecutivas de AssetGroupListingGroupFilterOperation (create, update e remove) direcionadas ao mesmo AssetGroup não pode exceder 10.000 operações.
• A violação de qualquer um desses limites de contagem de operações (ou o excesso do limite interno de tamanho de bytes serializados do servidor para um único sub-lote) interrompe o job em lote naquele sub-lote: todos os sub-lotes anteriores que já foram concluídos permanecem confirmados, enquanto todas as operações no sub-lote ofensivo e em qualquer sub-lote subsequente falham com InternalError.INTERNAL_ERROR.

Solução de problemas

As operações de filtro de grupo de produtos anunciados em um job em lote são processadas como uma transação, o que pode levar a cenários em que muitas operações falham devido a um pequeno número de operações incorretas. Além disso, devido à forma como as operações do BatchJob são processadas, a causa raiz das falhas pode aparecer em um índice antes ou depois das falhas downstream.

Por exemplo, ao processar uma resposta de ListBatchJobResults:

• Para grupos de produtos AdGroupCriterionOperation, talvez você perceba que operações consecutivas segmentando o mesmo AdGroup falharam com CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION (Product group operations are atomic within the same ad group. This operation failed because another operation targeting the same ad group ID was invalid.).
• Para operações de AssetGroupListingGroupFilterOperation, talvez você descubra que operações consecutivas que têm como destino o mesmo AssetGroup falharam com BatchJobError.ASSET_GROUP_LISTING_GROUP_FILTER_TRANSACTION_FAILURE.

Esses erros indicam que a operação nesse índice foi revertida porque outra operação no mesmo subgrupo atômico falhou. Para identificar a causa raiz do problema, itere pelas mensagens status em cada BatchJobResult (antes e depois do operation_index do erro de transação) para operações que compartilham o mesmo ID AdGroup ou AssetGroup.