#Интеграция рабочего процесса через HTTP-запрос

Узел HTTP Request позволяет рабочему процессу NocoBase отправлять запросы к любым HTTP-сервисам, обеспечивая обмен данными и бизнес‑интеграцию с внешними системами.

#Обзор

Узел HTTP Request — ключевой компонент интеграции в рабочем процессе, который позволяет во время выполнения рабочего процесса вызывать сторонние API, внутренние интерфейсы сервисов или другие веб‑сервисы, чтобы получать данные или запускать внешние операции.

#Типовые сценарии использования

#Получение данных

• Запросы к сторонним сервисам данных: получение данных в реальном времени из API погоды, API курсов валют и т. п.
• Определение адреса: вызов API картографических сервисов для парсинга адресов и геокодинга
• Синхронизация корпоративных данных: получение данных клиентов и заказов из CRM/ERP

#Бизнес‑триггеры

• Отправка сообщений: вызов SMS-, email-, WeCom‑сервисов для отправки уведомлений
• Платёжные запросы: инициирование оплат и возвратов через платёжные шлюзы
• Обработка заказов: отправка накладных, запрос статуса логистики через системы доставки

#Интеграция систем

• Вызов микросервисов: обращение к API других сервисов в микросервисной архитектуре
• Отчётность по данным: отправка бизнес‑данных в аналитические и мониторинговые системы
• Интеграция сторонних сервисов: интеграция AI, OCR, синтеза речи и т. п.

#Автоматизация

• Плановые задания: периодический вызов внешних API для синхронизации данных
• Реакция на события: автоматический вызов внешних API при изменении данных
• Процессы согласования: отправка запросов на согласование через API системы согласования

#Возможности

#Полная поддержка HTTP

• поддержка методов GET, POST, PUT, PATCH, DELETE
• пользовательские заголовки запросов
• форматы данных: JSON, form data, XML
• типы параметров: URL‑параметры, path‑параметры, тело запроса

#Гибкая обработка данных

• Ссылки на переменные: динамическая сборка запросов с использованием переменных рабочего процесса
• Парсинг ответа: автоматический разбор JSON‑ответов и извлечение данных
• Преобразование данных: преобразование форматов данных запросов и ответов
• Обработка ошибок: настройка повторов, таймаутов и логики обработки ошибок

#Аутентификация и безопасность

• Базовая аутентификация: базовая HTTP‑аутентификация
• Токен Bearer: аутентификация по токену
• Ключ API: пользовательская аутентификация ключом API
• Пользовательские заголовки: поддержка любых методов аутентификации

#Шаги использования

#1. Убедиться, что плагин включён

Узел HTTP Request — это встроенная функция плагина рабочего процесса. Убедитесь, что плагин Рабочий процесс включён.

#2. Добавить узел HTTP Request в рабочий процесс

1. Создайте или отредактируйте рабочий процесс.
2. Добавьте узел HTTP запрос в нужном месте.

3. Настройте параметры запроса

#3. Настроить параметры запроса

#Базовая настройка

• URL запроса: адрес целевого API, поддерживает переменные

  https://api.example.com/users/{{$context.userId}}

• Метод запроса: выберите GET, POST, PUT, DELETE и т. п.

• Заголовки запроса: настройте заголовки HTTP‑запроса

  {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{$context.apiKey}}"
  }

• Параметры запроса:

  • Query-параметры: параметры URL
  • Параметры тела: данные тела запроса (POST/PUT)

#Расширенная настройка

• Таймаут: таймаут запроса (по умолчанию 30 секунд)
• Повтор при ошибке: число повторов и интервал
• Игнорировать ошибку: продолжать рабочий процесс даже при ошибке запроса
• Настройки прокси: HTTP‑прокси (если нужно)

#4. Использовать данные ответа

После выполнения узла HTTP Request данные ответа доступны в последующих узлах:

• {{$node.data.status}}: код HTTP-статуса
• {{$node.data.headers}}: заголовки ответа
• {{$node.data.data}}: тело ответа
• {{$node.data.error}}: сообщение об ошибке (если запрос не удался)

#Примеры сценариев

#Пример 1: Получение информации о погоде

// Конфигурация
URL: https://api.weather.com/v1/current
Method: GET
Query Parameters:
  city: {{$context.city}}
  key: your-api-key

// Использование ответа
Temperature: {{$node.data.data.temperature}}
Weather: {{$node.data.data.condition}}

#Пример 2: Отправка сообщения в WeCom

// Конфигурация
URL: https://qyapi.weixin.qq.com/cgi-bin/message/send
Method: POST
Headers:
  Content-Type: application/json
Body:
{
  "touser": "{{$context.userId}}",
  "msgtype": "text",
  "agentid": 1000001,
  "text": {
    "content": "Order {{$context.orderId}} has been shipped"
  }
}

#Пример 3: Запрос статуса платежа

// Конфигурация
URL: https://api.payment.com/v1/orders/{{$context.orderId}}/status
Method: GET
Headers:
  Authorization: Bearer {{$context.apiKey}}
  Content-Type: application/json

// Условная логика
Если {{$node.data.data.status}} равно "paid"
  - Обновить статус заказа на "Paid"
  - Отправить уведомление об успешной оплате
Иначе если {{$node.data.data.status}} равно "pending"
  - Оставить статус заказа как "Awaiting Payment"
Иначе
  - Зафиксировать ошибку оплаты в журнале
  - Уведомить администратора для обработки исключения

#Пример 4: Синхронизация данных с CRM

// Конфигурация
URL: https://api.crm.com/v1/customers
Method: POST
Headers:
  X-API-Key: {{$context.crmApiKey}}
  Content-Type: application/json
Body:
{
  "name": "{{$context.customerName}}",
  "email": "{{$context.email}}",
  "phone": "{{$context.phone}}",
  "source": "NocoBase",
  "created_at": "{{$context.createdAt}}"
}

#Настройка аутентификации

#Базовая аутентификация

Headers:
  Authorization: Basic base64(username:password)

#Токен Bearer

Headers:
  Authorization: Bearer your-access-token

#Ключ API

// В заголовке
Headers:
  X-API-Key: your-api-key

// Или в параметрах запроса
Query Parameters:
  api_key: your-api-key

#OAuth 2.0

Сначала получите access_token, затем используйте:

Headers:
  Authorization: Bearer {{$context.accessToken}}

#Обработка ошибок и отладка

#Частые ошибки

1. Connection Timeout: проверьте сеть, увеличьте значение таймаута.
2. 401 Unauthorized: проверьте учётные данные аутентификации.
3. 404 Not Found: проверьте, что URL корректен.
4. 500 Server Error: проверьте статус сервиса у API‑провайдера.

#Советы по отладке

1. Используйте узлы логирования: добавляйте узлы логирования до и после HTTP‑запросов для записи request/response.

2. Проверяйте логи выполнения: в логах выполнения рабочего процесса есть подробности запросов и ответов.

3. Инструменты тестирования: сначала тестируйте API через Postman/cURL.

4. Обработка ошибок: добавьте условную логику для обработки разных статусов ответа.

Если {{$node.data.status}} >= 200 и {{$node.data.status}} < 300
  - Обработать логику успеха
Иначе
  - Обработать логику ошибки
  - Записать ошибку: {{$node.data.error}}

#Оптимизация производительности

#1. Использовать асинхронную обработку

Для запросов, где не требуется немедленный результат, рассмотрите использование асинхронных рабочих процессов.

#2. Настраивать разумные таймауты

Задавайте таймауты исходя из реального времени ответа API, чтобы не ждать слишком долго.

#3. Реализовать кэширование

Для редко меняющихся данных (конфигурации, справочники) рассмотрите кэширование ответов.

#4. Пакетная обработка

Если вы делаете много вызовов к одному API, рассмотрите batch‑эндпоинты (если поддерживаются).

#5. Повторы при ошибках

Настройте разумные стратегии повторов, но избегайте чрезмерных повторов, которые могут привести к ограничению частоты запросов.

#Лучшие практики безопасности

#1. Защитить чувствительную информацию

• не раскрывайте чувствительные данные в URL
• используйте HTTPS для шифрования передачи
• храните API keys и чувствительные данные в переменных окружения или системе управления конфигурацией

#2. Валидировать данные ответа

// Проверка статуса ответа
if (![200, 201].includes($node.data.status)) {
  throw new Error('API request failed');
}

// Проверка формата данных
if (!$node.data.data || !$node.data.data.id) {
  throw new Error('Invalid response data');
}

#3. Ограничение скорости

Учитывайте лимиты запросов сторонних API, чтобы вас не заблокировали.

#4. Санитизация логов

При логировании удаляйте или маскируйте чувствительные данные (пароли, ключи и т. п.).

#Сравнение с вебхуком

Эти две возможности дополняют друг друга и помогают построить полноценное решение интеграции систем.

#Связанные ресурсы

• Документация по плагину рабочего процесса
• Рабочий процесс: узел HTTP запроса
• Рабочий процесс: триггер вебхук
• Аутентификация по API‑ключам
• Плагин документации по API