Обработка JSON в n8n: парсинг и трансформация данных
Блок 1. Основы JSON в n8n — что нужно знать перед началом работы
При работе с API или webhook вы неизбежно столкнетесь с JSON-данными. Понимание этого формата — основа для создания любых автоматизаций в n8n. Именно в формате JSON данные чаще всего приходят от внешних сервисов, передаются между узлами (nodes) и в итоге отправляются дальше — в CRM, мессенджеры, таблицы и базы данных. Поэтому умение читать и понимать JSON в контексте n8n — обязательный навык.
JSON (JavaScript Object Notation) — это текстовый формат, который описывает структуру данных с помощью пар «ключ — значение». Его часто называют «универсальным языком обмена данными между системами», потому что его понимают почти все современные API и интеграционные инструменты. В контексте n8n именно JSON определяет, как выглядят ваши items, какие там поля доступны и что вы можете использовать в expressions.
Базовая структура JSON выглядит так: есть объекты (object), которые заключены в фигурные скобки {}, и массивы (array), которые заключены в квадратные скобки []. Внутри объекта находятся ключи и значения:
- ключ (key) — это название поля, всегда строка;
- значение (value) — это данные этого поля: строка, число, булево значение, объект или массив.
Простой пример JSON-объекта, с которым вы можете столкнуться в n8n при работе с API:
json
{
"id": 123,
"name": "Иван",
"email": "ivan@example.com",
"isActive": true,
"tags": ["vip", "newsletter"],
"address": {
"city": "Moscow",
"country": "Russia"
}
}
Здесь хорошо видно, как устроены ключи и значения JSON:
- id — число,
- name и email — строки,
- isActive — булево значение (true/false),
- tags — массив строк,
- address — вложенный объект с собственными ключами и значениями.
В n8n этот формат завязан на понятии items. Каждый узел обычно возвращает массив элементов (items), где каждый элемент — это объект JSON с полем json внутри. Упрощённо это выглядит так:
json
[
{
"json": {
"id": 1,
"name": "Иван"
}
},
{
"json": {
"id": 2,
"name": "Мария"
}
}
]
Именно такая структура данных n8n используется при передаче информации между узлами. Каждый элемент в массиве — отдельная «строчка» данных, с которой можно работать: фильтровать, изменять, объединять, отправлять дальше. Понимание, что вы почти всегда работаете с массивом items, а не с одним объектом, критично важно для корректной обработки JSON-данных в n8n.
Типы данных в формате JSON достаточно просты, но в контексте n8n их важно распознавать:
- строки ("text"),
- числа (123 или 45.67),
- булевые значения (true или false),
- null (отсутствие значения),
- объекты ({ ... }),
- массивы ([ ... ]).
Все эти типы вы увидите в интерфейсе n8n, когда откроете вкладку JSON в данных узла. Это и есть ваши «JSON данные n8n», с которыми вы будете работать.
Чтобы правильно читать структуру JSON в интерфейсе n8n, удобно мысленно раскладывать её по уровням:
- верхний уровень — список items,
- внутри каждого item — объект json,
- внутри json — конкретные ключи и значения: name, email, address.city и т.д.
Если в данных есть вложенные JSON-объекты и массивы, n8n показывает их в виде раскрывающихся структур. Раскрывая уровни, вы понимаете, какие поля доступны для выборки в expressions и как устроена структура данных n8n в вашем workflow.
Теперь, когда вы понимаете формат JSON, структуру данных n8n, ключи и значения JSON, а также как выглядят массивы и объекты JSON в интерфейсе, можно перейти к практике. Теперь, когда вы понимаете структуру JSON, давайте разберем, как извлекать и преобразовывать эти данные в реальных сценариях автоматизации.
Блок 2. Парсинг JSON — извлечение нужных данных из API и webhook
Когда вы получаете данные от внешнего API или webhook, они часто приходят в формате JSON-строки или в виде сложной вложенной структуры. Чтобы использовать эти данные в workflow, их нужно правильно распарсить — то есть превратить строку в JSON-объект и научиться доставать нужные поля. n8n предлагает несколько подходов: expressions, Code node и специальные функции для работы с JSON.
Самый простой способ извлечь данные из JSON-ответа API — использовать встроенные expressions n8n. Если узел API вернул items, то к данным можно обратиться, например, так: {{ $json.name }} для поля name или {{ $json.address.city }} для вложенного поля city. Это базовый вариант парсинга JSON в n8n без написания кода: вы просто выбираете нужное поле в интерфейсе или прописываете путь вручную.
С точки зрения n8n json парсинг может происходить разными методами:
- Expressions — когда данные уже в формате JSON и вам нужно лишь извлечь конкретные ключи ({{ $json.fieldName }}).
- Code node — когда необходимо написать произвольную логику на JavaScript для обработки сложных массивов и объектов («Code node JSON» сценарии).
- Специальные операции конвертации, когда исходно данные приходят как строка, и их нужно вручную превратить в JSON или наоборот.
Особенно важно понимать работу с вложенными JSON-структурами и массивами. Например, если API вернул:
json
{
"user": {
"id": 10,
"name": "Ирина",
"orders": [
{ "id": 1, "total": 100 },
{ "id": 2, "total": 250 }
]
}
}
В expressions можно обратиться к имени пользователя так: {{ $json.user.name }}. Но если вам нужно пройтись по массиву orders, одной простой expression может быть недостаточно — тут уже удобнее использовать Code node с циклом по массиву или узлы, которые умеют "Loop Over Items".
Функции JSON.parse() и toJsonString() особенно полезны, когда ваши данные не изначально в формате «чистого» JSON. Например, вебхук может прислать поле payload как строку:
json
{
"payload": "{\"email\":\"test@example.com\",\"age\":30}"
}
В Code node вы можете сделать:
javascript
const data = JSON.parse($json.payload);
return [{ json: data }];
Так вы превращаете строку в полноценный JSON-объект, доступный для дальнейших expressions. Обратная операция — toJsonString() — используется, когда нужно превратить JSON обратно в строку, например, чтобы передать её в API, который ждёт именно текст.
Ошибки при парсинге JSON — частая проблема. Они возникают, если строка не является корректным JSON (не хватает кавычки, лишняя запятая и т.п.) или вы обращаетесь к несуществующему полю через expressions ({{ $json.nonExisting.field }}). В таких случаях:
- проверяйте структуру входящих данных во вкладке JSON узла;
- используйте try/catch внутри Code node для безопасного JSON.parse();
- добавляйте проверки вида {{ $json.user && $json.user.name }}, чтобы не упасть на undefined.
Good practice: для простых кейсов извлечения данных n8n json парсинг лучше всего решать через expressions {{ $json.fieldName }} и авто-подстановку полей в интерфейсе. Для сложных сценариев с вложенными массивами, фильтрацией и преобразованием лучше перейти к Code node и работать с объектами и массивами напрямую на JavaScript.
Для простых извлечений используйте expressions ({{ $json.fieldName }}), для сложной логики — Code node с JavaScript. Теперь перейдем к трансформации этих данных для ваших бизнес-задач.
Блок 3. Трансформация данных с помощью Set node (Edit Fields) и Code node
Set node (или Edit Fields) — это швейцарский нож для работы с данными в n8n. Он позволяет модифицировать структуру данных без написания кода и покрывает большую часть типичных задач по трансформации JSON. Если вы хотите переименовать поля, добавить новые, удалить ненужные или подготовить данные для отправки в другой сервис — начните с Set node.
Основная идея Set node в том, что вы управляете тем, какие поля попадут в выходные items и в каком виде. Узел поддерживает несколько режимов работы, но ключевые для ежедневных задач — это Manual Mapping и JSON Output. Оба режима заточены под удобную работу с n8n variables и позволяют гибко настраивать формат JSON на выходе.
В режиме Manual Mapping вы работаете с полями поштучно:
- добавляете новое поле, задаёте его имя;
- выбираете источник значения: фиксированная строка, число, булево или expression вида {{ $json.oldField }};
- можете удалить исходные поля, оставив только необходимые для следующего узла.
Это удобно, когда нужно навести порядок в структуре: переименовать first_name в firstName, собрать полное имя fullName из firstName и lastName, убрать лишние внутренние поля API. Такой подход даёт прозрачную структуру данных n8n на следующем шаге.
Режим JSON Output позволяет задать сразу целый JSON-объект в одном поле ввода. Вы просто описываете структуру, которую хотите получить, например:
json
{
"fullName": "{{ $json.firstName }} {{ $json.lastName }}",
"email": "{{ $json.email }}",
"isActive": "{{ $json.status === 'active' }}"
}
n8n подставит значения из текущего item, и на выходе вы получите готовый объект в нужном формате. Этот режим удобен, когда вы чётко представляете финальную структуру и хотите описать её одним блоком вместо поэлементного редактирования.
Когда использовать n8n set node вместо Code node?
- Если задача сводится к добавлению, изменению или удалению полей без сложной логики, циклов или условий.
- Если вы хотите, чтобы конфигурация была максимально «визуальной» и понятной без знания JavaScript.
- Если вы работаете с таблицами данных (n8n data tables), где нужно просто красиво подготовить поля под экспорт или запись.
Примеры того, как создавать новые поля на основе существующих данных в Set node:
- fullName = {{ $json.firstName + ' ' + $json.lastName }};
- orderValueWithTax = {{ $json.orderValue * 1.2 }};
- isBigOrder = {{ $json.orderValue > 1000 }}.
Во всех этих случаях вы используете expressions и n8n variables внутри Set node, но не пишете отдельный код.
Code node пригодится, когда трансформация данных n8n выходит за рамки простого изменения полей. Например:
- нужно пройтись по массиву объектов и сгруппировать их по какому-то признаку;
- нужно преобразовать вложенные массивы в плоский список;
- необходимо выполнить сложные вычисления или многоступенчатую логику.
В Code node вы получаете массив items, обрабатываете его любым JavaScript-кодом и возвращаете новый массив, где каждый item.json — это ваш обновлённый JSON. Это даёт полную свободу работы с объектами и массивами, но требует больше внимания и навыков.
Set node идеально подходит для 90% задач трансформации: он прост, прозрачен и легко читается. Для сложной логики с циклами и условиями переходите к Code node. Но часто данные нужно не только трансформировать, но и объединять из разных источников.
Блок 4. Объединение данных — работа с Merge node и агрегацией
Представьте: вам нужно обогатить данные клиентов из CRM информацией о заказах из другой системы. В одном потоке у вас список клиентов, в другом — список заказов. В идеале вы хотите получить объединённый JSON, где у каждого клиента есть список его заказов или хотя бы ключевые поля по последнему заказу. Merge node создан именно для таких задач объединения данных n8n из разных источников.
Merge node в n8n позволяет соединять два потока items по разным принципам. Это ключевой инструмент для случаев, когда нужно сопоставить или склеить результаты из двух API, двух таблиц или разных веток одного и того же workflow. Правильная настройка Merge node — основа корректной агрегации данных n8n.
Существует несколько режимов слияния (combine mode n8n), которые отвечают за то, как именно будут объединяться потоки:
- Combine — объединяет элементы из двух потоков в один, обычно по индексу или ключу, создавая «расширенный» JSON.
- Append — просто добавляет items одного потока к items другого, не объединяя их по ключам (получается длинный список).
- Keep Matches — сохраняет только те элементы, которые совпали по ключам или индексам, похоже на INNER JOIN в SQL.
Варианты «Merge by Key» и «Merge by Index» управляют тем, как именно находятся пары элементов:
- Merge by Index — объединяет элементы с одинаковыми индексами в массивах: первый с первым, второй со вторым и т.д. Полезно, если оба потока гарантированно отсортированы одинаково и имеют одинаковую длину.
- Merge by Key — объединяет элементы, у которых значения определённого поля совпадают, например, customerId или email. Это более гибкий способ, когда число элементов в потоках отличается или порядок разный.
Когда использовать Merge node vs Loop Over Items?
- Merge node нужен, когда у вас есть два независимых потока данных (две ветки workflow) и вы хотите их скрестить по какому-то принципу — ключу или индексу. Это про объединение двух наборов items.
- Loop Over Items и похожие конструкции больше про обработку одного потока: пройтись по каждому элементу, сделать запрос, что-то изменить и вернуть результат. Это не столько про объединение, сколько про пошаговую обработку.
Типичная ошибка при объединении данных с разным количеством элементов — выбор режима Merge by Index там, где количества items не совпадают. В таком случае часть данных просто потеряется или сойдётся «не с теми» элементами. Чтобы этого избежать:
- при разных объёмах данных и наличии общего идентификатора (например, userId) используйте Merge by Key;
- проверяйте структуру выходных данных во вкладке JSON, чтобы убедиться, что нужные поля действительно появились внутри каждого объединённого item;
- учитывайте, что в режиме Append Merge node не делает сопоставления, а просто складывает потоки друг за другом.
Хорошая практика:
- используйте режим Combine и Merge by Key, когда нужно обогатить данные — клиент + его заказы, пользователь + его настройки, товар + его остатки на складе;
- используйте Append, когда хотите собрать «ленточку» данных из разных источников без логического объединения;
- используйте Keep Matches, когда важны только те пары элементов, у которых есть соответствие по ключу (аналог SQL JOIN с фильтрацией по совпадениям).
Merge node превращает разрозненные потоки данных в единую структуру. Используйте режим Combine для обогащения данных, Append — для простого добавления, а Keep Matches — для работы по принципу SQL JOIN. Освоив парсинг, трансформацию и объединение JSON, вы сможете автоматизировать практически любые бизнес-процессы на базе n8n.
