Item lists n8n

Item Lists в n8n: Полное руководство по работе со структурами данных

Item List (список элементов) является фундаментальной концепцией в n8n, определяющей способ передачи и обработки данных между узлами. Понимание принципов работы со списками элементов критически важно для построения эффективных, надежных и сложных рабочих процессов. Каждый узел в n8n принимает на входе и возвращает на выходе список элементов, где каждый элемент представляет собой объект JavaScript в формате JSON, содержащий пары ключ-значение. Эта статья детально рассматривает структуру, манипуляции, методы работы и лучшие практики при использовании Item Lists в n8n.

Структура и представление Item List

Item List — это массив объектов. В контексте n8n это не просто массив примитивных значений (строк, чисел), а массив объектов, где каждый объект является самостоятельной единицей данных (элементом). Каждый элемент может содержать вложенные объекты и массивы. Данные в n8n всегда передаются в этой структуре, даже если элемент всего один.

Пример простого списка элементов:

• Элемент 1: {"id": 1, "name": "Product A", "price": 100}
• Элемент 2: {"id": 2, "name": "Product B", "price": 200}
• Элемент 3: {"id": 3, "name": "Product C", "price": 150}

В JSON-представлении этот список будет выглядеть как массив: [{"id":1,"name":"Product A","price":100},{"id":2,"name":"Product B","price":200},{"id":3,"name":"Product C","price":150}].

В интерфейсе n8n, особенно в узлах «Function» и «Function Item», данные отображаются в виде удобной для чтения таблицы, где строки соответствуют элементам, а столбцы — ключам (полям) этих элементов.

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

n8n предоставляет специализированные узлы для управления потоком и структурой данных.

Узел «Split In Batches»

Этот узел предназначен для разделения входящего списка элементов на несколько более мелких групп (пакетов). Это необходимо при работе с API, которые имеют ограничения на количество объектов в одном запросе (пагинация, лимиты). Узел накапливает элементы и передает их следующему узлу порциями заданного размера.

• Batch Size: Количество элементов в одном пакете.
• Options: Настройки повторных попыток и паузы между пакетами.

Узел «Aggregate»

Узел агрегирует данные из нескольких входных элементов в один выходной элемент на основе заданных операций и ключей группировки. Это аналог операций GROUP BY в SQL.

• Group By: Поле, по которому происходит группировка элементов.
• Operation: Действие, применяемое к сгруппированным данным (сумма, среднее, конкатенация, подсчет и т.д.).

Узел «Limit»

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

• Max Items: Максимальное количество элементов для пропуска дальше.

Узлы «Sort» и «Filter»

Узел «Sort» упорядочивает элементы списка по указанному полю в порядке возрастания или убывания. Узел «Filter» позволяет исключить элементы из потока на основе заданных условий (например, price > 100). Условия можно комбинировать с помощью логических операторов (AND, OR).

Манипуляции с данными в узлах «Function» и «Function Item»

Эти узлы предоставляют максимальную гибкость для работы со списками элементов с помощью JavaScript/TypeScript кода.

Узел «Function Item» (Обработка каждого элемента отдельно)

Код выполняется для каждого элемента списка по отдельности. Контекст текущего элемента доступен через переменную $item. Возвращаемое значение становится новым элементом.

Пример: Добавление вычисляемого поля.

// Предположим, каждый $item имеет поля price и tax
const total = $item.json.price 
(1 + $item.json.tax / 100);
$item.json.totalWithTax = Math.round(total 
100) / 100;
return $item;

Узел «Function» (Обработка всего списка целиком)

Код выполняется один раз для всего массива элементов, доступного через $input.all(). Позволяет выполнять операции над всей коллекцией: сложные трансформации, реструктуризацию, сводные вычисления.

Пример: Группировка и агрегация в коде.

const items = $input.all();
const summary = {};

for (const item of items) {
  const category = item.json.category;
  const value = item.json.value;

  if (!summary[category]) {
    summary[category] = { count: 0, total: 0 };
  }
  summary[category].count++;
  summary[category].total += value;
}

// Преобразуем результат обратно в формат списка элементов n8n
const result = Object.keys(summary).map(category => {
  return {
    json: {
      category: category,
      totalValue: summary[category].total,
      averageValue: summary[category].total / summary[category].count
    }
  };
});

return result;

Режимы выполнения: «Run Once for All Items» vs «Run Once for Each Item»

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

Режим выполнения	Описание	Использование	Пример узлов
Run Once for All Items	Узел активируется один раз, получая на вход весь список элементов. Узел сам решает, как обрабатывать коллекцию.	Операции над множеством данных: агрегация, сортировка, фильтрация, отправка запроса с массивом тел.	Aggregate, Sort, HTTP Request (который отправляет массив), Function.
Run Once for Each Item	Узел активируется отдельно для каждого элемента в списке. Каждая активация получает только один элемент.	Индивидуальная обработка, вызов API для каждой сущности, создание персональных файлов или сообщений.	HTTP Request (для вызова API на каждый ID), Email, Function Item, большинство триггеров.

Неправильный выбор режима — частая причина ошибок. Например, если узел HTTP Request, ожидающий один ID, работает в режиме «Run Once for All Items» и получает массив из 10 элементов, он, скорее всего, завершится ошибкой. Его необходимо переключить в режим «Run Once for Each Item».

Работа с вложенными массивами и операция «Flatten»

Часто элемент содержит поле, которое само является массивом объектов. Например, заказ (order) с списком товаров (items). Для обработки каждого товара отдельно необходимо «развернуть» (flatten) структуру.

Исходные данные (1 элемент):

{
  "orderId": 123,
  "items": [
    {"product": "Book", "qty": 2},
    {"product": "Pen", "qty": 5}
  ]
}

После применения операции flatten (например, в узле «Function») получаем 2 элемента:

• Элемент 1: {"orderId": 123, "product": "Book", "qty": 2}
• Элемент 2: {"orderId": 123, "product": "Pen", "qty": 5}

Обратная операция — группировка нескольких элементов в один с вложенным массивом — выполняется с помощью узла «Aggregate» (операция «Merge By Position» или «Aggregate Individual Fields») или вручную в узле «Function».

Передача метаданных: Binary Data, Paired Item

Помимо JSON-данных, элемент может содержать бинарные данные (файлы) и метаинформацию о связях.

• Binary Data: Каждый элемент имеет свойство binary, которое может содержать файлы (изображения, PDF и т.д.). Узлы вроде «Read Binary Files» добавляют эту информацию. При работе в «Function» узле доступ осуществляется через $item.binary.
• Paired Item: Это свойство (pairedItem) используется n8n для отслеживания происхождения данных и реализации функциональности «Retry on fail» для конкретного элемента. Обычно устанавливается автоматически.

Отладка и лучшие практики

• Использование узла «Debug»: Подключайте его после узлов, где происходит сложная обработка данных. Он показывает полную структуру элементов, включая JSON, бинарные данные и метаданные.
• Валидация структуры данных: В узлах «Function» добавляйте проверки на наличие ожидаемых полей (if ($item.json.someField) { ... }) для избежания ошибок выполнения.
• Эффективная обработка: Для простых операций над каждым элементом используйте «Function Item». Для операций над всей коллекцией или сложных преобразований структуры используйте «Function».
• Очистка данных: Используйте узел «Set» для стандартизации структуры элементов, удаления лишних полей или переименования ключей перед передачей в конечные узлы (например, в базу данных).

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

Как преобразовать массив строк в список элементов n8n?

В узле «Function» создайте новый массив, где каждый элемент будет объектом с ключом, например, «value».

const inputArray = ["A", "B", "C"];
return inputArray.map(str => ({ json: { value: str } }));

Чем отличается «Function» от «Function Item»?

«Function Item» выполняет код для каждого элемента по отдельности, автоматически итерируясь по списку. «Function» выполняется один раз и дает полный контроль над всем массивом элементов; программист должен самостоятельно организовать циклы и возврат итогового массива.

Почему мой узел HTTP Request падает с ошибкой, хотя данные есть?

Скорее всего, неверно выбран режим выполнения. Если API ожидает один объект, а у вас на входе узла список из многих элементов, установите режим «Run Once for Each Item». Если API ожидает массив объектов, оставьте «Run Once for All Items».

Как объединить данные из двух разных веток рабочего процесса в один список элементов?

Используйте узел «Merge». Он позволяет объединять элементы из двух входов по различным стратегиям: объединение попарно (по позиции), добавление в конец (по значению) или простое слияние двух списков в один.

Как получить общее количество элементов, прошедших через узел?

В узле «Function» вы можете получить длину массива: const totalCount = $input.all().length;. Для вывода этого значения как элемента создайте новый элемент: return [{ json: { totalCount } }];.

Что делать, если элемент содержит слишком много полей и это мешает отладке?

Используйте узел «Set» для выбора только необходимых полей (опция «Include Only Specified Fields») или узел «Function» для создания нового объекта с нужной структурой.

Как обработать ситуацию, когда входящий список элементов может быть пустым?

В узле «Function» добавьте проверку в начале кода:

const items = $input.all();
if (items.length === 0) {
  // Возвращаем пустой массив или элемент с флагом
  return [{ json: { message: "No data to process" } }];
}
// ... дальнейшая обработка

Как передать файл (бинарные данные) из одного узла в другой?

Бинарные данные передаются автоматически в свойстве binary элемента. Убедитесь, что узел-источник (например, «Read Binary Files» или «HTTP Request» с настройкой `responseFormat: ‘file’`) корректно их устанавливает. В целевом узле (например, «HTTP Request» для загрузки) используйте выражение типа `{{ $item.binary.data }}` для доступа к бинарному контенту.