Как работает loop over items в n8n

Как работает Loop Over Items в n8n: Полное руководство по итерациям и обработке данных

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

Принцип работы и архитектура

Когда нода работает в режиме Loop Over Items, она ожидает на своем входе массив данных (список объектов). Этот массив может быть получен из предыдущей ноды, например, из ноды «HTTP Request», которая вернула список товаров, или из ноды «Extract from JSON», которая извлекла массив записей. Как только нода получает такой массив, она инициирует внутренний цикл.

Технически процесс можно разделить на следующие этапы:

Получение и парсинг входных данных: Нода проверяет входящие данные. Если на вход пришел не массив, а одиночный объект, n8n автоматически обернет его в массив, содержащий один элемент. Это обеспечивает обратную совместимость и устойчивость потока.
Активация режима итерации: В интерфейсе ноды активируется индикатор (обычно в виде циклической стрелки). Внутренний движок n8n начинает последовательный перебор элементов массива, начиная с индекса 0.
Изоляция контекста выполнения: Для каждой итерации (каждого элемента массива) создается изолированный контекст выполнения. В этом контексте элемент массива становится доступным как входные данные для ноды. Все выражения, ссылающиеся на `$json`, `$binary`, `$input` или `$node`, будут вычисляться относительно текущего элемента цикла.
Выполнение операции ноды: Нода выполняет свою основную функцию (например, делает HTTP-запрос, записывает в базу данных, преобразует данные) используя данные из текущего элемента массива.
Агрегация результатов: Результаты выполнения каждой итерации (выходные данные ноды для каждого элемента) собираются в новый массив. Порядок элементов в выходном массиве соответствует порядку обработки входного массива.
Передача результата дальше по потоку: Собранный массив результатов передается на выход ноды и становится входными данными для следующей ноды в рабочем процессе.

Настройка и конфигурация

Режим Loop Over Items включается на уровне отдельной ноды. Для его активации необходимо:

Выбрать нужную ноду в рабочем процессе.
Перейти в панель настроек ноды (клик на ноде -> «Execute once for each item»).
Активировать переключатель «Execute once for each item».

После активации становятся доступны дополнительные опции конфигурации:

Опция	Описание	Значение по умолчанию
Max Iterations	Максимальное количество итераций, которое будет выполнено. Ограничивает обработку массива, даже если в нем больше элементов. Полезно для тестирования или ограничения API-вызовов.	0 (без ограничений)
Output Format	Определяет формат выходных данных после завершения цикла.	Multiple Items (One per Input Item)
Concurrency	Количество параллельно выполняемых итераций. Позволяет ускорить обработку за счет параллелизма.	1 (последовательное выполнение)
Keep Source Data (Depends on node)	Определяет, будут ли исходные данные (входной массив) объединены с результатом операции ноды в выходных данных.	Зависит от типа ноды

Форматы выходных данных (Output Format)

Это критически важная настройка, определяющая структуру данных, которые нода передаст следующему узлу.

Формат	Структура вывода	Использование
Multiple Items (One per Input Item)	Массив, где каждый элемент — это результат соответствующей итерации. Например, `[ {result1}, {result2}, … ]`.	Стандартный вариант. Когда следующей ноде нужны все результаты для дальнейшей обработки или другого цикла.
Single Item (Merge All Input Items)	Все результаты итераций сливаются в один объект. Если результаты — объекты, они будут объединены (при конфликте ключей побеждает последнее значение).	Когда нужно собрать агрегированную статистику или создать один объект из множества записей.
Single Item (First Input Item)	На выход передается только результат первой итерации цикла. Остальные результаты игнорируются.	Для обработки только первого элемента массива или когда требуется семантика «найти первый подходящий».

Использование выражений внутри цикла

Внутри ноды, работающей в режиме Loop Over Items, выражения (Expressions) вычисляются в контексте текущего элемента. Это ключевой момент для динамической настройки операций.

Доступ к данным текущего элемента: Используйте выражение `{{ $json }}` для доступа ко всему объекту текущего элемента. Например, `{{ $json.product_id }}` вернет значение поля `product_id` из элемента, обрабатываемого в данной итерации.
Доступ к индексу итерации: Переменная `{{ $index }}` содержит текущий индекс (начиная с 0). Ее можно использовать для нумерации, условной логики или включения в запросы.
Доступ к данным из других нод: Можно получать данные из нод, которые были выполнены до начала цикла, используя синтаксис `{{ $node(‘NodeName’).item.json }}`. Важно: при таком обращении вы получите весь массив данных от той ноды, а не элемент, соответствующий текущей итерации. Для синхронизации по индексу может потребоваться использовать `{{ $node(‘NodeName’).item.json[$index] }}`.

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

При работе цикла ошибка в одной итерации может повлиять на весь процесс. По умолчанию, если ошибка возникает в середине обработки массива, цикл прерывается, и нода завершается с ошибкой. Уже обработанные до ошибки итерации считаются выполненными, но их результаты не агрегируются в итоговый выход.

Для отладки используйте следующие методы:

Встроенный редактор выражений: Проверяйте выражения перед выполнением.
Нода «Debug» внутри цикла: Поместите ноду «Debug» после ноды с циклом, чтобы увидеть массив всех результатов. Поместите ноду «Debug» внутри ветки, которая обрабатывает каждый элемент (например, после ноды с циклом, но перед следующей нодой, которая также работает в режиме цикла), чтобы увидеть данные каждой итерации по отдельности.
Ограничение итераций (Max Iterations): Установите небольшое значение (например, 2-3) для тестового прогона потока.

Производительность и параллельное выполнение (Concurrency)

Установка параметра Concurrency больше 1 переводит цикл из последовательного режима в параллельный. Это кардинально увеличивает скорость обработки больших массивов, особенно при операциях, связанных с ожиданием (сетевые запросы, API-вызовы).

Важные ограничения и considerations:

Порядок вывода: n8n гарантирует, что порядок элементов в выходном массиве будет соответствовать порядку во входном массиве, даже если итерации завершаются в разное время из-за параллельного выполнения.
Ограничения API: Многие API имеют лимиты на количество одновременных запросов (Rate Limiting). Слишком высокий уровень параллелизма вызовет ошибки 429 (Too Many Requests). Рекомендуется начинать с низких значений (2-5).
Использование ресурсов: Высокий параллелизм увеличивает нагрузку на сервер n8n и потребление памяти.

Сравнение с другими методами итерации в n8n

Loop Over Items — не единственный способ организовать цикл в n8n. Понимание отличий критично для выбора правильного подхода.

Метод	Уровень	Как работает	Плюсы	Минусы
Loop Over Items (Execute once for each item)	Уровень ноды	Внутренний цикл в рамках одной ноды. Одна нода выполняется N раз.	Простота настройки, компактность workflow, встроенный контроль параллелизма.	Ограничен одной операцией за цикл. Сложная логика требует дополнительных нод внутри ветки.
Loop Trigger Node	Уровень workflow	Специальная нода-триггер, которая запускает весь workflow или его часть заданное количество раз или по массиву данных.	Может запускать сложные цепочки нод в каждой итерации. Полноценный цикл на уровне всего потока.	Более сложная архитектура. Нет встроенного параллелизма. Может создавать много экземпляров выполнения.
While Loop (Do Until) Node	Уровень ветки	Выполняет подключенные к ней ноды до тех пор, пока не будет выполнено заданное условие.	Идеален для циклов с неизвестным количеством итераций (опрос API, чтение до конца файла).	Риск бесконечного цикла при неправильном условии. Нет прямого параллелизма.

Практические примеры применения

Пример 1: Обновление товаров в магазине через API.

Нода «HTTP Request» (GET) получает список товаров, требующих обновления. Возвращает массив `[ {id: 1, price: 10}, {id: 2, price: 20} ]`.
Нода «HTTP Request» (PATCH) настраивается на вызов `PATCH /product/{{ $json.id }}` с телом `{ «price»: {{ $json.price
1.1 }} }`. Включается режим «Loop Over Items» с Concurrency=3.
Результат: для каждого товара будет отправлен отдельный PATCH-запрос с новым ценником, запросы выполнятся параллельно.

Пример 2: Создание задач в Trello из списка контактов.

Нода «Google Sheets» читает строки из таблицы. Каждая строка — контакт.
Нода «Trello: Create Card» настраивается с циклом. Название карточки: `{{ $json[‘Contact Name’] }} — Follow-up`. Описание формируется из других полей.
Результат: для каждой строки таблицы создается отдельная карточка в Trello.

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

В чем разница между Loop Over Items и Loop Trigger?

Loop Over Items — это функция конкретной ноды, позволяющая ей обработать массив входных данных. Loop Trigger — это отдельная нода-триггер, которая запускает новый экземпляр выполнения рабочего процесса (или его части) для каждого элемента. Loop Over Items работает внутри одного выполнения, Loop Trigger создает множество выполнений. Первый метод легче и быстрее для простых операций над массивом, второй — мощнее для сложных, многозадачных циклов.

Почему следующая нода получает пустой массив или только один элемент?

Наиболее вероятные причины:

Нода с циклом настроена на выходной формат «Single Item (First Input Item)». Проверьте настройку «Output Format».
Входные данные для ноды с циклом не являются массивом. Убедитесь, что предыдущая нода передает именно массив. Используйте ноду «Debug» для проверки структуры данных.
В цикле возникает ошибка, и выполнение прерывается. Проверьте Execution Log на наличие ошибок в итерациях.

Как обработать только часть элементов массива (фильтрация внутри цикла)?

Непосредственно внутри режима Loop Over Items нет встроенного условия фильтрации. Есть два подхода:

Использовать ноду «IF» или «Filter» перед нодой с циклом, чтобы отфильтровать массив и передать в цикл только нужные элементы.
Организовать ветвление внутри цикла, используя ноду «IF» после ноды с циклом. Но в этом случае цикл все равно выполнит итерацию для каждого элемента, а нода «IF» будет просто направлять данные по разным веткам. Это менее эффективно.

Можно ли использовать данные из двух разных массивов в одном цикле?

Да, но для этого нужно синхронизировать массивы по индексу. Предположим, у вас есть два массива одинаковой длины из разных нод: `ArrayA` и `ArrayB`. В ноде с циклом, который получает на вход `ArrayA`, вы можете обратиться к элементу из `ArrayB` по текущему индексу: `{{ $node(‘Node_B’).item.json[$index] }}`. Это сработает, если порядок элементов в массивах соответствует логике вашей задачи. Для сложных сопоставлений лучше сначала объединить данные в один массив с помощью ноды «Join» или «Merge».

Как остановить цикл досрочно при определенном условии?

В режиме Loop Over Items прямой команды «break» нет. Альтернативы:

Используйте настройку «Max Iterations» для ограничения количества шагов.
Обработайте и отфильтруйте массив перед циклом так, чтобы в него не попадали элементы, после которых нужно остановиться.
Для сложной логики прерывания используйте ноду «While Loop» (Do Until) или «Loop Trigger», где условие выхода можно задать гибко.

Влияет ли параллельное выполнение (Concurrency) на лимиты API?

Да, влияет напрямую. Параллельные запросы потребляют квоту API быстрее, чем последовательные. Если вы настроите Concurrency=10 и ваш API имеет лимит 100 запросов в минуту, вы можете исчерпать лимит за 10 секунд выполнения цикла на 100 элементов. Всегда учитывайте Rate Limiting API при настройке параллелизма. Рекомендуется добавлять ноду «Wait» или использовать функцию паузы в коде ноды, если это возможно, для соблюдения лимитов.