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

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

#Обзор

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

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

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

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

#Запуск бизнес-операций

• Отправка уведомлений: Использование сервисов SMS, электронной почты, WeCom для отправки уведомлений.
• Платежные запросы: Инициирование платежей, возвратов средств через платежные шлюзы.
• Обработка заказов: Отправка накладных и запрос статуса доставки в логистических системах.

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

• Вызовы микросервисов: Вызов API других сервисов в микросервисной архитектуре.
• Отчетность по данным: Отправка бизнес-данных на платформы аналитики и в системы мониторинга.
• Сторонние сервисы: Интеграция сервисов ИИ, распознавания текста (OCR), синтеза речи и т.д.

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

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

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

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

• Поддерживает все HTTP-методы: GET, POST, PUT, PATCH, DELETE.
• Поддержка пользовательских заголовков запроса (Headers).
• Поддержка различных форматов данных: JSON, данные формы, XML и т.д.
• Различные способы передачи параметров: параметры URL, параметры пути, тело запроса и т.д.

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

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

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

• Basic Auth: Базовая HTTP-аутентификация.
• Bearer Token: Аутентификация по токену.
• API Key: Аутентификация по пользовательскому API-ключу.
• Пользовательские заголовки: Поддержка любого метода аутентификации.

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

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

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

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

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.
  • Параметры тела (Body): Данные тела запроса (POST/PUT).

#Дополнительные настройки

• Таймаут: Установите таймаут запроса (по умолчанию 30 секунд).
• Повторная попытка при сбое: Настройте количество и интервал повторных попыток.
• Игнорировать сбой: Рабочий процесс продолжит выполнение, даже если запрос завершится неудачно.
• Настройки прокси: Настройте HTTP-прокси (при необходимости).

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

После выполнения узла HTTP-запроса данные ответа можно использовать в последующих узлах:

• {{$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": "Заказ {{$context.orderId}} отправлен"
  }
}

#Пример 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"
  - Обновить статус заказа на "Оплачен"
  - Отправить уведомление об успешной оплате
Иначе если {{$node.data.data.status}} равно "pending"
  - Сохранить статус заказа как "Ожидает оплаты"
Иначе
  - Записать в лог ошибку платежа
  - Уведомить администратора об исключении

#Пример 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 Token

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. Таймаут соединения: Проверьте сетевое соединение, увеличьте время ожидания.
2. 401 Неавторизовано: Убедитесь, что учетные данные для аутентификации верны.
3. 404 Не найдено: Проверьте правильность URL.
4. 500 Ошибка сервера: Проверьте статус сервиса поставщика API.

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

1. Используйте узлы логирования: Добавляйте узлы логирования до и после HTTP-запросов для записи данных запроса и ответа.

2. Проверяйте журналы выполнения: Журналы выполнения рабочего процесса содержат подробную информацию о запросах и ответах.

3. Инструменты тестирования: Сначала протестируйте API с помощью таких инструментов, как Postman, cURL и т.д.

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

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

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

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

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

#2. Настройте разумные таймауты

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

#3. Внедрите стратегии кэширования

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

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

Если вам нужно многократно вызывать один и тот же API, рассмотрите возможность использования пакетных интерфейсов API (если они поддерживаются).

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

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

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

#1. Защищайте конфиденциальную информацию

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

#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. Обезличивание журналов

При ведении журналов будьте внимательны к обезличиванию конфиденциальной информации (паролей, ключей и т.д.).

#Сравнение с Webhook

Эти две функции дополняют друг друга, создавая комплексное решение для системной интеграции.

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

• Документация плагина «Рабочий процесс»
• Рабочий процесс: Узел HTTP-запроса
• Рабочий процесс: Триггер Webhook
• Аутентификация по API-ключам
• Плагин документации API