N8n списки

N8n: Работа со списками и массивами данных

N8n — это инструмент автоматизации рабочих процессов (workflow automation), который оперирует данными, передаваемыми между узлами (нодами). Фундаментальной концепцией для обработки множественных элементов данных в n8n являются списки, или, в терминах JavaScript/JSON, массивы объектов. Понимание принципов работы со списками критически важно для создания эффективных, сложных и гибких автоматизаций.

Что такое список (массив) в контексте n8n

В n8n каждый узел принимает на вход и возвращает на выходе данные в формате JSON. Основная единица данных — это объект, представляющий собой набор пар «ключ-значение». Когда узел возвращает несколько таких объектов, они объединяются в массив. Этот массив и является списком. Например, узел «Google Sheets» при чтении диапазона строк возвращает список, где каждый элемент — объект, представляющий одну строку, а ключи объекта — это заголовки столбцов.

• Одиночный элемент: { "id": 1, "name": "Item A", "email": "a@test.com" }
• Список (массив) элементов: [ { "id": 1, "name": "Item A" }, { "id": 2, "name": "Item B" } ]

Списки могут быть вложенными, то есть значение ключа в объекте также может быть массивом или объектом.

Как n8n обрабатывает списки: Режимы выполнения

Поведение узлов при работе со списками определяется их режимом выполнения (Operation Mode). Это одна из ключевых настроек многих узлов в n8n.

Режим выполнения	Описание	Входные данные	Выходные данные	Использование
Run Once for All Items	Узел выполняется один раз, получая на вход весь список элементов. Узел сам решает, как обрабатывать массив.	Один входной элемент, содержащий массив данных (список).	Один или несколько элементов (часто также массив).	Операции с целым набором: фильтрация, сортировка, агрегация, отправка всего списка в одном HTTP-запросе.
Run Once for Each Item	Узел выполняется отдельно для каждого элемента входящего списка. N8n автоматически итерирует по элементам.	Список из N элементов.	Список из N элементов (или меньше, если некоторые выполнения завершились ошибкой). Каждое выполнение независимо.	Индивидуальные операции: отправка персонализированных писем, обновление отдельных записей в БД, обработка отдельных файлов.

Ключевые узлы для работы со списками

N8n предоставляет специализированные узлы в палитре «Core Nodes» для манипуляции списками и их преобразования.

1. Узел «Split Out» (Разделить)

Этот узел преобразует один элемент, содержащий массив, в несколько отдельных элементов. Он является переходом от режима «Run Once for All Items» к «Run Once for Each Item».

• Вход: Один элемент с полем, содержащим массив (например, items: [ {...}, {...} ]).
• Выход: Два отдельных элемента, каждый из которых представляет собой объект из исходного массива. Поле items исчезает, его данные «поднимаются» на верхний уровень.

2. Узел «Merge» (Объединить)

Выполняет обратную операцию — объединяет несколько элементов в один, содержащий массив. Существует несколько режимов слияния:

Режим слияния	Результат
Append (Добавить)	Объединяет несколько ветвей workflow в один список элементов. Элементы из каждого входа добавляются в общий массив.
Merge By Fields (Объединить по полям)	Аналогично операции JOIN в SQL. Объединяет два списка в один на основе совпадения значений в указанных ключевых полях.
Multiplex (Мультиплексирование)	Создает комбинации «каждый с каждым». Берет по одному элементу из каждого входа и создает отдельный выходной элемент для каждой возможной пары (тройки и т.д.).

3. Узел «Aggregate» (Агрегировать)

Позволяет выполнять операции агрегации над списком, аналогично GROUP BY в SQL.

• Группировка: Объединение элементов в группы по значению указанного поля (например, category).
• Операции: В каждой группе можно выполнить подсчет элементов, суммирование значений, нахождение минимума/максимума, конкатенацию строк и т.д.

4. Узел «Limit» (Ограничить)

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

5. Узел «Sort» (Сортировать)

Сортирует элементы списка по указанному полю в порядке возрастания или убывания. Поддерживает сортировку как по числовым, так и по текстовым полям.

6. Узел «Item Lists» (Преобразование списков)

Многофункциональный узел для различных операций:

• Summarize: Создает сводку списка (количество элементов, сумма, среднее значение выбранных полей).
• Remove Duplicates: Удаляет дубликаты элементов на основе сравнения значений указанных полей.
• Sort: Альтернатива узлу Sort.
• Split Out: Альтернатива узлу Split Out.

Доступ к данным внутри списков: Выражения и циклирование

Для ссылки на данные внутри элементов списка используются выражения n8n. Специальные переменные позволяют работать как с текущим элементом в цикле, так и со всем списком.

Переменная	Контекст	Описание	Пример выражения
$items	Любой узел	Массив всех элементов, полученных на вход узла. Полезен в режиме «Run Once for All Items».	{{ $items[0].json.email }} — email первого элемента.
$item или $json	Режим «Run Once for Each Item»	Объект, представляющий текущий элемент в цикле. $json — сокращение для доступа к полям текущего элемента.	{{ $item.json.name }} или {{ $json.name }} — поле name текущего элемента.
$index	Режим «Run Once for Each Item»	Порядковый номер (индекс) текущей итерации, начинается с 0.	{{ $index + 1 }} — получение порядкового номера, начиная с 1.
$input	Любой узел	Содержит данные со всех входов узла. $input.first() часто используется для получения массива элементов с первого входа.	{{ $input.first().json[0].id }} — id первого элемента с первого входа.

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

Паттерн 1: Обработка элементов из таблицы (например, Google Sheets)

1. Узел Google Sheets (режим «Read») → возвращает список строк.
2. Узел Split Out → преобразует список в отдельные элементы.
3. Далее workflow выполняется для каждого элемента: например, узел HTTP Request отправляет данные на другой сервис, узел Condition проверяет значения полей.

Паттерн 2: Обогащение данных из двух источников

1. Ветка A: Узел MySQL получает список заказов.
2. Ветка B: Узел HTTP Request получает список данных о клиентах из CRM.
3. Узел Merge (режим «Merge By Fields») объединяет два списка по полю customer_id. Результат: список заказов с добавленной информацией о клиентах.

Паттерн 3: Группировка и агрегация

1. Узел PostgreSQL получает детальные записи о продажах.
2. Узел Aggregate группирует записи по полю product_id и вычисляет сумму продаж (amount) и количество транзакций в каждой группе.
3. Результирующий список с агрегированными данными отправляется в отчет или в систему аналитики.

Оптимизация и обработка ошибок

При работе с большими списками в режиме «Run Once for Each Item» важно учитывать:

• Скорость выполнения: Использование параллельного выполнения (настройка «Max concurrent executions» в узле-триггере или в настройках workflow).
• Ограничения API: Необходимость добавления задержек (узел «Wait») между итерациями, чтобы не превысить лимиты запросов к внешнему API.
• Обработка ошибок: В настройках workflow можно задать поведение при ошибке в одной из итераций («Continue on Fail»). Ошибочные элементы могут быть перенаправлены в отдельную ветку для логирования или повторных попыток с помощью узла «IF».

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

Как преобразовать список в строку с разделителями?

Используйте узел «Item Lists» в режиме «Summarize» для агрегации, или в режиме «Run Once for Each Item» используйте выражение для конкатенации. Более гибкий способ — использовать узел «Code» (JavaScript) и метод массива join(): const output = items.map(item => item.json.value).join(', ');.

Почему узел выполняется только один раз, хотя я ожидаю цикл?

Проверьте режим выполнения узла. Если на вход узлу приходит список, но он настроен на режим «Run Once for All Items», он обработает список как единый объект. Чтобы запустить цикл, либо переключите узел в режим «Run Once for Each Item», либо поставьте перед ним узел «Split Out».

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

Есть несколько способов:

• Использовать узел «Item Lists» в режиме «Summarize».
• В выражении использовать длину массива: {{ $items.length }} (в контексте «Run Once for All Items»).
• В узле «Code»: items.length.

Как фильтровать элементы списка по условию?

Основной инструмент — узел «IF». После узла «Split Out» используйте «IF» для проверки условия и направляйте элементы по соответствующим веткам (true/false). Для более сложной фильтрации можно использовать узел «Code» (JavaScript) с методом filter().

Как создать список (массив) с нуля внутри n8n?

Используйте узел «Code» (JavaScript). В его редакторе можно определить и вернуть массив объектов:

const newArray = [
  { id: 1, task: "Task 1" },
  { id: 2, task: "Task 2" }
];
return newArray;

Этот массив далее будет обрабатываться следующими узлами как список.

Чем отличается $item от $json?

$item — это полный объект текущего элемента, который включает в себя помимо данных (json) также мета-информацию (binary, index и др.). $json — это сокращение, которое ссылается непосредственно на объект с данными текущего элемента ($item.json). В большинстве выражений для доступа к полям данных используется $json.field_name.

Как обработать только первые 10 элементов из большого списка?

Используйте узел «Limit». Установите параметр «Max Items» равным 10. Элементы, идущие после 10-го, не будут переданы на следующие узлы.

Можно ли работать со вложенными массивами?

Да. Для доступа к вложенному массиву используйте выражение, например, {{ $json.someArray[0].nestedField }}. Чтобы развернуть вложенный массив в отдельные элементы, может потребоваться каскад из узлов «Split Out».