Інтеграція із зовнішніми сервісами за допомогою REST-конектора

ЗМІСТ

1. Створення ServiceEntry
2. Створення секрету для авторизації сервісу
3. Налаштування регламенту
4. Моделювання бізнес-процесу з використанням делегата Connect to external system

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

REST Connector — це конектор для підключення до зовнішніх захищених сервісів/систем поза кластером Платформи.

Для налаштування конектора необхідно виконати наступні кроки.

1. Створення ServiceEntry

Для того, щоб запит на отримання зовнішніх ресурсів міг вийти за межі кластера Платформи, необхідно на рівні реєстру створити Service Entry — точку виходу трафіку за межі системи.

Service Entry створюється автоматично, після того, як адміністратор реєстру налаштує інтеграцію в адміністративній панелі Control Plane. Після застосування змін до конфігурації реєстру та проходження Jenkins-пайплайну MASTER-Build-<registry-name>, підключення до зовнішньої системи буде налаштовано.

За деталями налаштувань у консолі Control Plane зверніться до сторінки Налаштування взаємодії з іншими системами у Control Plane.

Для версій реєстру 1.9.2 та нижче Service Entry створюється автоматично, після запуску пайплайну публікацій та розгортання змін до регламенту реєстру.

Перевірити, що Service Entry створено, можна у списку ServiceEntries в OpenShift-консолі. Для цього:

Увійдіть до OpenShift консолі.
Перейдіть до меню Home → API Explorer. У рядку пошуку Filter by kind введіть значення ServiceEntry, в результатах фільтрування виберіть відповідний сервіс.
Виберіть реєстр з випадного списку Project, в якому буде використовуватись зовнішній сервіс. Перейдіть до меню Instances і знайдіть необхідну ServiceEntry.

2. Створення секрету для авторизації сервісу

Для версій реєстру 1.9.3 і вище не потрібно створювати секрети вручну в Openshift.

Секрети (токен, пароль тощо) створюються автоматично після застосування налаштувань взаємодії з іншими системами, які необхідно виконати в адмін-панелі Control Plane.

В результаті застосування змін до конфігурації реєстру та проходження Jenkins-пайплайну MASTER-Build-<registry-name>, разом із Service Entry створюється й секрет для авторизації у зовнішньому сервісі. Він додається до user-management:hashicorp-vault для тієї системи/сервісу, до якої необхідно виконувати запити.

Зверніться до сторінки Налаштування взаємодії з іншими системами у Control Plane для отримання детальної інформації щодо налаштування взаємодії з іншими системами.

Щоб створити секрет вручну, необхідно виконати наступні кроки:

В OpenShift консолі перейдіть до меню Workloads → Secrets та оберіть відповідний проєкт з випадного списку Project. Натисніть Create → Key/value secret.

Вкажіть назву секрету у полі Secret name, наприклад, httpbin-basic-authentication.

Назву секрету необхідно буде використати у параметрі secret-name при налаштуванні регламенту (див. детальніше у розділі Налаштування регламенту).

rest connector 7

Доступно два типи аутентифікації сервісу:
- Для типу аутентифікації BASIC необхідно додати два параметри Key:
  - username
  - password
- Для типу аутентифікації PARTNER_TOKEN необхідно додати один параметр Key:
  - token
У результаті успішного виконання налаштувань буде створено секрет, за допомогою якого можливо авторизуватися в зовнішньому сервісі.

3. Налаштування регламенту

Для версій реєстру 1.9.3+ та вище основні інтеграційні налаштування виконуються на рівні екземпляра реєстру в адміністративній панелі Control Plane (див. детальніше — Налаштування взаємодії з іншими системами у Control Plane).

На рівні налаштувань регламенту адміністратор конфігурує лише:

назву системи;
дозволені операції:
- ендпоінт/шлях до ресурсу;
- метод.

Приклад 1. Налаштування external-systems у файлі bp-trembita/configuration.yml для версій реєстру 1.9.3+

# reusing external system names configured on registry level
external-systems:
  diia:
    operations:
      get-damaged-property:
        resource-path: "/api/v1/public-service/damaged-property/filtered"
        method: "GET"
      create-distribution:
        resource-path: "/api/v1/notification/distribution/push"
        method: "POST"
  http-bin:
    operations:
      get-operation:
        resource-path: "/get"
        method: "GET"

Для версії реєстру 1.9.2 та нижче виконайте попередні конфігурації на рівні регламенту реєстру.

Для цього потрібно налаштувати параметри блоку external-systems у конфігураційному файлі bp-trembita/configuration.yml відповідного реєстру.

Приклад для типу аутентифікації BASIC

external-systems:
  httpbin:
    url: http://httpbin.org/
    methods:
      get:
        path: /get
        method: GET
    auth:
      type: BASIC
      secret-name: httpbin-basic-authentication

після заголовка external-systems зазначається назва сервісу, що буде використовуватись, наприклад, httpbin;
для параметра url вказується адреса сервісу, наприклад, http://httpbin.org/;
в заголовку methods вказується назва методу взаємодії з сервісом, наприклад, get:
- path шлях до сервісу, наприклад, /get;
- method HTTP-метод взаємодії з сервісом, наприклад, GET.
для заголовка auth зазначаються параметри секрету:
- type створений типу аутентифікації BASIC або PARTNER_TOKEN;
- secret-name назву секрету, наприклад, httpbin-basic-authentication.

Приклад для типу аутентифікації PARTNER_TOKEN

external-systems:
  diia:
    url: http://api2.diia.gov.ua
    methods:
      get-damaged-property:
        path: /api/v1/public-service/damaged-property/filtered
        method: GET
    auth:
      type: PARTNER_TOKEN
      secret-name: secret2
      partner-token-auth-url: https://api2t.diia.gov.ua/api/v1/auth/partner
      token-json-path: $.token

4. Моделювання бізнес-процесу з використанням делегата Connect to external system

Для налаштування шаблону делегата в Camunda Modeler, необхідно виконати наступні кроки:

Створіть Service Task.
На панелі налаштувань справа натисніть кнопку Open Catalog, оберіть відповідний шаблон Connect to external system v2 зі списку та натисніть Apply для підтвердження.
Сконфігуруйте обраний шаблон:
- У полі Name вкажіть назву задачі, наприклад, Створити запит (GET).
- Input Parameters:
  - Розгорніть блок External system name та вкажіть назву сервісу, з яким буде відбуватися взаємодія:
    
    Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для метода.
    
    У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.
    
    У полі Variable Assignment Value введіть назву сервісу — httpbin.
  - Розгорніть блок External system method name та вкажіть HTTP-метод для взаємодії з сервісом:
    
    Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для метода.
    
    У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — String or Expression.
    
    У полі Variable Assignment Value введіть назву методу — get.
  - Розгорніть блок Request parametrs (використовується для методу GET) та вкажіть необхідні параметри запиту:
    
    Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для метода.
    
    У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — Map.
    
    Key вкажіть ключ параметра запита.
    
    Value вкажіть значення параметра запита.
  - Розгорніть блок Additional request headers та вкажіть додаткові заголовки запиту:
    
    Активуйте позначку Local Variable Assignment → ON. Це дозволить створити локальну змінну для метода.
    
    У полі Variable Assignment Type оберіть з випадного списку тип призначення змінної — Map.
    
    Key вкажіть ключ заголовка запита.
    
    Value вкажіть значення заголовка запита.
  - Блок Request payload використовується для POST і PUT методів запиту.
- Output Parameters:
  - Розгорніть блок Result variable та вкажіть назву змінної процесу, до якої необхідно записати результат (за замовчуванням — response):
  - Активуйте позначку Process Variable Assignment → ON.
  - У полі Assign to Process Variable введіть назву результівної змінної (за замовчуванням — response).