Искусственный интеллект

N8n how to get tool description

Получение описания инструментов (нод) в n8n: методы, API и практическое применение

В n8n инструменты представлены нодами (nodes). Каждая нода обладает метаданными, включающими название, описание, свойства входов/выходов, параметры конфигурации и другую критически важную информацию для построения корректных рабочих процессов (workflows). Получение программного доступа к этим описаниям необходимо для создания динамических интерфейсов, документации, систем валидации или интеграции n8n с другими платформами. Ниже детально рассмотрены все методы получения описаний инструментов.

Архитектура описаний нод в n8n

Описание ноды в n8n — это объект JavaScript/TypeScript, соответствующий определенному интерфейсу. Ключевые свойства описания:

    • name: Системное имя ноды (например, ‘n8n-nodes-base.httpRequest’).
    • displayName: Человекочитаемое имя, отображаемое в интерфейсе.
    • description: Текстовое пояснение функциональности ноды.
    • version: Версия ноды (обычно мажорная, например, 1).
    • inputs: Массив, описывающий количество и типы входов (‘main’, ‘main’, ‘main’ для трех входов).
    • outputs: Массив, описывающий количество и типы выходов.
    • properties: Массив объектов, описывающих параметры конфигурации ноды (поля, которые пользователь заполняет в интерфейсе). Каждое свойство имеет свой name, type, displayName, description, default value и другие атрибуты.

    Метод 1: Использование встроенного REST API n8n

    n8n предоставляет REST API эндпоинты для получения информации о нодах. Это основной метод для внешних систем.

    Эндпоинт GET /types/nodes

    Данный эндпоинт возвращает список всех доступных нод и их полные описания. Ответ включает как встроенные (core), так и установленные кастомные ноды.

    • URL: https://your-n8n-instance.com/api/v1/types/nodes
    • Аутентификация: Требуется API Key или сессионная аутентификация.
    • Формат ответа: JSON-массив, где каждый элемент соответствует одной ноде.

    Пример фрагмента ответа для ноды HTTP Request:

    
{
  "name": "n8n-nodes-base.httpRequest",
  "displayName": "HTTP Request",
  "description": "Makes an HTTP request and returns the response data",
  "version": 4,
  "inputs": ["main"],
  "outputs": ["main"],
  "properties": [
    {
      "displayName": "Method",
      "name": "method",
      "type": "options",
      "options": [
        { "name": "GET", "value": "GET" },
        { "name": "POST", "value": "POST" }
      ],
      "default": "GET",
      "description": "The HTTP method to use"
    },
    {
      "displayName": "URL",
      "name": "url",
      "type": "string",
      "default": "",
      "description": "The URL to make the request to",
      "required": true
    }
    // ... другие свойства
  ]
}

    Эндпоинт GET /nodes[/?options]

    Этот эндпоинт также предоставляет информацию о нодах, часто в формате, оптимизированном для UI. Может принимать query-параметры для фильтрации.

    Метод 2: Программный доступ через код n8n (для разработчиков нод и расширений)

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

    Использование NodeTypes Object

    В контексте n8n (например, в хуках или сервисах) можно получить доступ к коллекции всех нод через NodeTypes().

    
// Пример в TypeScript в контексте n8n
import { Container } from 'n8n-core';
import { NodeTypes } from 'n8n-workflow';

// Получение экземпляра NodeTypes
const nodeTypes = Container.get(NodeTypes);

// Получение объекта конкретной ноды по ее имени
const httpRequestNode = nodeTypes.getByNameAndVersion('n8n-nodes-base.httpRequest');

// Получение описания ноды
const nodeDescription = httpRequestNode.description;

// Получение свойств
const nodeProperties = nodeDescription.properties;

    Чтение файлов описания напрямую

    Каждая нода содержит файл NodeName.node.json, в котором хранится ее описание в JSON-формате. Этот файл находится в директории ноды. Вы можете прочитать его с помощью стандартных методов Node.js fs.readFile.

    
const fs = require('fs').promises;
const path = require('path');

async function getNodeDescription(nodeName) {
  // Путь может варьироваться в зависимости от установки
  const nodePath = path.join('node_modules', nodeName, 'NodeName.node.json');
  const data = await fs.readFile(nodePath, 'utf8');
  return JSON.parse(data);
}

    Метод 3: Использование CLI n8n (Community Edition)

    В n8n Community Edition можно использовать командную строку для экспорта информации о нодах, хотя это менее прямой метод.

    1. Экспортируйте весь список нод в JSON-файл через UI (настройки > Nodes > Download nodes list).
    2. Проанализируйте полученный файл программно.

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

Сценарий 1: Динамическая генерация UI для выбора нод

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

Сценарий 2: Валидация и документация workflow

Автоматическая проверка корректности настроек нод в workflow, сравнение параметров с ожидаемыми типами из описания. Генерация актуальной документации по используемым нодам.

Сценарий 3: Создание систем обучения или онбординга

Использование описаний свойств для создания подсказок, туториалов или интерактивных гайдов по использованию конкретных нод внутри вашей организации.

Таблица сравнения методов получения описаний

Метод Контекст использования Сложность Доступность данных Динамичность
REST API (/types/nodes) Внешние приложения, интеграции, боты Низкая Полные описания всех нод Высокая (отражает текущее состояние инстанса)
NodeTypes Object Внутри кода n8n, кастомные хуки, триггеры Средняя (требует знаний кодовой базы) Полные описания, доступ к runtime-методам Высокая
Чтение JSON-файлов Статический анализ, сборка документации Низкая Только статические свойства (без computed) Низкая (только на этапе разработки/сборки)
CLI / Экспорт UI Разовое получение списка для анализа Очень низкая Ограниченный набор полей Низкая

Обработка и парсинг полученных данных

После получения JSON-описания ноды часто требуется извлечь конкретную информацию. Рассмотрим ключевые задачи.

Извлечение всех доступных операций (operations) ноды

Многие ноды (как Salesforce или Slack) поддерживают несколько операций (например, «create», «update», «get»). Они обычно определяются в свойстве с типом «options».


function getNodeOperations(nodeDescription) {
  const operationProperty = nodeDescription.properties.find(prop =>
    prop.name === 'operation' || prop.name === 'resource'
  );
  if (operationProperty && operationProperty.options) {
    return operationProperty.options.map(opt => ({ name: opt.name, value: opt.value }));
  }
  return [];
}

Получение обязательных (required) полей

Валидация workflow требует знания обязательных параметров.


function getRequiredFields(nodeDescription) {
  return nodeDescription.properties
    .filter(prop => prop.required === true)
    .map(prop => prop.name);
}

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

Вопрос: Как получить описание только для определенной ноды через API, а не для всех?

Ответ: Прямого эндпоинта для одной ноды в стандартном API нет. Необходимо запросить список всех нод через GET /types/nodes и отфильтровать результат по полю name, найдя элемент, где name === 'n8n-nodes-base.httpRequest' (или другое нужное имя).

Вопрос: Обновляются ли описания автоматически при обновлении ноды или n8n?

Ответ: Да, при использовании API /types/nodes или объекта NodeTypes вы всегда получаете актуальные описания, загруженные в текущий запущенный экземпляр n8n. При чтении JSON-файлов из node_modules данные будут соответствовать установленной версии пакета.

Вопрос: Можно ли через API получить описание не только ноды, но и ее credentials?

Ответ: Да, для этого существует отдельный эндпоинт GET /types/credentials. Он возвращает описание всех доступных типов учетных данных (credentials), включая их свойства и форматы.

Вопрос: Как получить список всех нод определенной категории (например, «Communication»)?

Ответ: В ответе API /types/nodes каждая нода содержит поле group или categories. Необходимо отфильтровать массив результатов, оставив ноды, у которых в массиве categories содержится искомая категория. Пример: node.categories.includes('Communication').

Вопрос: Я разрабатываю кастомную ноду. Как обеспечить, чтобы ее описание было доступно через API?

Ответ: Если ваша нода корректно упакована, установлена в n8n и зарегистрирована (через package.json n8n или методом loadNodesFromDirectory), она автоматически появится в ответе API /types/nodes. Убедитесь, что ваш класс ноды корректно реализует свойство description.

Вопрос: Как программно определить, какие типы данных (string, number, array) ожидает конкретный параметр ноды?

Ответ: Анализируйте свойство type в каждом элементе массива properties описания ноды. Типы могут быть: ‘string’, ‘number’, ‘boolean’, ‘options’, ‘collection’, ‘fixedCollection’, ‘json’, ‘dateTime’ и другие. Для сложных вложенных структур необходимо рекурсивно обходить свойства внутри typeOptions или options.

Вопрос: Можно ли получить переводы (i18n) описаний нод через API?

Ответ: Нет, стандартный API возвращает описания только на языке, установленном в конфигурации n8n (по умолчанию английский). Сами файлы переводов находятся внутри пакетов нод в папках translations/, и к ним можно получить прямой доступ через файловую систему.

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *