Utiliser des filtres de groupes de fiches dans les jobs par lot

Lorsque vous utilisez des filtres de groupe de fiches dans le contexte d'un AdGroupCriterion.listing_group ou d'un AssetGroupListingGroupFilter, tenez compte des points suivants lors de la conception de votre intégration.

Répartition par lot

Important : Nous vous recommandons d'ajouter des opérations AssetGroupListingGroupFilterOperation (create, update et remove) ciblant le même AssetGroup, et des opérations AdGroupCriterionOperation (create, update et remove) pour les critères LISTING_GROUP (AdGroupCriterion.listing_group) ciblant le même AdGroup, à un job par lot consécutivement, afin que l'ensemble des opérations soit traité de manière atomique lors de la division du lot.

Si un job par lot contient des opérations qui incluent des critères de groupe d'annonces ou des filtres de groupe de fiches de groupe de composants, les opérations du job par lot sont divisées en plusieurs sous-lots lorsqu'elles sont reçues par le serveur d'API Google Ads. Contrairement aux opérations standards d'un job par lot, chaque sous-lot contenant des opérations de filtrage de groupes de fiches est traité de manière atomique.

La manière dont les jobs par lot contenant des filtres de groupes de fiches sont divisés en sous-lots est déterminée par les facteurs suivants :

1. Type de filtre de groupe de fiches
2. AdGroup ou AssetGroup ciblé par le filtre de groupe de fiches
3. Ordre de priorité des opérations

Réfléchissez à la façon dont les opérations sont regroupées :

• Toutes les opérations AssetGroupListingGroupFilterOperation consécutives (create, update et remove) ciblant le même AssetGroup sont regroupées dans un sous-lot atomique (aucun comportement d'échec partiel).
• Toutes les opérations AdGroupCriterionOperation consécutives (create, update et remove) pour les critères LISTING_GROUP (AdGroupCriterion.listing_group) ciblant le même AdGroup sont regroupées dans un sous-lot atomique (aucun comportement d'échec partiel).
• Toutes les autres opérations consécutives sont regroupées dans des sous-lots non atomiques (comportement d'échec partiel).

Remarque : Si vous créez également AssetGroup dans le même job par lot, placez toutes les opérations AssetOperation (create) préalables pour les nouvelles ressources Asset avant AssetGroupOperation (create), suivies immédiatement de ses opérations AssetGroupAssetOperation (create) (qui s'exécutent ensemble dans un sous-lot atomique précédent), puis des opérations AssetGroupListingGroupFilterOperation consécutives (qui s'exécutent dans le sous-lot atomique suivant). Comme ces opérations forment deux sous-lots distincts, un échec dans le sous-lot AssetGroupListingGroupFilterOperation entraîne l'annulation des filtres de groupe de fiches, mais pas des ressources AssetGroup et AssetGroupAsset nouvellement créées.

Terme clé : Consécutif fait référence à l'ordre des opérations dans le job par lot. Si des opérations ciblant le même AdGroup ou AssetGroup sont entrelacées avec des opérations ciblant un autre groupe, elles sont divisées en sous-lots distincts et ne sont plus traitées comme une seule transaction atomique.

Le schéma suivant illustre ce concept. Chaque zone grise représente un job par lot envoyé à l'aide de l'API Google Ads. Dans les cases grises, les opérations individuelles sont regroupées par couleur pour représenter les sous-lots créés par le serveur de l'API Google Ads. L'ordre des opérations dans chacune des zones grises correspond à l'ordre dans lequel les opérations auraient été ajoutées au job par lot.

Limites

Lorsque vous utilisez des filtres de groupe de fiches dans le contexte de jobs par lot, les limites suivantes s'appliquent :

• Un seul sous-lot atomique d'opérations AdGroupCriterionOperation consécutives (create, update et remove) pour les critères LISTING_GROUP (AdGroupCriterion.listing_group) ciblant le même AdGroup ne peut pas dépasser 20 000 opérations. Toutefois, il est recommandé de ne pas dépasser 10 000 opérations. Étant donné que chaque AddBatchJobOperationsRequest est limité à 10 000 opérations, un sous-lot AdGroup de 10 001 à 20 000 opérations doit être importé sur au moins deux requêtes AddBatchJobOperations consécutives.
• Un seul sous-lot atomique d'opérations AssetGroupListingGroupFilterOperation consécutives (create, update et remove) ciblant le même AssetGroup ne peut pas dépasser 10 000 opérations.
• Le non-respect de l'une de ces limites de nombre d'opérations (ou le dépassement de la limite de taille d'octets sérialisés interne du serveur pour un seul sous-lot) entraîne l'abandon du job par lot au niveau de ce sous-lot : tous les sous-lots précédents déjà terminés restent validés, tandis que toutes les opérations du sous-lot incriminé et de tous les sous-lots suivants échouent avec InternalError.INTERNAL_ERROR.

Dépannage

Les opérations de filtrage des groupes de fiches dans un job par lot sont traitées comme une seule transaction, ce qui peut entraîner des scénarios dans lesquels de nombreuses opérations échouent en raison d'un petit nombre d'opérations erronées. De plus, en raison de la façon dont les opérations BatchJob sont traitées, la cause principale des échecs peut apparaître à un index avant ou après les échecs en aval.

Par exemple, lors du traitement d'une réponse de ListBatchJobResults :

• Pour les groupes de fiches AdGroupCriterionOperation, vous constaterez peut-être que des opérations consécutives ciblant le même AdGroup ont échoué avec l'erreur 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.).
• Pour les opérations AssetGroupListingGroupFilterOperation, vous constaterez peut-être que les opérations consécutives ciblant le même AssetGroup ont échoué avec BatchJobError.ASSET_GROUP_LISTING_GROUP_FILTER_TRANSACTION_FAILURE.

Ces erreurs indiquent que l'opération à cet index a été annulée, car une autre opération du même sous-lot atomique a échoué. Pour identifier l'origine du problème, parcourez les messages status de chaque BatchJobResult (avant et après l'operation_index de l'erreur de transaction) pour les opérations partageant le même ID AdGroup ou AssetGroup.