Loop over items n8n

Loop over items в n8n: Полное руководство по обработке коллекций данных

Loop over items (цикл по элементам) в n8n — это фундаментальная концепция, позволяющая автоматизировать обработку массивов, списков или любых других коллекций данных. В отличие от последовательного выполнения операций, циклы выполняют одну и ту же логику для каждого элемента входного массива, что является основой для массовой обработки информации. В n8n реализация циклов тесно связана с концепцией выполнения узлов (node execution) и может осуществляться несколькими способами, каждый из которых имеет свои особенности, преимущества и сценарии применения.

Основные методы организации циклов в n8n

n8n предоставляет три основных подхода для итерации по элементам: встроенная функциональность узлов, специализированные узлы-циклы и режим выполнения рабочего процесса (execution mode). Выбор метода зависит от структуры данных, требований к производительности и сложности обрабатываемой логики.

1. Встроенная цикличность узлов (Internal Node Looping)

Многие узлы в n8n имеют встроенную возможность обработки массивов. Когда узел получает на входе поле, содержащее массив (список) элементов, он может автоматически обработать каждый элемент по отдельности. Это наиболее простой и эффективный способ, не требующий добавления специальных узлов.

Принцип работы: Если узел настроен на операцию, которая по своей природе может быть применена к множеству объектов (например, создание записей, отправка писем, обновление строк в БД), и на вход поступает массив, узел выполнит свою операцию для каждого элемента массива в рамках одного запуска.

Пример: Узел «Google Sheets» с операцией «Append». Если на его вход пришел массив из 10 объектов, каждый из которых представляет строку с данными, узел добавит все 10 строк в таблицу одним выполнением, но внутренне проитерировавшись по массиву.

Как идентифицировать: В настройках узла (параметрах) часто присутствует опция «Fields» или «Properties», где можно использовать выражение для доступа к элементу массива (например, {{ $json.item }}). Если узел поддерживает встроенную цикличность, он будет ожидать массив на входе.

2. Специализированные узлы для циклов (Loop Nodes)

Для реализации более сложной и контролируемой логики итераций в n8n существуют отдельные узлы в категории «Flow». Они позволяют явно задать условия и структуру цикла.

Название узла	Назначение и принцип работы	Ключевые параметры	Сценарий использования
For Each	Базовый узел для итерации по элементам входного массива. Создает отдельный запуск для каждого элемента, передавая его в подключенные после него узлы.	Source Data: Определение пути к массиву (например, {{ $json.items }}). Output Format: Формат выходных данных (отдельные элементы или собранный массив). Max Iterations: Ограничение на количество итераций.	Последовательная обработка списка email для рассылки, обход страниц пагинации API, применение сложных преобразований к каждому элементу списка.
While	Выполняет подключенные узлы до тех пор, пока заданное условие истинно (true). Условие оценивается перед каждой итерацией.	Condition: Выражение, возвращающее boolean. Например, {{ $json.pageNumber <= $json.totalPages }}. Max Iterations: Критически важный параметр для предотвращения бесконечного цикла.	Постраничный сбор данных (пагинация) до исчерпания страниц, опрос системы до получения определенного статуса, выполнение до достижения целевого значения.
Do While	Аналогичен узлу While, но условие проверяется после выполнения итерации. Это гарантирует, что тело цикла выполнится как минимум один раз.	Аналогично узлу While (Condition, Max Iterations).	Задачи, где первая операция должна быть выполнена обязательно перед проверкой условия (например, создание отчета и последующая проверка его размера).
Merge	Не является циклом в чистом виде, но часто завершает цепочку For Each, собирая результаты всех итераций обратно в единый массив для дальнейшей обработки.	Operation: Режим слияния (Aggregate, Append, Remove Duplicates и др.). Combine Mode: Определяет, как объединять данные (например, «Merge By Index»).	Объединение данных, полученных в разных итерациях цикла For Each, в один пакет для записи в базу данных или отправки в другую систему.

3. Режим выполнения рабочего процесса (Execution Mode)

Это настройка всего рабочего процесса (workflow), которая определяет, как n8n будет обрабатывать входные данные первого узла. Доступна в настройках триггера или при ручном запуске.

• Run Once for All Items: Стандартный режим. Весь рабочий процесс запускается один раз, получая все входные данные как один пакет (массив). Последующие узлы могут использовать встроенную цикличность.
• Run Once for Each Item: Ключевой режим для циклов. n8n автоматически запускает весь рабочий процесс отдельно для каждого элемента во входном массиве первого узла. Каждая итерация полностью изолирована.

Сравнение режимов:

Критерий	Run Once for All Items	Run Once for Each Item
Количество запусков workflow	Один	По одному на каждый элемент входного массива
Изоляция данных	Нет. Все данные доступны в одном контексте.	Полная. Каждая итерация видит только свой элемент.
Ошибка в итерации	Может остановить весь процесс.	Останавливает только конкретную итерацию, остальные выполняются.
Использование памяти	Может быть высоким при больших массивах.	Контролируемое, обрабатывается по одному элементу.
Производительность	Выше для быстрых операций над массивом.	Может быть ниже из-за накладных расходов на множество запусков.

Практические примеры реализации

Пример 1: Обработка заказов с использованием For Each и Merge

Цель: Получить список новых заказов из Shopify, для каждого заказа рассчитать стоимость доставки через API перевозчика, и обновить информацию в Shopify.

1. Узел Shopify (Trigger): Получает массив новых заказов.
2. Узел For Each: Итерируется по массиву заказов. Внутри цикла:
   • Узел HTTP Request: Отправляет данные по заказу (вес, адрес) в API службы доставки. Использует выражение {{ $json.items[0].json.order_id }} для доступа к данным текущей итерации.
   • Узел Set: Формирует объект с рассчитанной стоимостью.
3. Узел Merge (Aggregate): Собирает все объекты с расчетами из каждой итерации в единый массив.
4. Узел Shopify (Update): Использует встроенную цикличность, принимает массив от Merge, и обновляет каждый заказ.

Пример 2: Постраничный сбор данных с использованием While

Цель: Собрать все товары из REST API, которое возвращает данные постранично.

1. Узел Set: Инициализирует переменные: page = 1, allProducts = [].
2. Узел While: Условие {{ $json.page <= $json.totalPages }}. Внутри цикла:
   • Узел HTTP Request: Запрашивает API с параметром ?page={{ $json.page }}.
   • Узел Set: Добавляет полученные товары в массив allProducts и увеличивает page на 1. Параметр totalPages извлекается из ответа API.
3. После выхода из цикла массив allProducts содержит все товары со всех страниц.

Ключевые аспекты и лучшие практики

Управление потоком данных в цикле

Понимание структуры данных внутри цикла критически важно. Внутри узла For Each данные текущей итерации доступны по пути, например, {{ $json.item }}. Если используется режим «Run Once for Each Item», данные элемента доступны напрямую в корне {{ $json }}. Для доступа к данным из предыдущих узлов вне текущей итерации используются переменные (например, {{ $node["Название узла"].json }}).

Обработка ошибок

Циклы увеличивают риск возникновения ошибок. Рекомендуется:

• Всегда устанавливать Max Iterations в узлах While/Do While.
• Использовать узел Split In Batches для обработки очень больших массивов частями.
• Настраивать политику повторных попыток (Retry) на узлах внутри цикла для обработки временных сетевых сбоев.
• Рассмотреть использование режима «Run Once for Each Item» для лучшей изоляции ошибок.

Производительность

• Встроенная цикличность узлов обычно самая быстрая.
• For Each создает отдельные задачи выполнения, что может быть ресурсоемко для тысяч элементов.
• While может быть эффективен для постраничных запросов.
• Для обработки огромных наборов данных используйте пагинацию на стороне источника, Split In Batches или активируйте флажок «Keep Source Data» в For Each для работы с подмножествами данных.

Ответы на часто задаваемые вопросы (FAQ)

В чем основное различие между For Each и режимом «Run Once for Each Item»?

Узел For Each — это часть потока внутри одного выполнения рабочего процесса. Он итерируется по массиву и выполняет подключенные после него узлы для каждого элемента. Режим «Run Once for Each Item» — это свойство всего рабочего процесса. n8n запускает весь workflow с начала до конца отдельно для каждого элемента входного массива первого узла. For Each дает больше контроля внутри потока, а режим выполнения обеспечивает полную изоляцию итераций.

Как получить на выходе цикла For Each единый массив со всеми результатами?

Необходимо подключить после узла For Each узел Merge. В настройках For Each установите «Output Format» в значение «Single Item (Append)» или оставьте «Separate Items», а в узле Merge выберите операцию «Aggregate» или «Append». Узел Merge соберет результаты всех итераций в один массив.

Как избежать бесконечного цикла при использовании узла While?

Всегда, без исключений, заполняйте параметр «Max Iterations» в настройках узла While. Установите разумный предел, например, 1000. Это гарантирует, что цикл остановится даже если логическое условие никогда не станет ложным.

Можно ли использовать несколько вложенных циклов For Each?

Да, это технически возможно. Вы можете подключить второй узел For Each внутри первого. Однако такая конструкция может быстро привести к проблемам с производительностью (количество итераций умножается). Тщательно оценивайте необходимость вложенных циклов и рассматривайте альтернативы, такие как предварительная обработка данных или использование функций в выражениях.

Как передать данные извне цикла внутрь итерации For Each?

Используйте выражение, ссылающееся на конкретный узел. Например, если данные находятся в узле с именем «Get Data», то внутри For Each к ним можно обратиться через {{ $node["Get Data"].json.someField }}. Также можно использовать узел Set перед циклом для сохранения данных в переменных.

Что делать, если API или узел внутри цикла возвращает ошибку для одного элемента?

При использовании стандартного For Each ошибка в одной итерации может остановить весь цикл. Чтобы продолжить обработку остальных элементов, можно:
1) Включить режим «Run Once for Each Item» для всего workflow — тогда каждая итерация независима.
2) Использовать узел «Error Trigger» или настроить политику «Continue on Fail» на конкретном узле внутри цикла (где это безопасно).
3) Реализовать дополнительную проверку данных (узлом IF) перед операцией, которая может вызвать ошибку.

Какой метод цикла наиболее эффективен для обработки 10 000 записей?

Для такого объема данных не рекомендуется использовать стандартный For Each на 10 000 отдельных выполнений. Вместо этого:
1) Проверьте, поддерживает ли целевой узел (например, база данных) пакетные операции (batch operations) — это самый эффективный способ.
2) Используйте узел Split In Batches для разбивки массива на части, например, по 500 элементов, и обрабатывайте каждый пакет за одну итерацию с помощью встроенной цикличности узла.
3) Если источник данных поддерживает пагинацию, используйте цикл While для постраничной загрузки и обработки.