N8n json

N8n и работа с JSON: полное руководство

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

Структура JSON-сообщения в N8n

Каждый узел в N8n принимает на вход и возвращает на выходе массив JSON-объектов. Стандартное сообщение имеет следующую структуру:

• json: Основной контейнер для полезных данных. Содержит произвольные данные, полученные или сгенерированные узлом. Это основное поле для извлечения и манипуляции информацией.
• binary: Содержит ссылки на бинарные данные (например, изображения, PDF-файлы, аудиозаписи). Данные хранятся не напрямую в JSON, а в файловой системе или памяти, а в этом объекте содержатся идентификаторы и метаданные файлов.
• pairedItem: Служебная информация, которая связывает выходные элементы данных с входными. Критически важно для корректной обработки ошибок и отладки, так как позволяет отследить происхождение каждого элемента данных.

Пример типичного сообщения в N8n:

[
  {
    "json": {
      "id": 12345,
      "name": "Example Item",
      "status": "active",
      "metadata": {
        "createdAt": "2023-10-01",
        "owner": "user@example.com"
      }
    },
    "binary": {
      "attachment": {
        "data": "base64EncodedStringOrReference",
        "mimeType": "application/pdf",
        "fileName": "document.pdf"
      }
    },
    "pairedItem": {
      "item": 0
    }
  }
]

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

N8n предоставляет специализированные узлы для манипуляции, преобразования и создания JSON-данных.

1. Узел «Code» (JavaScript / Python)

Наиболее мощный инструмент для работы с JSON. Позволяет писать пользовательский скрипт для обработки данных. Имеет доступ к переменной $input, содержащей все входные данные от предыдущего узла.

• Функции: Фильтрация массива объектов, преобразование структур данных, агрегация информации, обогащение данных из внешних источников, сложные вычисления.
• Пример: Извлечение и преобразование полей из входящего JSON.

2. Узел «Set»

Позволяет добавлять, удалять или изменять поля в JSON-объектах каждого элемента. Работа может вестись в нескольких режимах.

Режим	Описание	Использование
Value	Установка статического значения или значения из выражения.	Добавление временной метки, константного флага.
JSON	Парсинг строки JSON и присвоение результата полю.	Обработка сырого JSON-ответа из API.
Binary	Создание ссылки на бинарные данные.	Подготовка файла для отправки по почте.

3. Узел «Split Out»

Разбивает массив, находящийся внутри поля JSON, на отдельные элементы рабочего процесса. Если входящий элемент содержит поле items: [{id:1}, {id:2}], то на выходе будет два независимых элемента с json.id равным 1 и 2 соответственно.

4. Узел «Aggregate»

Выполняет операцию, обратную «Split Out». Группирует несколько входящих элементов в один, объединяя их данные в массив или вычисляя агрегированные значения (сумма, среднее, конкатенация).

5. Узлы «Convert to JSON» / «Convert from JSON»

«Convert to JSON» преобразует строку в формате JSON в структурированный объект для дальнейшей работы. «Convert from JSON» выполняет обратную операцию — сериализует объект в строку JSON, что необходимо для отправки данных в теле HTTP-запроса или сохранения в текстовом поле базы данных.

Использование выражений (Expressions) для доступа к JSON

Выражения — это мощный механизм N8n для динамического доступа к данным и их обработки непосредственно в параметрах узлов, без написания кода. Основаны на синтаксисе Mustache и встроенных функциях.

• Базовый доступ к полям: {{$json.field_name}} — доступ к полю из выходных данных предыдущего узла.
• Доступ к вложенным объектам: {{$json.metadata.createdAt}} — доступ по цепочке свойств.
• Работа с массивами: {{$json.items[0].id}} — доступ к первому элементу массива.
• Использование функций: Выражения включают десятки функций для работы со строками, датами, математикой и данными.
  • {{$now.format("YYYY-MM-DD")}} — текущая дата.
  • {{$if($json.status === 'active', 'Enabled', 'Disabled')}} — условная логика.
  • {{$join($json.tags, ", ")}} — объединение массива в строку.

Практические паттерны работы с JSON в N8n

Паттерн 1: Обработка пагинированного API

Многие API возвращают данные постранично. Рабочий процесс должен последовательно запрашивать страницы, пока они не закончатся.

1. Узел HTTP Request получает первую страницу. Ответ содержит массив данных и параметр nextPageToken.
2. Узел Code проверяет наличие токена следующей страницы. Если он есть, workflow возвращает массив данных текущей страницы и параметр для следующего запроса.
3. Связь «Loop» перенаправляет токен обратно в HTTP Request для получения следующей страницы.
4. Узел Aggregate собирает все полученные массивы в один итоговый список.

Паттерн 2: Нормализация сложных структур

При интеграции с внешними сервисами данные часто приходят в неудобном формате. Узел Code используется для их преобразования в единый, предсказуемый формат.

// Вход: массив объектов с разной структурой
// Задача: создать единый массив с полями `name`, `email`, `type`
const items = $input.all();
const normalized = items.map(item => {
  const json = item.json;
  return {
    name: json.fullName || json.contactName || "Unknown",
    email: json.emailAddress || json.primaryEmail,
    type: json.userType?.toLowerCase() || "guest"
  };
});
return normalized;

Паттерн 3: Обработка бинарных данных и JSON вместе

Часто необходимо обработать файл (например, CSV) и использовать его содержимое как JSON.

1. Узел HTTP Request или Read Binary File загружает файл (попадает в поле binary).
2. Узел Convert to File преобразует бинарные данные в текст.
3. Узел Code парсит текст CSV/XML в массив JSON-объектов.
4. Дальнейшая обработка массива стандартными методами.

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

• Использование узла «Debug»: Подключайте его после узлов с сложной логикой. Он позволяет инспектировать полную структуру выходного сообщения, включая все поля (json, binary, pairedItem).
• Валидация входных данных: В узле Code добавляйте проверки на существование обязательных полей перед доступом к ним: if (!$json.user?.email) { return []; }.
• Обработка ошибок: Используйте узел «Error Trigger» или обрабатывайте исключения внутри узла Code с помощью try-catch для предотвращения падения всего workflow.
• Эффективность: При обработке больших массивов данных избегайте вложенных циклов в узле Code. По возможности используйте встроенные операции узлов «Split Out» и «Aggregate».
• Документирование: Комментируйте логику в узле Code. Используйте узел «Comment» для описания сложных участков workflow.

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

Как извлечь значение из сложного вложенного JSON?

Используйте выражение с точечной нотацией: {{$json.apiResponse.data.users[0].contact.email}}. Если путь может не существовать, используйте функцию $jmespath() или проверяйте каждый уровень в узле Code.

Чем отличается работа с JSON в узле Code от использования выражений?

Узел Code предоставляет полную программную среду (JavaScript/Python) для сложных преобразований, циклов, асинхронных операций. Выражения предназначены для быстрого доступа к данным и простых операций непосредственно в настройках других узлов. Для сложной логики используйте Code.

Как преобразовать строку, содержащую JSON, в объект?

Используйте специализированный узел «Convert to JSON» или в узле Code примените функцию JSON.parse(): const obj = JSON.parse($json.rawStringField);.

Почему узел не видит ожидаемое поле JSON?

Наиболее частые причины:

• Ошибка в имени поля (регистр, опечатка).
• Попытка доступа к полю элемента, который является строкой, а не объектом.
• Данные пришли не в том элементе массива (например, вы обращаетесь к $json[0].field, а данные в $json[1].field).
• Предыдущий узел вернул пустой массив или структуру, отличную от ожидаемой. Всегда проверяйте выход предыдущего узла через Debug.

Как эффективно обработать большой массив объектов (тысячи записей)?

• Включите опцию «Continue on Fail» в критических узлах.
• Рассмотрите возможность использования триггера «Schedule» для пакетной обработки данных частями.
• В узле Code избегайте алгоритмов квадратичной сложности O(n²). Используйте объекты для быстрого поиска (хеш-таблицы).
• При работе с внешними API используйте пагинацию и, если поддерживается, фильтрацию на стороне сервера.

Как передать файл (бинарные данные) вместе с JSON-полями в HTTP-запросе?

Используйте узел HTTP Request в методе POST. В теле запроса выберите тип «Multipart/Form-Data». Добавьте поля:

• Для файла: укажите тип «File», значение выберите из выражений как бинарные данные, например, {{$binary.fileName.fieldName}}.
• Для JSON-полей: добавьте поля типа «String» и укажите значения через выражения, например, {{$json.description}}.

Можно ли динамически создавать структуру JSON на основе условий?

Да, это можно сделать как в узле Code, так и в узле Set. В узле Set используйте режим «Value» и выражение с тернарным оператором или функцией $if. В узле Code создайте новый объект и заполните его свойства в зависимости от условий.

// Пример в узле Code
const result = {
  id: $json.id,
  type: $json.amount > 100 ? 'premium' : 'standard',
  // Динамическое добавление поля
  ...($json.notes ? { comment: $json.notes } : {}) // Добавляет поле только если notes существует
};
return result;