n8n Loop Over Items : Batching et bouclage automatique

n8n traite généralement plusieurs enregistrements entièrement seul : un node reçoit une liste d'items, exécute sa logique pour chaque item individuellement et renvoie les résultats à nouveau sous forme de liste. Pour la plupart des workflows, tu n'as donc pas besoin de boucle explicite. Mais dès qu'un service externe n'autorise que peu de requêtes par seconde, qu'un node ne traite que le premier item, ou qu'une API paginée sans nombre de pages connu doit être interrogée, le traitement automatique ne suffit plus. C'est exactement pour cela qu'il existe dans n8n le node Loop Over Items, anciennement connu sous le nom de Split in Batches.

Dans cet article, nous te montrons comment fonctionne le bouclage automatique dans n8n, comment fonctionne en détail le node Loop Over Items et à quoi tu dois faire attention concernant la taille de batch et la performance, afin que tes workflows fonctionnent de manière stable et sans erreurs de limite de débit.

Comment n8n parcourt automatiquement les items

Selon la documentation officielle de n8n sur le bouclage , les nodes n8n acceptent en principe un nombre quelconque d'items, les traitent et renvoient à nouveau les résultats. Si tu connectes par exemple un node de stockage de données avec cinq enregistrements clients à un node Slack, n8n envoie automatiquement cinq messages individuels, un par enregistrement. Tu n'as pas besoin de construire ta propre boucle pour cela, c'est le moteur qui s'en charge en arrière-plan.

Si tu veux au contraire ne traiter que le premier item d'un enregistrement entrant, tu actives l'option Execute Once dans les paramètres du node, sous l'onglet Settings. Le node ignore alors tous les autres items et ne traite que le premier enregistrement, ce qui convient par exemple pour des notifications ponctuelles.

Le node Loop Over Items en détail

Pour tous les cas où le traitement automatique ne suffit pas, n8n propose le node Loop Over Items . Le node enregistre les données d'entrée d'origine et renvoie à chaque passage un nombre fixe d'items via la sortie loop . Une fois tous les batches traités, il combine les données traitées et les renvoie via la sortie done .

Deux paramètres sont ici centraux :

• Batch Size : définit combien d'items le node renvoie par passage. Si tu mets la valeur à 1, n8n traite chaque item individuellement, l'un après l'autre.
• Reset : réinitialise le node à chaque passage avec des données d'entrée fraîches. C'est utile pour les requêtes API paginées où tu ne connais pas à l'avance le nombre total de pages. Important selon la documentation : si Reset est activé, tu dois absolument prévoir une condition d'arrêt valide, sinon la boucle tourne indéfiniment.

En pratique, tu utilises pour cela des expressions telles que `{{$("Loop Over Items").context["noItemsLeft"]}}`, pour vérifier s'il reste des items, ou `{{$("Loop Over Items").context["currentRunIndex"]}}`, pour lire l'index du passage actuel et l'utiliser comme condition d'arrêt dans un node IF.

Quand tu dois boucler manuellement

Selon la documentation, certains nodes ne traitent en principe que le premier item ou tous les items en une fois, au lieu d'itérer proprement. Cela concerne entre autres CrateDB, Microsoft SQL, MongoDB et TimescaleDB pour les opérations d'insertion et de mise à jour, le node Code ainsi que le node Execute Workflow en mode "Run Once for All Items", le node HTTP Request en cas de pagination manuelle, l'opération Redis Info et le node RSS Read. Pour ces exceptions, tu construis la boucle manuellement : tu reconnectes la sortie d'un node à un node précédent et tu ajoutes un node IF qui vérifie une condition d'arrêt claire.

Taille de batch et performance en pratique

La taille de batch détermine directement la stabilité et la rapidité d'exécution d'un workflow. Une petite taille de batch, par exemple 1 à 5 items par passage, ménage les API externes aux limites de débit strictes, mais allonge la durée totale d'exécution, car n8n doit traiter davantage de passages individuels. Une grande taille de batch accélère le workflow, mais augmente le risque qu'un service réponde avec une erreur 429 ou que le workflow soit plus difficile à suivre en cas d'erreur au milieu d'un grand batch. En pratique, il est préférable de tester avec une taille de batch modérée et d'observer les temps d'exécution ainsi que d'éventuelles réponses d'erreur du service cible, avant d'augmenter encore la valeur.

Surtout pour les workflows en production avec de nombreux appels externes, il vaut la peine de combiner Loop Over Items spécifiquement avec des temps d'attente entre les batches, afin que les API ne soient pas surchargées et que tu gardes le contrôle sur l'exécution. Si tu veux non seulement construire tes workflows n8n, mais aussi les exploiter durablement de manière stable, nous t'accompagnons chez NordFlux dans le cadre de notre automatisation n8n précisément sur ces questions de performance et de limite de débit, afin que tes collaborateurs numériques fonctionnent de manière fiable.

Questions fréquentes

Quelle est la différence entre le bouclage automatique et le node Loop Over Items ?

Le bouclage automatique se produit de lui-même pour presque chaque node n8n : le node traite chaque item entrant individuellement et transmet la liste de résultats, sans que tu aies besoin de configurer quoi que ce soit pour cela. Le node Loop Over Items entre en jeu uniquement lorsque tu veux répartir explicitement le traitement en portions contrôlées, par exemple pour respecter des limites de débit ou pour servir des nodes qui ne peuvent traiter qu'un seul item à la fois.

Comment éviter une boucle infinie avec le node Loop Over Items ?

Une boucle infinie survient généralement lorsque l'option Reset est activée, mais qu'aucune condition d'arrêt n'est vérifiée. Dans ce cas, ajoute un node IF qui évalue par exemple l'expression `{{$("Loop Over Items").context["noItemsLeft"]}}`, et dirige le workflow vers la branche done une fois la fin atteinte, au lieu de revenir dans la boucle.

Quelle taille de batch dois-je choisir pour les requêtes API ?

Il n'existe pas de chiffre universel, car chaque service a ses propres limites de débit. Comme point de départ, des valeurs faibles entre 1 et 10 items par batch conviennent, que tu ajustes ensuite progressivement en fonction des temps de réponse réels et d'éventuels messages d'erreur du service cible.

Dois-je construire une boucle moi-même pour chaque node ?

Non, la plupart des nodes n8n traitent plusieurs items automatiquement sans configuration supplémentaire. Ce n'est que pour un nombre limité de nodes exceptionnels, par exemple certains nodes de base de données ou le node HTTP Request en cas de pagination manuelle, que tu dois construire la boucle toi-même avec le node Loop Over Items ou un node IF reconnecté en arrière.

Puis-je accéder aux données des passages précédents à l'intérieur d'une boucle ?

Oui, via les propriétés context du node Loop Over Items, comme currentRunIndex, tu peux identifier le passage actuel, et via des références à des nodes antérieurs dans le workflow, il est également possible d'intégrer des données provenant d'étapes précédentes. Pour un stockage intermédiaire plus complexe sur plusieurs passages, un node Set ou Code supplémentaire qui collecte les résultats intermédiaires est recommandé.