Usar filtros de grupo de produtos anunciados em jobs em lote

Ao trabalhar com filtros do grupo de produtos anunciados no contexto de um AdGroupCriterion.listing_group ou de um AssetGroupListingGroupFilter, leve em consideração as seguintes informações ao projetar sua integração.

Divisão em lote

Importante: recomendamos adicionar operações AssetGroupListingGroupFilterOperation (create, update e remove) que segmentam o mesmo AssetGroup e operações AdGroupCriterionOperation (create, update e remove) para critérios LISTING_GROUP (AdGroupCriterion.listing_group) que segmentam o mesmo AdGroup a um job em lote consecutivamente, para que o conjunto de operações seja tratado de forma atômica durante a divisão do 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 do 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 sublotes é determinada pelos seguintes fatores:

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

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

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

Observação : se você também estiver criando o AssetGroup no mesmo job em lote, coloque todas as operações de pré-requisito AssetOperation (create) para novos recursos Asset antes de AssetGroupOperation (create), seguidas imediatamente pelas operações AssetGroupAssetOperation (create) (que são executadas juntas em um sublote atômico anterior) e, em seguida, as operações consecutivas AssetGroupListingGroupFilterOperation (que são executadas no próximo sublote atômico). Como eles formam dois sublotes separados, uma falha no sublote AssetGroupListingGroupFilterOperation reverte os filtros do grupo de produtos anunciados sem reverter os recursos AssetGroup e AssetGroupAsset recém-criados.

Termo-chave: consecutivo se refere à ordem das operações no job em lote. Se as operações que segmentam o mesmo AdGroup ou AssetGroup forem intercaladas com operações que segmentam um grupo diferente, elas serão divididas em sublotes separados e não serão mais processadas como uma única transação atômica.

O diagrama a seguir ilustra esse conceito. Cada uma das caixas cinzas representa um job em lote enviado usando a API Google Ads. Nas caixas cinzas, as operações individuais são agrupadas por cor para representar os sublotes que o servidor de 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 grupos de produtos anunciados no contexto de jobs em lote, as seguintes limitações se aplicam:

• Um único sublote atômico de operações AdGroupCriterionOperation consecutivas (create, update e remove) para critérios 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 é limitado a 10.000 operações, um sublote AdGroup de 10.001 a 20.000 operações precisa ser enviado em pelo menos duas solicitações AddBatchJobOperations consecutivas.
• Um único sublote atômico de operações AssetGroupListingGroupFilterOperation consecutivas (create, update e remove) que segmentam o mesmo AssetGroup não pode exceder 10.000 operações.
• Violar qualquer um desses limites de contagem de operações (ou exceder o limite interno de tamanho de bytes serializados do servidor para um único sublote) cancela o job em lote nesse sublote: todos os sublotes anteriores que já foram concluídos permanecem confirmados, enquanto todas as operações no sublote ofensivo e em todos os sublotes subsequentes falham com InternalError.INTERNAL_ERROR.

Solução de problemas

As operações de filtro do 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 com erro. Além disso, devido à forma como as operações 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 anunciados AdGroupCriterionOperation, é possível que operações consecutivas segmentando o mesmo AdGroup falhem 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 AssetGroupListingGroupFilterOperation, é possível que operações consecutivas que segmentam o mesmo AssetGroup falhem 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 sublote atômico falhou. Para identificar a causa raiz do problema, itere as 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.