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

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

1. Tipo de filtro de 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) direcionadas ao mesmo AssetGroup são agrupadas em um sublote atômico (sem comportamento de falha parcial).
• Todas as operações consecutivas AdGroupCriterionOperation (create, update, e remove) para LISTING_GROUP critérios (AdGroupCriterion.listing_group) direcionadas ao 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 as operações AssetOperation (create) de pré-requisito para novos recursos Asset antes do 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 elas formam dois sublotes separados, uma falha no AssetGroupListingGroupFilterOperation sublote reverte os filtros de grupo de produtos anunciados sem reverter os recursos AssetGroup e AssetGroupAsset recém-criados.

Termo principal: consecutivo se refere à ordem das operações no job em lote. Se as operações direcionadas ao mesmo AdGroup ou AssetGroup forem intercaladas com operações direcionadas a 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. Dentro das caixas cinzas, as operações individuais são agrupadas por cor para representar os sublotes 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 foram 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 LISTING_GROUP critérios (AdGroupCriterion.listing_group) direcionados ao 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 consecutivas AddBatchJobOperations.
• Um único sublote atômico de operações consecutivas 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 exceder o limite de tamanho de byte serializado interno do servidor para um único sublote) interrompe 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 todos os sublotes subsequentes 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 errôneas. Além disso, devido à forma como as BatchJob operações 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, você pode descobrir que operações consecutivas direcionadas ao 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 AssetGroupListingGroupFilterOperation operações, você pode descobrir que operações consecutivas direcionadas ao 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 sublote atômico falhou. Para identificar a causa raiz do problema, itere pelas status mensagens em cada BatchJobResult—antes e depois do operation_index do erro de transação—para operações que compartilham o mesmo AdGroup ou AssetGroup ID.