#Інтеграція HTTP-запитів у робочих процесах

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

#Огляд

Вузол HTTP-запиту є ключовим компонентом інтеграції в робочих процесах. Він дозволяє викликати сторонні API, інтерфейси внутрішніх сервісів або інші веб-сервіси під час виконання робочого процесу для отримання даних або запуску зовнішніх операцій.

#Типові сценарії використання

#Отримання даних

• Запити до сторонніх даних: Отримання даних у реальному часі з 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 (API Key): Користувацька автентифікація за допомогою ключа API.
• Користувацькі заголовки (Custom Headers): Підтримка будь-якого методу автентифікації.

#Кроки використання

#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

// Використання відповіді
Температура: {{$node.data.data.temperature}}
Погода: {{$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"
  - Оновити статус замовлення на "Оплачено"
  - Надіслати сповіщення про успішну оплату
Інакше, якщо {{$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)
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"