JSON в n8n: разбор, преобразование и вложенность

Данные в n8n - это JSON, и большая часть проблем при сборке воркфлоу приходится не на логику, а на то, что структура оказалась не такой, как ожидалось.

Структура данных

Ключевая вещь, которую стоит понять сразу: данные в n8n - это массив элементов, а не один объект.

Каждый элемент содержит поле с полезной нагрузкой и, если это файл, бинарную часть. Нода получает массив и выполняется для каждого элемента отдельно.

Отсюда растёт половина недоразумений:

• Нода выполнилась пятьдесят раз, потому что на входе было пятьдесят элементов.
• Отправилось пятьдесят одинаковых сообщений вместо одного.
• Внешний API получил пятьдесят запросов подряд и ответил ограничением.

Практическое правило: всегда смотрите в историю выполнений, сколько элементов пришло в ноду. Это первое, что объясняет странное поведение.

Доступ к вложенным полям

Обращение идёт по пути от корня элемента через точечную нотацию. Массивы внутри - по индексу.

Три вещи, которые ломают выражения чаще всего:

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

Имя поля с необычными символами. Точки, дефисы и пробелы в именах требуют обращения через скобки, а не через точку.

Ссылка на ноду по имени. Выражения ссылаются на другие ноды по их названию, и переименование ноды ломает все выражения, которые на неё ссылались. Это самая обидная поломка, потому что она возникает при наведении порядка.

Полезный приём при отладке: выведите весь элемент целиком в отдельной ноде и посмотрите на реальную структуру. Быстрее, чем угадывать путь по документации API, которая может отставать от реальности.

Преобразования структуры

Четыре операции закрывают почти всё.

Разделение массива на элементы. Ответ API часто выглядит как один элемент с массивом внутри. Нода разделения по полю превращает массив в отдельные элементы, с которыми дальше работают ноды по одному.

Сборка элементов в один. Обратная операция. Нужна перед отправкой одного сообщения по многим записям или перед записью одним запросом.

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

Слияние двух потоков. Соединение данных из двух источников по ключу. Здесь важно понимать режим слияния: по позиции, по совпадению ключа или все со всеми - последний вариант при неаккуратном ключе даёт неожиданно много элементов.

Общая рекомендация: приводите данные к нужной структуре как можно раньше. Воркфлоу, где преобразование размазано по десяти выражениям в разных нодах, невозможно отлаживать.

Типовые ошибки

• Ожидали один элемент, пришёл массив. Смотрите историю выполнений.
• Обращение к полю, которого нет. Особенно после изменения внешнего API: воркфлоу работал год и вдруг перестал.
• Число как строка. API часто отдаёт числа строками, и сравнение или сложение ведут себя не так, как ожидалось. Приводите тип явно.
• Пустой массив против отсутствующего поля. Это разные случаи, и проверять их надо по-разному.
• Кодировка и экранирование. JSON, вложенный строкой внутрь JSON, требует отдельного разбора и встречается чаще, чем хотелось бы.
• Слишком большой объём. Тысячи элементов в истории выполнений замедляют интерфейс и раздувают базу - см. работу с API.

Когда нужна нода с кодом

Ноды преобразования закрывают типовые случаи. Код нужен, когда структура нетривиальна: рекурсивный обход, сложная группировка, разбор нестандартного формата.

Полезное ограничение: если половина воркфлоу - это код, значит, задача переросла визуальный редактор. Разбор этой развилки - в статье про аналоги.

Базовая работа с выражениями - данные и выражения. Обзор - гид по n8n.