Integrate node n8n

Интеграция Node.js с n8n: Полное руководство

Интеграция Node.js с n8n представляет собой процесс создания, настройки и использования пользовательских узлов (nodes) для расширения функциональности платформы автоматизации n8n. N8n построен на Node.js и использует его экосистему, что позволяет разработчикам создавать собственные узлы для взаимодействия с любыми API, сервисами или протоколами, которые не поддерживаются из коробки. Этот процесс включает в себя несколько ключевых этапов: настройку среды разработки, создание структуры узла, реализацию его логики, тестирование и публикацию.

Настройка среды разработки для создания узлов n8n

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

• Установка инструментов: Убедитесь, что Node.js и npm установлены глобально.
• Инициализация проекта узла: Используйте официальный генератор или создайте структуру вручную. Рекомендуется использовать команду npm init n8n-node для инициализации проекта с помощью официального инструмента.
• Структура проекта: Типичный проект узла содержит следующие ключевые файлы:
  • package.json — метаданные и зависимости.
  • index.ts или index.js — основной файл с описанием узла.
  • credentials.ts — описание параметров аутентификации (если требуется).
  • nodes/ — директория для файлов описания узлов.
  • Icon.png — иконка узла.

Анатомия узла n8n: Ключевые компоненты

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

Компонент	Назначение	Пример свойства в коде
Свойства узла (Node Properties)	Основная метаинформация: имя, описание, версия, категория.	displayName, name, icon, group, version
Описание полей (Fields)	Определяет параметры, которые пользователь видит и заполняет в интерфейсе n8n.	properties в секции description
Методы выполнения (Execution Methods)	Функции, которые выполняют основную работу узла (например, обработка входящих данных).	async execute()
Креденшалы (Credentials)	Схема данных для аутентификации узла во внешних сервисах (API ключи, логины/пароли).	Отдельный класс, расширяющий ICredentialType

Пошаговый процесс создания простого узла

Рассмотрим создание узла «Simple Greeting», который принимает имя и возвращает приветствие.

1. Определение свойств узла

В файле Greeting.node.ts описываем базовые свойства.

import { INodeType, INodeTypeDescription } from 'n8n-workflow';

export class GreetingNode implements INodeType {
    description: INodeTypeDescription = {
        displayName: 'Simple Greeting',
        name: 'greetingNode',
        icon: 'file:icon.png',
        group: ['transform'],
        version: 1,
        description: 'Generates a greeting message',
        defaults: { name: 'Simple Greeting' },
        inputs: ['main'],
        outputs: ['main'],
        properties: [
            {
                displayName: 'Name',
                name: 'name',
                type: 'string',
                default: '',
                placeholder: 'e.g., John',
                description: 'The name to greet',
            }
        ]
    };

2. Реализация логики выполнения

Добавляем метод execute в тот же класс.

    async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
        const items = this.getInputData();
        const returnData: INodeExecutionData[] = [];

        for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
            const name = this.getNodeParameter('name', itemIndex, '') as string;
            const greeting = `Hello, ${name || 'World'}!`;

            returnData.push({
                json: { greeting, originalInput: items[itemIndex].json },
                pairedItem: itemIndex,
            });
        }
        return [returnData];
    }
}

3. Сборка и тестирование узла в n8n

• Сборка: Выполните команду npm run build для компиляции TypeScript в JavaScript.
• Локальная установка: Скопируйте скомпилированные файлы (папку dist) и иконку в директорию ~/.n8n/custom/ или укажите путь к ним через переменную среды N8N_CUSTOM_EXTENSIONS.
• Запуск n8n: Перезапустите n8n. Ваш узел появится в палитре узлов в категории «Transform».
• Функциональное тестирование: Создайте новый workflow, добавьте узел «Simple Greeting», настройте его и запустите для проверки вывода.

Создание узлов с аутентификацией (Credentials)

Для работы с защищенными API необходимо создать тип учетных данных.

1. Создание файла Credentials

import { ICredentialType, INodeProperties } from 'n8n-workflow';

export class MyServiceApi implements ICredentialType {
    name = 'myServiceApi';
    displayName = 'My Service API';
    properties: INodeProperties[] = [
        {
            displayName: 'API Key',
            name: 'apiKey',
            type: 'string',
            typeOptions: { password: true },
            default: '',
        },
        {
            displayName: 'Subdomain',
            name: 'subdomain',
            type: 'string',
            default: '',
        }
    ];
}

2. Интеграция Credentials в узел

В описании узла необходимо указать ссылку на эти credentials и использовать их в методе execute.

export class MyServiceNode implements INodeType {
    description: INodeTypeDescription = {
        // ... другие свойства ...
        credentials: [
            {
                name: 'myServiceApi',
                required: true,
            },
        ],
    };

    async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
        const credentials = await this.getCredentials('myServiceApi') as { apiKey: string, subdomain: string };
        const apiKey = credentials.apiKey;
        // ... используем apiKey для вызова API ...
    }
}

Обработка данных: Работа с входами, выходами и бинарными данными

Узлы n8n могут обрабатывать как структурированные JSON-данные, так и бинарные файлы (изображения, PDF и т.д.).

Тип данных	Метод доступа	Описание
JSON-данные	this.getInputData() items[itemIndex].json	Основной способ получения данных от предыдущих узлов в workflow.
Параметры узла	this.getNodeParameter()	Получение значений, заданных пользователем в интерфейсе узла.
Бинарные данные	items[itemIndex].binary this.helpers.prepareBinaryData()	Доступ к файлам. Объект binary содержит свойства с данными файлов (например, data, mimeType).

Публикация и распространение пользовательского узла

После разработки и тестирования узел можно сделать доступным для сообщества.

• Публикация в npm: Убедитесь, что package.json корректно заполнен (ключевые поля: name с префиксом n8n-nodes-, version, description, main указывающий на dist/index.js). Выполните npm publish.
• Документация: Создайте файл README.md с подробным описанием узла, параметров и примеров использования.
• Интеграция с n8n: Пользователи смогут установить ваш узел через интерфейс n8n (Settings > Community Nodes) или через CLI командой n8n install-package n8n-nodes-your-package-name.

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

• Логирование: Используйте this.logger для вывода отладочной информации. Логи видны при запуске n8n с флагом --verbose.
• Обработка ошибок: Всегда обрабатывайте ошибки API и сетевые сбои, используя try-catch блоки. Пробрасывайте понятные ошибки с помощью throw new Error('Descriptive message').
• Производительность: Для узлов, выполняющих HTTP-запросы, реализуйте пагинацию и используйте асинхронные операции. Избегайте блокировки цикла событий Node.js.
• Следование стилю: Придерживайтесь стиля кодирования и структуры существующих официальных узлов n8n для обеспечения согласованности.

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

Вопрос: Могу ли я использовать существующие npm-пакеты в своем узле n8n?

Ответ: Да, вы можете. Установите необходимый пакет как зависимость с помощью npm install package-name, а затем импортируйте и используйте его в коде вашего узла. Убедитесь, что пакет совместим с версией Node.js, которую использует n8n.

Вопрос: Как обрабатывать пагинацию API в моем узле?

Ответ: Реализуйте цикл, который продолжает делать запросы, пока не будут получены все данные. Часто это требует анализа заголовков ответа (например, Link) или параметров в теле ответа. Возвращайте данные по мере их получения, используя returnData.push(). Для удобства можно добавить параметр «Limit» в интерфейсе узла.

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

Ответ: Проверьте следующие пункты:

• Путь к кастомным узлам указан верно (переменная среды N8N_CUSTOM_EXTENSIONS).
• Файлы узла скомпилированы (находятся в папке dist).
• В логах запуска n8n нет ошибок загрузки вашего узла (смотрите логи с флагом --verbose).
• Свойства name и displayName в описании узла заданы корректно и уникально.

Вопрос: Как протестировать узел без постоянного перезапуска n8n?

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

Вопрос: Можно ли создать узел, который имеет два различных выхода (Yes/No ветвление)?

Ответ: Да. В свойстве outputs укажите ['main', 'main'] для двух выходов. В методе execute вы должны возвращать массив массивов: [[], []]. Например, return [itemsForOutput1, itemsForOutput2];. В интерфейсе это будет отображено как два исходящих соединения.

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

Ответ: Для получения бинарных данных используйте items[itemIndex].binary?.['binaryPropertyName']. Чтобы создать или изменить бинарные данные, используйте хелпер this.helpers.prepareBinaryData(binaryBuffer, fileName, mimeType). Для передачи файла дальше по workflow добавьте результат этого вызова в свойство binary объекта возвращаемых данных.

Вопрос: Обязательно ли использовать TypeScript для создания узлов?

Ответ: Нет, не обязательно. Вы можете писать узлы на чистом JavaScript. Однако использование TypeScript рекомендуется, так как оно обеспечивает лучшую поддержку типов, автодополнение и помогает избежать ошибок, благодаря строгой типизации интерфейсов n8n.