N8n items

N8n Items: Фундаментальная единица данных в автоматизации рабочих процессов

В экосистеме n8n, платформы для автоматизации рабочих процессов с открытым исходным кодом, понятие «Items» (элементы) является центральным и фундаментальным. Понимание структуры, поведения и методов работы с Items критически важно для создания эффективных, надежных и сложных автоматизаций. Items представляют собой основные единицы данных, которые передаются между узлами (нодами) в рабочем процессе (workflow). Каждый узел в n8n принимает на вход один или несколько Items, обрабатывает их и возвращает новые или модифицированные Items на выход для последующих узлов.

Что такое Item: Детальное определение

Item в n8n — это объект JavaScript в формате JSON (JavaScript Object Notation), который содержит полезные данные. По своей сути, это набор пар «ключ-значение», где ключ является строкой, а значение может быть строкой, числом, булевым значением, массивом, другим объектом или null. Когда рабочий процесс выполняется, он создает и обрабатывает поток таких Items. Каждый Item независим, но узлы могут обрабатывать несколько Items одновременно, что формирует массив Items. Именно этот массив передается по конвейеру рабочего процесса от одного узла к другому.

Важно различать два уровня данных в n8n:

Items (Элементы): Отдельные объекты данных (например, одна строка из таблицы, одно письмо, одна запись из CRM).
Item Array (Массив элементов): Коллекция, или список, Items, которая передается между узлами. Каждая связь (connection) между узлами несет именно один Item Array.

Структура и состав Item

Стандартный Item в n8n состоит из двух основных частей: полезных данных (json) и метаданных (внутренних полей n8n).

Полезные данные (json): Это ядро Item, содержащее информацию, полученную из внешнего сервиса (например, заголовок и тело письма из Gmail, название и стоимость товара из Shopify, текст задачи из Todoist). Эти данные определяются API подключенного сервиса и логикой узла.
Метаданные и внутренние поля: N8n добавляет к каждому Item служебную информацию для корректной работы платформы. Ключевые внутренние поля включают:
- _id: Уникальный идентификатор элемента в рамках текущего выполнения рабочего процесса.
- _name: Имя, часто соответствующее ключевому полю данных (например, subject для письма).
- _json: Ссылка на корневой объект JSON данных элемента.

Пример Item, полученного из узла «Google Sheets — Read»:

{
  "json": {
    "id": 1,
    "Name": "John Doe",
    "Email": "john@example.com",
    "OrderAmount": 150
  },
  "_id": "abc123",
  "_name": "John Doe"
}

Жизненный цикл Items в рабочем процессе

Жизненный цикл Items начинается в узле-триггере (например, «Schedule», «Webhook», «Email Trigger») или в узле, который извлекает данные из внешнего источника (например, «Google Sheets — Read», «MySQL — Select»). Далее Items проходят через последовательность узлов, где они могут быть:

Преобразованы: Изменены, обогащены новыми полями, отфильтрованы (узлы «Set», «Function», «IF»).
Разделены: Один Item может быть преобразован в несколько (узел «Split In Batches», «Item Lists»).
Объединены: Данные из нескольких Items или источников могут быть агрегированы (узлы «Merge», «Aggregate»).
Отправлены во внешние системы: Записаны в базу данных, отправлены по email, опубликованы в мессенджере (узлы «HTTP Request», «Email Send», «Telegram»).

На каждом этапе узел получает на вход Item Array, обрабатывает его согласно своей логике и возвращает новый Item Array на выход. Этот процесс продолжается до завершения рабочего процесса.

Ключевые узлы для работы с Items

N8n предоставляет богатый набор узлов для манипуляции Items. Их можно классифицировать по основным функциям.

Категория узла	Название узла	Назначение и влияние на Items
Трансформация данных	Set	Позволяет добавлять, устанавливать или удалять поля в каждом Item. Можно задавать статические значения, выражения или данные из других полей.
	Function	Предоставляет возможность писать пользовательский код на JavaScript для произвольных операций над Items (маппинг, фильтрация, сложные вычисления).
	Item Lists	Выполняет операции над массивом Items: сортировка, агрегация (сумма, среднее), ограничение количества, объединение в строку.
Управление потоком	IF	Разделяет поток Items на два или более направления на основе условий. Каждый Item проходит по ветке, условие которой истинно.
Управление потоком	Split In Batches	Разбивает входящий массив Items на несколько более мелких массивов (пакетов) для обработки с заданным интервалом, что полезно для соблюдения лимитов API.
Агрегация и слияние	Merge	Объединяет Items из двух или более входящих веток в один общий поток. Поддерживает несколько стратегий слияния: «добавить», «объединить по ключу», «многопарное слияние».
Агрегация и слияние	Aggregate	Группирует Items по заданным полям и вычисляет агрегатные функции (сумма, количество, минимальное/максимальное значение) для других полей, создавая новые сводные Items.
Фильтрация	Filter	Пропускает дальше только те Items, которые соответствуют заданным условиям. Остальные Items отбрасываются.

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

Для ссылки на значения внутри Items в настройках большинства узлов n8n использует систему выражений (expressions). Это позволяет динамически подставлять данные из предыдущих узлов.

Селектор данных (Data Selector): Визуальный инструмент, вызываемый кнопкой «Добавить выражение» ({{}}). Он отображает структуру данных, полученных от предыдущих узлов, позволяя выбрать нужное поле.
Синтаксис выражений: Вручную выражения пишутся с использованием двойных фигурных скобок. Внутри них используется путь к данным.
- {{ $json.OrderAmount }} — обращается к полю «OrderAmount» текущего Item.
- {{ $json["Name"] }} — альтернативный синтаксис.
- {{ $("node_name").item[0].json.Email }} — обращается к данным из конкретного узла по имени.
- {{ $input.first().json.Date }} — обращается к данным из первого входа.

Особые режимы обработки Items

N8n поддерживает несколько режимов выполнения, которые влияют на обработку Items:

Режим «Run Once for All Items»: Стандартный режим. Узел выполняется один раз, получая на вход весь массив Items. Большинство узлов работают в этом режиме.
Режим «Run Once for Each Item»: Узел выполняется отдельно для каждого Item во входящем массиве. Это характерно для узлов действий, таких как «HTTP Request» или «Email Send», когда нужно совершить отдельное действие для каждой записи.
Режим «Append»: В некоторых узлах-накопителях (например, «Spreadsheet File — Write») позволяет добавлять новые Items к существующим данным, а не перезаписывать их.

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

Пример 1: Обогащение данных из Google Sheets. Узел «Google Sheets — Read» извлекает список заказов (массив Items). Узел «Set» добавляет к каждому Item новое поле «Status» со значением «New». Узел «Function» вычисляет поле «Tax» как 20% от «OrderAmount». Результат — модифицированный массив Items с новыми полями.

Пример 2: Разделение и пакетная отправка. Узел «CRM — Get Contacts» возвращает 500 Items (контактов). Узел «Split In Batches» разбивает их на пакеты по 100 Items. Узел «Send Email» работает в режиме «Run Once for Each Item» и отправляет персонализированное письмо каждому контакту в текущем пакете, соблюдая лимиты почтового сервиса.

Отладка и мониторинг Items

Для эффективной разработки рабочих процессов n8n предлагает инструменты отладки:

Режим выполнения (Execution Mode): Запуск workflow в режиме «Manual» или «Test» позволяет увидеть данные на выходе каждого узла.
Панель данных (Output Panel): При клике на узел после выполнения отображает детальную информацию: какие Items поступили на вход (INPUT) и какие были возвращены (OUTPUT). Можно просмотреть структуру каждого Item в формате JSON.
Встроенный редактор выражений: Позволяет тестировать выражения на реальных данных перед сохранением настроек узла.

Часто задаваемые вопросы (FAQ) по теме N8n Items

Как ограничить количество Items, обрабатываемых в рабочем процессе?

Используйте узел «Item Lists» и его операцию «Limit». Укажите нужное число — на выход пройдут только первые N Items из входящего массива. Альтернативно, настройте фильтрацию в узле-источнике данных (например, параметры «Limit» в SQL-запросе или API-вызове).

Чем отличается «Merge» от «Aggregate»?

Узел «Merge» объединяет потоки Items из параллельных веток, сохраняя их индивидуальность (например, список клиентов из CRM и список заказов из Shopify сливаются в один общий список записей). Узел «Aggregate» группирует Items из одного потока по ключу и вычисляет сводные показатели, уменьшая общее количество Items (например, группировка заказов по клиенту с подсчетом общей суммы).

Как обработать только первый или последний Item в массиве?

В выражениях используйте индексацию. Для первого Item: {{ $("node_name").item[0].json.field_name }}. Для последнего: {{ $("node_name").item[$("node_name").item.length - 1].json.field_name }}. Также можно использовать узел «Item Lists» для извлечения первого/последнего элемента.

Почему узел «Function» не видит мои данные?

Убедитесь, что в коде функции вы правильно обращаетесь к Items. Данные поступают в переменную $input. Для доступа к массиву Items используйте $input.all() или $input.item. Для доступа к JSON первого Item первого входа: $input.first().json. Возвращать данные необходимо с помощью return $input.all(); или нового массива.

Как преобразовать один Item с массивом внутри в несколько отдельных Items?

Если в поле Item содержится массив (например, «tags»: [«red», «blue», «green»]), и нужно создать отдельный Item для каждого элемента массива, используйте узел «Function». Напишите код, который проходит по массиву и для каждого элемента создает новый объект Item, копируя необходимые поля из исходного.

Как работать с бинарными данными (файлами, изображениями) в Items?

N8n поддерживает бинарные данные. Узлы, работающие с файлами (например, «Read/Write File from Disk», «HTTP Request» для загрузки), добавляют к Item специальное бинарное свойство binary. В последующих узлах к этим данным можно обращаться через выражения, например, {{ $binary.data }} или {{ $binary["file_name"].data }}.

Что происходит с Items, если узел завершается с ошибкой?

По умолчанию выполнение рабочего процесса останавливается, и Items не передаются дальше. Однако вы можете настроить обработку ошибок, используя параметр «Continue on Fail» в настройках узла. Если он включен, узел, даже завершившись с ошибкой, передаст входящие Items на следующий узел, что позволяет создать ветку для обработки сбоев.

Заключение

Items — это кровь и плоть любого рабочего процесса в n8n. Глубокое понимание их структуры JSON, жизненного цикла, методов трансформации и способов доступа к данным является ключом к созданию продвинутых, эффективных и отказоустойчивых автоматизаций. Освоение узлов для работы с Items, таких как Set, Function, Merge, Aggregate и Split In Batches, значительно расширяет возможности интегратора. Комбинируя эти узлы и используя мощную систему выражений, можно реализовать практически любую бизнес-логику по обработке данных, от простой пересылки информации до сложной ETL-трансформации и многозвенной оркестрации между сервисами.