N8n custom nodes

N8n Custom Nodes: Полное руководство по созданию и использованию

N8n — это инструмент с открытым исходным кодом для оркестрации рабочих процессов (workflow automation), который использует визуальный редактор на основе узлов (nodes). Каждый узел представляет собой отдельный шаг в рабочем процессе, выполняющий определенную функцию: получение данных, их преобразование, отправку запросов к API и т.д. Встроенные (native) узлы покрывают множество популярных сервисов, но реальная мощь n8n раскрывается через создание пользовательских узлов (custom nodes). Custom node — это узел, разработанный пользователем для интеграции с любым API, базой данных или системой, для которой нет готового решения в стандартной поставке n8n.

Архитектура и компоненты пользовательского узла

Пользовательский узел в n8n — это пакет Node.js, который следует определенной структуре и конвенциям. Он состоит из нескольких ключевых компонентов, описывающих его поведение и внешний вид в интерфейсе n8n.

Основные файлы узла:

• Node.ts (или Node.js): Основной файл, содержащий класс узла. Здесь определяется его логика: свойства, методы выполнения, обработки данных.
• Node.description.ts: Файл с метаданными узла. Описывает его название, иконку, версию, описание, входы/выходы, свойства (credentials) и параметры (options), которые пользователь видит в интерфейсе.
• index.ts: Точка входа, которая экспортирует класс узла.
• package.json: Стандартный файл манифеста npm-пакета, в котором указаны зависимости, имя пакета, версия и основная точка входа.
• Дополнительные файлы: Файлы для иконок, локализаций, сервисные классы для работы с API.

Создание пользовательского узла: пошаговый процесс

1. Настройка среды разработки

Требуется установленный Node.js (версии 18 или выше) и npm. Рекомендуется использовать n8n CLI для быстрого старта. Установите его глобально:

• npm install -g n8n

Создайте заготовку для нового узла с помощью команды:

• n8n create node-package "My Custom Nodes"

Эта команда создаст директорию со всей необходимой структурой файлов и примером узла.

2. Определение метаданных узла (Node.description.ts)

Этот файл описывает, как узел будет выглядеть в интерфейсе n8n. Рассмотрим ключевые секции.

Свойство	Тип	Описание	Пример
displayName	string	Название узла, отображаемое в интерфейсе.	‘My CRM — Create Contact’
name	string	Внутреннее имя узла (в camelCase, без пробелов).	myCrmCreateContact
icon	string	Иконка из набора n8n или путь к пользовательской.	‘fa:user-plus’
group	string[]	Категория, в которой будет размещен узел.	[‘transform’]
version	number	Версия узла. При обновлении логики рекомендуется увеличивать.	1
subtitle	string	Текст, отображаемый под названием узла. Может использовать выражения типа ={{$parameter["operation"]}}.	‘Operation: {{$parameter[«operation»]}}’
description	string	Подробное описание функциональности узла.	‘Создает или обновляет контакт во внутренней CRM системе.’
inputs	NodeInputConfiguration	Количество входных соединений. Может быть ‘main’ (один), ‘multiple’ (несколько) или отсутствовать.	[‘main’]
outputs	NodeOutputConfiguration	Количество выходных соединений. Аналогично inputs.	[‘main’]
properties	INodeProperties[]	Массив объектов, описывающих параметры (поля) узла, которые пользователь настраивает.	См. пример ниже.
credentials	ICredentialType[]	Ссылка на тип учетных данных, необходимых для работы узла (например, API ключ).	[{ name: ‘myCrmApi’, required: true }]

Пример секции properties для поля выбора операции (operation):

• { displayName: 'Operation', name: 'operation', type: 'options', noDataExpression: true, options: [ { name: 'Create', value: 'create' }, { name: 'Update', value: 'update' } ], default: 'create', }

3. Реализация логики узла (Node.ts)

Основной класс узла наследуется от INodeType и должен реализовывать метод execute. Этот метод вызывается каждый раз, когда рабочий процесс доходит до данного узла.

Структура метода execute:

• Входные данные: Метод получает массив items. Каждый item представляет собой объект данных, пришедший с предыдущего узла (в формате json).
• Параметры: Значения, которые пользователь установил в полях узла, доступны через this.getNodeParameter().
• Учетные данные: Данные аутентификации (API ключи) получаются через this.getCredentials().
• Задача: Обработать входные items, выполнить необходимые HTTP-запросы (используя встроенную утилиту this.helpers.httpRequest), преобразования или любую другую логику.
• Возврат данных: Метод должен вернуть массив массивов INodeExecutionData[][]. Каждый вложенный массив представляет собой набор items для соответствующего выхода узла (если выходов несколько).

Пример фрагмента кода метода execute для узла, делающего GET-запрос:

• async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> { const items = this.getInputData(); const returnData: INodeExecutionData[] = []; for (let i = 0; i < items.length; i++) { const resource = this.getNodeParameter('resource', i) as string; const responseData = await this.helpers.httpRequest({ method: 'GET', url: `https://api.example.com/${resource}`, headers: { 'Authorization': `Bearer ${credentials.apiKey}`, }, }); returnData.push({ json: responseData }); } return [returnData]; }

4. Создание типа учетных данных (Credentials)

Если узел требует аутентификации, необходимо создать отдельный класс для типа учетных данных. Он определяет поля, которые пользователь должен заполнить (например, API Key, Secret, Domain). Эти данные затем безопасно хранятся и шифруются в n8n.

5. Сборка, тестирование и публикация

Для локальной разработки используется команда npm run dev. Она компилирует TypeScript-код и создает симлинк в директории ~/.n8n/custom, что позволяет n8n загрузить ваш узел при запуске в режиме разработки (n8n start --tunnel). После тестирования узел можно опубликовать как npm-пакет, чтобы другие пользователи могли установить его через npm install в директорию ~/.n8n/custom своего инстанса n8n.

Типы пользовательских узлов и расширенные возможности

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

Тип узла	Назначение	Ключевая особенность
Триггерный узел (Trigger Node)	Запуск рабочего процесса по событию (вебхук, поллинг).	Реализует методы trigger() и webhook(). Может работать в режиме поллинга (опрос API) или как вебхук.
Узел с несколькими выходами (Multiple Outputs)	Маршрутизация данных по разным веткам в зависимости от условий.	В методе execute возвращает несколько массивов, например, return [successBranch, errorBranch];.
Узел с ресурсами и операциями (Resource/Operation Pattern)	Создание комплексных узлов для целого API (как встроенные узлы для GitHub, Slack).	В метаданных определяется параметр resource (например, ‘User’, ‘Ticket’), а затем operation для этого ресурса (‘Create’, ‘Get’). Логика разделяется по switch-блокам.

Лучшие практики разработки custom nodes

• Обработка ошибок: Всегда обрабатывайте ошибки HTTP-запросов и невалидные данные. Используйте throw new NodeOperationError() для предоставления понятных сообщений об ошибках пользователю.
• Пагинация: Для операций, возвращающих большие списки данных, реализуйте поддержку пагинации. Используйте параметры типа ‘Limit’ и циклы для запроса всех страниц.
• Кэширование: Для данных, которые редко меняются (например, списки стран), используйте метод this.getCache() и this.setCache() для оптимизации производительности.
• Локализация: Для международной аудитории выносите все строки, отображаемые в UI, в отдельные файлы локализации.
• Валидация входных данных: Проверяйте обязательные параметры и их формат перед выполнением запросов к API.

Отладка и развертывание

Для отладки используйте встроенный режим отладки n8n, который позволяет просматривать входные и выходные данные каждого узла. Также полезно логировать данные с помощью this.logger.debug(). Для развертывания собственного узла в production-среде n8n необходимо:

1. Скомпилировать код в JavaScript (npm run build).
2. Скопировать итоговую директорию с узлом (включая package.json и скомпилированные файлы) в папку custom инстанса n8n. По умолчанию это ~/.n8n/custom/.
3. Перезапустить n8n. Узел появится в палитре узлов в соответствующей группе.

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

В чем основное отличие custom node от встроенного?

Встроенные узлы разрабатываются и поддерживаются командой n8n, они интегрированы в основную кодобазу. Пользовательские узлы создаются сообществом или отдельными разработчиками для нишевых или внутренних сервисов. Функционально они идентичны, но custom nodes требуют самостоятельной поддержки и обновления.

Можно ли изменить или расширить функциональность существующего встроенного узла?

Нет, напрямую модифицировать код встроенных узлов нельзя. Однако вы можете создать собственный узел, который будет выполнять нужную вам расширенную логику, либо использовать комбинацию узлов (например, узел «Function» или «Code») для добавления дополнительной обработки данных рядом со встроенным узлом.

Какие языки можно использовать для разработки custom nodes?

Официально поддерживается только TypeScript/JavaScript (Node.js). Поскольку n8n написан на TypeScript, это единственный язык для создания нативных узлов. Однако внутри узла вы можете, теоретически, выполнять shell-команды или вызывать внешние скрипты на других языках, но это усложняет развертывание и не является стандартной практикой.

Как организовать код, если я хочу создать набор узлов для одного сервиса (например, для внутреннего API)?

Рекомендуется создавать один npm-пакет (директорию), внутри которого будет несколько поддиректорий для каждого узла. В корневом package.json указываются все узлы в секции n8n. Это позволяет устанавливать весь набор узлов одной командой.

Как безопасно работать с учетными данными (API keys) в custom node?

Никогда не хардкодьте учетные данные и не выводите их в логах. Все секретные данные должны запрашиваться через механизм Credentials. В коде узла получайте их только через метод this.getCredentials(). N8n автоматически шифрует эти данные при хранении и расшифровывает только во время выполнения рабочего процесса.

Мой узел не появляется в интерфейсе n8n после установки. В чем может быть проблема?

Проверьте следующее:

• Файлы узла расположены в правильной директории: ~/.n8n/custom/ (или путь, указанный в переменной окружения N8N_CUSTOM_EXTENSIONS).
• Структура файлов корректна: есть package.json с заполненными полями name, version, main и секцией n8n.
• Код скомпилирован (файлы .js присутствуют).
• В логах n8n при запуске нет ошибок загрузки вашего пакета. Ищите сообщения, содержащие имя вашего пакета.
• Вы перезапустили n8n после копирования файлов узла.

Как обновить уже созданный и используемый custom node?

Внесите изменения в код, увеличьте номер версии в package.json и в файле описания узла (Node.description.ts). Пересоберите проект (npm run build) и замените файлы в директории custom. После перезапуска n8n новая версия узла станет доступна. Существующие рабочие процессы, использующие старую версию узла, продолжат работать, но при открытии их в редакторе появится предложение обновить узел до новой версии.