N8n REST API: Полное руководство по интеграции и автоматизации
N8n REST API представляет собой программный интерфейс, который позволяет взаимодействовать с платформой автоматизации n8n извне. Этот API открывает возможности для управления рабочими процессами (workflows), их выполнения, мониторинга, а также для интеграции n8n в более крупные системы и скрипты. В отличие от графического интерфейса, API предоставляет машиночитаемый способ полного контроля над инстанцией n8n, что критически важно для DevOps, CI/CD пайплайнов и создания кастомных панелей управления.
Архитектура и базовые концепции N8n API
API n8n построен по принципам REST и использует стандартные HTTP-методы (GET, POST, PUT, PATCH, DELETE) для операций с ресурсами. Основные сущности, с которыми работает API, — это Workflows (рабочие процессы), Executions (запуски), Credentials (учетные данные) и Webhooks (внешние триггеры). Аутентификация в API по умолчанию осуществляется с помощью секретного ключа, который генерируется в настройках экземпляра n8n. Важно понимать, что n8n может работать в двух режимах: как изолированный сервис и как встраиваемая библиотека, и возможности API в этих сценариях могут различаться.
Аутентификация и безопасность
Для вызова большинства эндпоинтов API n8n требуется заголовок аутентификации. Основной метод — использование заголовка X-N8N-API-KEY, значением которого является сгенерированный API-ключ. Альтернативно, можно использовать базовую HTTP-аутентификацию (Basic Auth) или сессионные куки после входа в UI. Настоятельно рекомендуется использовать HTTPS для защиты передаваемых данных и хранить API-ключи в безопасном месте, например, в переменных окружения.
| Метод | Заголовок/Параметр | Пример | Использование |
|---|---|---|---|
| API Key | X-N8N-API-KEY |
X-N8N-API-KEY: your_secret_api_key_here |
Рекомендуемый способ для сервер-сервер взаимодействия. |
| Basic Auth | Authorization: Basic |
Authorization: Basic base64(email:password) |
Альтернативный способ, использует учетные данные пользователя. |
| Session Cookie | Cookie |
Cookie: n8n-session=session_id_value |
Используется после входа через веб-интерфейс, чаще для браузерных скриптов. |
Ключевые эндпоинты API и их использование
Управление рабочими процессами (Workflows)
Эндпоинты для работы с рабочими процессами являются центральными. Они позволяют создавать, читать, обновлять, удалять, активировать и деактивировать workflows.
- GET /api/v1/workflows: Получение списка всех рабочих процессов. Поддерживает пагинацию, фильтрацию и выбор полей.
- GET /api/v1/workflows/{id}: Получение полной информации о конкретном workflow, включая его узлы (nodes) и связи.
- POST /api/v1/workflows: Создание нового рабочего процесса. Тело запроса должно содержать полное JSON-представление workflow.
- PUT /api/v1/workflows/{id}: Полное обновление существующего workflow.
- PATCH /api/v1/workflows/{id}: Частичное обновление (например, только активация).
- DELETE /api/v1/workflows/{id}: Удаление рабочего процесса.
- POST /api/v1/workflows/{id}/activate: Активация workflow (перевод его в активное состояние, чтобы он мог запускаться по триггерам).
- POST /api/v1/workflows/{id}/deactivate: Деактивация workflow.
- GET /api/v1/executions: Получение списка всех выполнений с возможностью фильтрации по workflow ID, статусу и дате.
- GET /api/v1/executions/{id}: Получение деталей конкретного выполнения, включая данные на каждом узле (если включено сохранение данных).
- POST /api/v1/workflows/{id}/run: Синхронный запуск workflow. API дожидается окончания выполнения и возвращает его результат. Важно для интеграций, требующих немедленного ответа.
- POST /api/v1/workflows/{id}/execute: Асинхронный запуск workflow. API немедленно возвращает ID запущенного выполнения, а сам процесс работает в фоне. Предпочтительнее для длительных операций.
- DELETE /api/v1/executions/{id}: Удаление записи о выполнении.
- GET /api/v1/credentials: Получение списка метаданных учетных записей (без самих секретов).
- GET /api/v1/credentials/{id}: Получение метаданных конкретной учетной записи.
- POST /api/v1/credentials: Создание новых учетных данных. Секретная часть должна быть передана в соответствующем поле.
- PATCH /api/v1/credentials/{id}: Обновление учетных данных. Можно обновить как название, так и сам секрет.
- DELETE /api/v1/credentials/{id}: Удаление учетных данных.
Запуск и мониторинг выполнения (Executions)
Executions представляют собой отдельные запуски рабочего процесса. API позволяет запускать workflow вручную и получать детальную информацию о прошлых выполнениях.
Управление учетными данными (Credentials)
Учетные данные хранятся в зашифрованном виде. API предоставляет ограниченный доступ к ним для обеспечения безопасности.
Практические примеры использования API
Пример 1: Создание и активация рабочего процесса через API
Следующий пример на Python демонстрирует, как создать простой workflow, который отправляет HTTP-запрос, и активировать его.
import requests
import json
API_KEY = "your_n8n_api_key"
N8N_URL = "https://your-n8n-instance.com"
headers = {"X-N8N-API-KEY": API_KEY, "Content-Type": "application/json"}
1. Создание workflow
workflow_data = {
"name": "API Created Workflow",
"nodes": [
{
"name": "HTTP Request Node",
"type": "n8n-nodes-base.httpRequest",
"parameters": {
"url": "https://api.example.com/data",
"method": "GET"
},
"position": [250, 300]
}
],
"connections": {},
"settings": {},
"triggerOnActivation": True
}
response = requests.post(f"{N8N_URL}/api/v1/workflows", json=workflow_data, headers=headers)
new_workflow_id = response.json()["data"]["id"]
print(f"Created workflow ID: {new_workflow_id}")
2. Активация workflow
activate_response = requests.post(f"{N8N_URL}/api/v1/workflows/{new_workflow_id}/activate", headers=headers)
if activate_response.status_code == 200:
print("Workflow activated successfully.")
Пример 2: Синхронный запуск workflow с передачей входных данных
Многие workflows ожидают входные данные. Их можно передать через тело запроса при запуске.
run_payload = {
"workflowData": {
Данные для первого узла (обычно триггера или узла "Webhook").
"startNode": "Webhook Node", Имя узла, принимающего данные
"nodeData": {
"Webhook Node": [
[
{
"json": {"orderId": 12345, "customer": "John Doe"},
"binary": {}
}
]
]
}
}
}
response = requests.post(f"{N8N_URL}/api/v1/workflows/{new_workflow_id}/run", json=run_payload, headers=headers)
print(json.dumps(response.json(), indent=2))
Интеграция с внешними системами и вебхуки
N8n может не только вызывать внешние API, но и сам выступать в качестве вебхук-приемника. Для этого в workflow используется узел «Webhook». После активации такого workflow n8n предоставляет уникальный URL, на который можно отправлять POST, GET или другие HTTP-запросы для запуска процесса. Управление этими вебхуками также частично доступно через API, например, через получение информации о workflow. Для создания сложных интеграционных панелей можно использовать API для сбора статистики по выполнениям, статусам workflows и оперативного управления ими.
Ограничения, квоты и лучшие практики
Производительность API зависит от конфигурации сервера n8n и базы данных. При работе с большим количеством execution записей необходимо использовать пагинацию. Для предотвращения случайного удаления или деактивации критичных процессов рекомендуется использовать систему тегирования или вести внешний журнал изменений. Синхронный запуск (/run) имеет таймаут, который может быть настроен в конфигурации n8n. Для длительных операций всегда используйте асинхронный эндпоинт (/execute). Регулярно делайте бэкапы workflows через API (GET запросы) и храните их в системе контроля версий.
| Эндпоинт | Тип запуска | Возвращаемый ответ | Таймаут | Использование |
|---|---|---|---|---|
POST /api/v1/workflows/{id}/run |
Синхронный | Данные результата выполнения всего workflow. | Да (настраивается) | Быстрые операции, где результат нужен немедленно (генерация отчета, проверка). |
POST /api/v1/workflows/{id}/execute |
Асинхронный | ID выполнения (executionId). |
Нет | Длительные процессы (обработка файлов, массовая рассылка). |
Ответы на часто задаваемые вопросы (FAQ)
Как получить API-ключ в n8n?
В веб-интерфейсе n8n перейдите в раздел «Settings» (Настройки) -> «API». Нажмите «Create new API key». Скопируйте сгенерированный ключ и сохраните его в безопасном месте, так как позже его будет невозможно просмотреть полностью, только перегенерировать.
Можно ли запустить workflow с определенной версией?
Да, n8n поддерживает версионирование workflows. При обновлении workflow через API создается новая версия. Для запуска конкретной версии можно использовать параметр versionId в теле запроса к эндпоинту /run или /execute.
Как отслеживать статус асинхронного выполнения?
После асинхронного запуска вы получите executionId. Для проверки статуса периодически опрашивайте эндпоинт GET /api/v1/executions/{executionId}. В ответе будет поле status (например, «running», «success», «error», «waiting»).
Как передавать файлы (бинарные данные) при запуске workflow через API?
Для передачи файлов необходимо кодировать их в base64 и включать в поле binary объекта данных узла. Структура должна соответствовать ожиданиям узла, принимающего файлы (например, «Read Binary Files»).
Почему мой запрос к API возвращает ошибку 401?
Наиболее частая причина — отсутствие, неверный или просроченный API-ключ в заголовке X-N8N-API-KEY. Убедитесь, что ключ указан верно и что у пользователя, для которого создан ключ, есть необходимые права доступа.
Можно ли использовать n8n API для массового импорта/экспорта workflows?
Да, это одна из сильных сторон API. Вы можете получить все workflows (GET /api/v1/workflows), а затем использовать полученные JSON-определения для восстановления на другой инстанции n8n через POST запрос. Это основа для переноса конфигураций между средами (dev/stage/prod).
Как ограничить доступ к API для определенных IP-адресов?
Эта функциональность не реализована на уровне самого n8n. Необходимо настраивать брандмауэр, обратный прокси-сервер (например, nginx) или использовать сетевые политики на уровне инфраструктуры для ограничения доступа к порту, на котором работает n8n.
Заключение
REST API n8n является мощным инструментом, который трансформирует платформу из инструмента визуальной автоматизации в полноценный компонент корпоративной ИТ-инфраструктуры. Он позволяет программировать жизненный цикл рабочих процессов, интегрировать их выполнение в сторонние системы и создавать сложные управляющие надстройки. Понимание и грамотное использование эндпоинтов для управления workflows, executions и credentials открывает путь к построению отказоустойчивых, масштабируемых и легко управляемых конвейеров автоматизации. Для успешного применения необходимо уделять внимание безопасности (API-ключи, HTTPS), выбирать правильный метод запуска (синхронный/асинхронный) и реализовывать обработку ошибок в клиентском коде.
Комментарии