Інтеграційна REST-взаємодія реєстрів з іншими реєстрами на Платформі та зовнішніми системами

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

1. Загальний опис

Платформа підтримує інтеграційну взаємодію реєстрів за допомогою REST API-інтерфейсів. Така взаємодія можлива завдяки Підсистемі міжреєстрових інтеграцій.

Функціональність забезпечує інтероперабельність Платформи з можливістю надавати доступи до бізнес-процесів та API читання даних, а також дозволяє читати дані та викликати бізнес-процеси в інших реєстрах.

За замовчуванням на Платформі використовується інтеграційна взаємодія між реєстрами через шлюз безпечного обміну (ШБО) «Трембіта». Така взаємодія здійснюється за протоколом SOAP та вимагає розв’язання підготовчих питань у юридичній площині (див. детальніше — Реєстрація підсистеми нового реєстру на ШБО "Трембіта" Платформи).

Міжреєстрова взаємодія за допомогою REST дозволяє зменшити надлишкове використання обчислювальних потужностей, зовнішнього трафіку, скоротити час відповіді при інтеграції між реєстрами, не використовуючи SOAP-інтерфейси ШБО «Трембіта», а також відійти від складних бюрократичних механізмів.

Основні функції підсистеми міжреєстрових інтеграцій:

  • Надання API для виклику бізнес-процесів реєстру сторонніми для реєстру системами.

  • Надання доступу іншим реєстрам або системам до окремих запитів читання Підсистеми управління даними реєстру.

  • Маршрутизація запитів до зовнішніх реєстрів, до яких було надано доступ.

2. Схеми міжреєстрової REST-взаємодії

Виділяють 2 схеми інтеграційної взаємодії реєстрів, що розгорнуті на Платформі:

2.1. REST-взаємодія реєстрів на Платформі із зовнішньою інформаційною системою

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

int reg ext system
Зображення 1. Взаємодія реєстрів на Платформі зі сторонньою інформаційною системою

  1. Вихідна взаємодія можлива завдяки інтеграційному REST-конектору Connect to external system. Конектор має REST-інтерфейс для виклику зовнішніх ендпоінтів. Його можна використовувати при моделюванні бізнес-процесів у регламенті певного реєстру. Для автентифікації необхідно використовувати OpenShift (Kubernetes) секрети.

  2. Вхідна взаємодія можлива завдяки імплементованим реєстровим сервісам external-system-api-kong-proxy та registry-rest-api-ext.

    Зовнішня система має спочатку отримати пароль доступу від адміністратора реєстру. З цим паролем — отримати токен доступу у сервісі Keycloak. З цим токеном надалі можливо авторизуватися у сервісах та отримувати доступ до ресурсів.

    • Сервіс external-system-api-kong-proxy розгортається автоматично, разом з реєстром та має REST-інтерфейс, що дозволяє ініціювати бізнес-процеси у реєстрах на Платформі та отримувати з них дані. Сервіс використовує точку входу (ендпоінт) /startBp для старту бізнес-процесу.

    • Сервіс registry-rest-api-ext розгортається автоматично, після створення моделі даних у регламенті реєстру. Він дозволяє звертатися до API-представлень операційної бази даних реєстру.

2.2. REST-взаємодія реєстрів в межах одного екземпляра Платформи

При інтеграційній взаємодії реєстрів в межах Платформи завжди є реєстр-клієнт (споживач/запитувач даних) та цільовий реєстр (власник даних).

internal registries platform
Зображення 2. REST-взаємодія реєстрів в межах одного екземпляра Платформи
Реєстр-клієнт може запитати дані у цільового реєстру 2-ма шляхами:
Реєстр-клієнт має спочатку отримати токен доступу іншого реєстру у сервісі Keycloak. З цим токеном надалі можливо авторизуватися у сервісах.

  1. Через сервіс bp-webservice-gateway — розгортається автоматично, разом з реєстром та має REST-інтерфейс, що дозволяє ініціювати бізнес-процеси у реєстрах на Платформі та отримувати з них дані. Сервіс використовує точку входу (ендпоінт) /startBp для старту бізнес-процесу.

    • Ініціювати бізнес-процеси в іншому (цільовому) реєстрі можливо за допомогою спеціального розширення-делегата — Start business process in another registry. Він призначений лише для інтеграції реєстрів у межах Платформи.

    • Отримати дані з операційної БД реєстру іншого (цільового) реєстру в рамках виконання бізнес-процесів можливо за допомогою спеціального розширення-делегата — Search for entities from another registry data factory. Він призначений лише для інтеграції реєстрів у межах Платформи.

  2. Через сервіс registry-rest-api-ext — розгортається автоматично, після створення моделі даних у регламенті реєстру. Він дозволяє звертатися до API-представлень операційної бази даних реєстру з форм Кабінету користувача (за критеріями пошуку).

3. Налаштування взаємодії між реєстрами

Налаштуйте REST-взаємодію з іншими реєстрами в межах одного екземпляра Платформи, або зовнішніми системами.

3.1. Налаштування цільового реєстру (власника даних)

Якщо ваш реєстр є власником даних, і ви хочете виставляти інтеграційні API-точки, отримувати запити та віддавати дані іншим реєстрам або системам, виконайте наступні налаштування регламенту:

  1. Виконайте авторизаційні налаштування — надайте доступ для виклику бізнес-процесу.

  2. Змоделюйте бізнес-процес, що викликатиметься іншим реєстром.

  3. Створіть модель даних (надайте доступ на читання даних реєстру через API-представлення).

Детальніше про налаштування регламенту для кроків 1-3 див. на сторінці Налаштування регламенту для надання доступу до даних через SOAP та REST API.

  1. Також для REST-взаємодії — надайте доступ до реєстру для іншого реєстру на Платформі або зовнішньої системи в адміністративній панелі Control Plane. Адміністратор може додавати, видаляти, або призупиняти доступ до реєстру для інших реєстрів на Платформі та зовнішніх систем.

    Деталі дивіться на сторінці Налаштування доступу до реєстрів.

3.2. Налаштування реєстру-клієнта (споживача даних)

Налаштуйте взаємодію з іншими реєстрами для реєстру-споживача даних. Для цього:

  1. Змоделюйте бізнес-процес з можливістю виклику зовнішнього реєстру.

    Де можна знайти приклад референтного бізнес-процесу?

    Адміністратор Платформи може розгорнути для вас демо-реєстр — еталонний реєстр, що містить референтні та інші приклади файлів для створення цифрового регламенту. Він містить різноманітні елементи для розробки моделі даних, бізнес-процесів, UI-форм, аналітичної звітності, витягів, сповіщень, зовнішніх інтеграцій та багато іншого.

    Детальну інструкцію щодо розгортання демо-реєстру та отримання референтних прикладів моделювання ви знайдете на сторінці Розгортання демо-реєстру із референтними прикладами.

    Приклад BPMN-схеми процесу буде доступний у регламенті демо-реєстру за пошуком по ключовим словам — create-school-auto. Назви форм ви можете знайти всередині відповідних користувацьких задач (User Task) бізнес-процесу у полі Form key.

  2. В рамках бізнес-процесу використовуйте типові інтеграційні розширення для взаємодії з іншими реєстрами на Платформі:

    • старту бізнес-процесів в іншому реєстрі на Платформі — для цього використовуйте типове інтеграційне розширення-конектор Start business process in another registry;

    • отримання даних з операційної БД іншого реєстру на Платформі — для цього використовуйте типове інтеграційне розширення-конектор Search for entities from another registry data factory.

      Опис та налаштування делегатів ви можете знайти на сторінці Типові розширення для інтеграції з іншими реєстрами на Платформі.

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

      Наприклад, стартові змінні можна передати як Map вхідних параметрів (Input Parameters), тобто як ключі-значення, при налаштуванні делегата для старту бізнес-процесу.

      pass map params bp
      Зображення 3. Формування стартових змінних процесу у реєстрі-клієнті для передачі до цільового реєстру

  3. Змоделюйте UI-форму для читання даних з операційної БД реєстру за критеріями пошуку (search condition). Це дозволить звертатися до БД іншого реєстру з користувацької форми. Для цього:

    • Перейдіть до Кабінету адміністратора регламентів > Відкрийте розділ UI-форми > Створіть форму введення даних > Відкрийте Конструктор форм.

    • У компоненті Select перейдіть на вкладку Data > У полі Data Source URL введіть шлях до ресурсу у фабриці даних іншого реєстру:

      Приклад 1. Поле Data Source URL на UI-формі
      /api/integration/data-factory/test-registry/resource-name
      Параметр/Шлях Опис

      /api/integration/data-factory

      Кореневий шлях (не змінюється).

      test-registry

      Службова назва цільового реєстру, вказана у Control Plane.

      resource-name

      Назва ресурсу/ендпоінту, до якого звертатися для отримання даних. Наприклад, /edu-type.
      create sc data source url
      Зображення 4. Запит до БД іншого реєстру за критерієм пошуку з UI-форми користувача

3.3. Отримання токена авторизації зовнішніми системами

Щоб отримати дозвіл на звернення до ресурсів реєстру, зовнішня система має отримати спеціальний токен доступу — JWT-токен. Він призначений для подальшої авторизації зовнішніх систем при взаємодії з реєстрами, що розгорнуті в межах Платформи.

Детальніше дивіться на сторінці Виклик реєстру зовнішньою системою: Отримання JWT-токена у Keycloak.

3.4. Вихідна інтеграція із зовнішніми системами

Якщо необхідно інтегруватися із зовнішнім сервісом, або системою, що знаходиться поза кластером Платформи, використовуйте спеціальний REST-конектор — Connect to external system.

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

3.5. Пов’язані сторінки

Опис функціональності охоплює пов’язані сторінки з документацією. Вони подані списком у цьому розділі для зручності.