Налаштування емуляторів зовнішніх інтеграцій

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

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

Ви можете налаштувати емулятори (моки) для інтеграцій із зовнішніми системами через SOAP або REST в адміністративній панелі Control Plane за допомогою WireMock.

whats new 1 9 5 2

Основні Особливості:

  • 🔄 Підтримка SOAP та REST: емуляції можуть бути створені для обох протоколів — SOAP і REST, що дає більшу гнучкість при роботі з різними зовнішніми системами.

  • 🔧 Керування через Control Plane: активація та керування моками здійснюється через адміністративну панель Control Plane в рамках -dev-шаблонів реєстру.

  • 🛠️ WireMock — потужний інструмент для тестування: WireMock є симулятором HTTP-серверів, який дозволяє створювати моки HTTP-взаємодій. Це зручний інструмент для імітації роботи зовнішніх API та сервісів.

  • 📁 Кастомізація моків через mock-integrations: ви можете задати структуру моків на рівні регламенту реєстру, використовуючи директорію mock-integrations.

Сценарії використання:

  • 🧪 Тестування: створюйте модульні (unit) та інтеграційні тести з використанням WireMock для емуляції зовнішніх API й сервісів.

  • 💻 Розробка: якщо реальний сервіс ще не готовий або тимчасово недоступний, WireMock допоможе імітувати його поведінку, що дозволить продовжувати розробку без перерв.

  • 🔍 Відтворення помилок: використовуйте WireMock для моделювання різних станів та помилок HTTP-сервісів, що допоможе в глибшому розумінні та розв’язанні проблем.

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

2. План дій з використання емуляторів зовнішніх інтеграцій

3. Активація емуляторів зовнішніх інтеграцій

Ви можете увімкнути використання емуляторів при налаштуванні зовнішніх інтеграцій в інтерфейсі адміністративної панелі Control Plane, зокрема під час:

Активуйте перемикач Використати мок зовнішньої інтеграції для відповідного типу взаємодії.

whats new 1 9 5 2
Зображення 1. Увімкнення емуляторів взаємодії з реєстрами через ШБО "Трембіта"
mock integrations 1
Зображення 2. Увімкнення емуляторів взаємодії з іншими системами

4. Визначення шаблонів емуляторів у регламенті

Налаштування шаблонів емуляцій зовнішніх інтеграцій визначається на рівні Gerrit-репозиторію регламенту вашого реєстру, у директорії mock-integrations. Шаблони мають бути визначеними згідно з конвенціями WireMock у форматі JSON.

Файли налаштування шаблонів моків у структурі регламенту реєстру
Зображення 3. Файли налаштування шаблонів моків у структурі регламенту реєстру

4.1. REST

Шаблони у WireMock можна розділити на дві основні частини:

  1. Request Matching — визначає, які HTTP-запити повинні бути перехоплені. Ви можете вказати URL, метод (GET, POST тощо), заголовки, тіло запита тощо.

  2. Response Definition — визначає, як повинна виглядати відповідь, яка повертається на співставлений запит. Тут можна вказати статус код, заголовки, тіло відповіді тощо.

Приклад шаблону WireMock у форматі JSON:
{
  "request": {
    "method": "GET",
    "urlPathPattern": "/some/endpoint"
  },
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "jsonBody": {"key": "value"}
  }
}

Цей шаблон вказує на те, що коли WireMock отримує GET запит на URL /some/endpoint, він повинен повернути відповідь зі статус-кодом 200, заголовком Content-Type встановленим як application/json, та тілом відповіді у форматі {"key":"value"}.

4.2. SOAP

WireMock також може бути використаний для мокування SOAP вебсервісів. SOAP (Simple Object Access Protocol) є протоколом для обміну повідомленнями між застосунками через HTTP, і, на відміну від REST, використовує формат XML для структуризації даних.

Коли ви мокуєте SOAP-сервіс за допомогою WireMock, ви зазвичай хочете створити моки для SOAP запитів і відповідей, які вони отримують. Ось приклад того, як може виглядати конфігураційний файл WireMock для мокування SOAP-вебсервісу:

Шаблон мокування SOAP-вебсервісу
{
  "request": {
    "method": "POST",
    "url": "/soap-endpoint",
    "headers": {
      "Content-Type": "text/xml; charset=utf-8"
    },
    "bodyPatterns": [
      {
        "matchesXPath": "//your-xpath-expression"
      }
    ]
  },
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "text/xml; charset=utf-8"
    },
    "body": "<your-soap-response-xml>"
  }
}

У цьому прикладі WireMock налаштований так, що коли він отримує POST-запит на URL /soap-endpoint з відповідними заголовками та тілом, яке відповідає заданому XPath-виразу, він повертає відповідь зі статус-кодом 200 та XML-вмістом як тіло відповіді.

Важливо підготувати правильний XML-вміст для тіла SOAP-відповіді й, за потреби, використовувати XPath для зіставлення елементів у тілі SOAP-запита.

Імітація поведінки SOAP-сервісу при запитах на ендпоінт SearchSubjects
{
  "mappings": [
    {
      "priority": 100,
      "request": {
        "method": "POST",
        "bodyPatterns": [
          {
            "matchesXPath": "//*[local-name()='serviceCode'][text()='SearchSubjects']"
          }
        ]
      },
      "response": {
        "status": 200,
        "body": "<soap11env:Envelope xmlns:soap11env=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:tns=\"http://nais.gov.ua/api/sevdeir/EDR\" xmlns:xroad=\"http://x-road.eu/xsd/xroad.xsd\" xmlns:id=\"http://x-road.eu/xsd/identifiers\">\n   <soap11env:Header>\n      <tns:AuthorizationToken>token</tns:AuthorizationToken>\n      <xroad:userId>MDTUDDM</xroad:userId>\n      <xroad:client id:objectType=\"SUBSYSTEM\">\n         <id:xRoadInstance>SEVDEIR-TEST</id:xRoadInstance>\n         <id:memberClass>GOV</id:memberClass>\n         <id:memberCode>43395033</id:memberCode>\n         <id:subsystemCode>IDGOV_TEST_01</id:subsystemCode>\n      </xroad:client>\n      <xroad:service id:objectType=\"SERVICE\">\n         <id:xRoadInstance>SEVDEIR-TEST</id:xRoadInstance>\n         <id:memberClass>GOV</id:memberClass>\n         <id:memberCode>00015622</id:memberCode>\n         <id:subsystemCode>2_MJU_EDR_prod</id:subsystemCode>\n         <id:serviceCode>SearchSubjects</id:serviceCode>\n      </xroad:service>\n      <xroad:protocolVersion>4.0</xroad:protocolVersion>\n      <xroad:id>MDTUDDM</xroad:id>\n      <xroad:requestHash algorithmId=\"http://www.w3.org/2001/04/xmldsig-more#gost34311\">kfkfkjkfjkjkfjkfjkjokojkkjlkjkjlkjdlkjljkdlk=</xroad:requestHash>\n   </soap11env:Header>\n   <soap11env:Body>\n      <tns:SearchSubjectsResponse>\n         <tns:SubjectList/>\n      </tns:SearchSubjectsResponse>\n   </soap11env:Body>\n</soap11env:Envelope>",
        "headers": {
          "Content-Type": "text/xml"
        }
      }
    }
]
}

Цей шаблон створюється за допомогою WireMock та використовується для імітації вебсервісу, який обробляє SOAP-запити.

Працює це наступним чином:

  1. request — визначає критерії, яким SOAP-запит має відповідати, щоб бути перехопленим. У нашому прикладі шаблон шукає POST-запити, тіло яких відповідає такому XPath-виразу:

    "//*[local-name()='serviceCode'][text()='SearchSubjects']"

    Це означає, що запит буде перехоплений, якщо він містить елемент з локальним ім’ям 'serviceCode' та текстом 'SearchSubjects'.

  2. response — визначає відповідь, яку WireMock поверне, коли він знайде вхідний запит, що відповідає шаблону. У цьому випадку він повертає HTTP-відповідь зі статус-кодом 200, заголовком Content-Type: text/xml та специфічним XML-тілом, яке є відповіддю на SOAP-запит.

  3. SOAP Envelope є базовим елементом повідомлення в SOAP (Simple Object Access Protocol) і визначає, що повідомлення є SOAP-повідомленням. Він містить інформацію, яку потрібно передати між клієнтськими та серверними застосунками.

    SOAP-повідомлення повинно містити Envelope із наступною структурою:

    Структура базового SOAP-повідомлення
    <soap11env:Envelope
    xmlns:soap11env="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:tns="http://nais.gov.ua/api/sevdeir/EDR"
    xmlns:xroad="http://x-road.eu/xsd/xroad.xsd"
    xmlns:id="http://x-road.eu/xsd/identifiers">
    <soap11env:Header>
        <!-- Заголовок -->
    </soap11env:Header>
    <soap11env:Body>
        <!-- Тіло -->
    </soap11env:Body>
</soap11env:Envelope>

    • Envelope — це кореневий елемент повідомлення SOAP, що обгортає усю інформацію, яка передається.

    • Header (Заголовок) — необов’язковий елемент, який містить додаткову інформацію (метадані), яка може бути необхідна для обробки повідомлення. У нашому випадку заголовок містить елементи для авторизації, ідентифікації користувача, клієнта, сервісу тощо.

    • Body (Тіло) — містить фактичні дані, які передаються. Це єдиний обов’язковий елемент SOAP Envelope. У нашому випадку тіло містить відповідь з елементом SearchSubjectsResponse.

      Також слід звернути увагу на атрибути з оголошеннями просторів імен (xmlns), які визначають простори імен для різних частин повідомлення і використовуються для того, щоб уникнути конфліктів між елементами з однаковими іменами, але з різних джерел.

5. Створення роута для сервісу та використання WireMock

В результаті вищезазначених дій, створиться под сервісу wiremock. Тепер ви можете взаємодіяти із колекцією API WireMock двома шляхами:

Створіть новий роут для цього сервісу вручну. Для цього виконайте наступні кроки:

  1. Увійдіть до OpenShift-консолі, у секції Projects знайдіть проєкт вашого реєстру.

  2. Перейдіть до Networking > Routes та створіть новий роут натисканням кнопки Create Route.

  3. У новому вікні оберіть Configure via > Form view.

  4. У полі Name вкажіть унікальну назву для роута у проєкті вашого реєстру. Наприклад, test-wiremock-route.

  5. У полі Hostname вкажіть ім’я хосту, на якому розгортатиметься роут. Наприклад, test-wiremock-route.apps.1-9-6-1.mdtu-ddm.projects.epam.com.

    Це публічне ім’я хосту для роута. Ви можете лишити поле порожнім — в такому разі система згенерує hostname автоматично.

  6. У полі Path вкажіть шлях, за яким роутер маршрутизує трафік до сервісу. Наприклад, /.

  7. У полі Service оберіть под сервісу зі списку доступних — wiremock.

  8. У полі Target port вкажіть цільовий порт, на якому потрібно дозволити трафік. Оберіть опцію 9021→9021 (TCP).

  9. Визначте налаштування безпеки для з’єднання. Маршрути можна захистити за допомогою кількох типів TLS-термінації.

    Що таке TLS termination?

    TLS termination (завершення TLS) в OpenShift належить до процесу дешифрування TLS шифрованого трафіку на певному рівні у структурі вашого сервісу та використовується для захисту комунікації між клієнтами та серверами.

    OpenShift використовує концепцію "роутів" для експонування сервісів на зовнішній мережі. Роут дозволяє вам визначати, як зовнішні запити повинні транслюватися на сервіси всередині кластера.

    При створенні роута в OpenShift, ви можете вказати, де саме має відбуватися TLS-термінація:

    • Edge Termination: завершення TLS відбувається на рівні роута. Це означає, що OpenShift розшифровує трафік, перш ніж він потрапляє до вашого застосунку. Після розшифрування, трафік може бути переданий до застосунку як незашифрований або повторно зашифрований.

    • Passthrough Termination: з OpenShift не втручається у шифрування, і TLS трафік проходить через роут без змін. Завершення TLS відбувається на рівні застосунку або сервісу.

    • Re-encrypt Termination: це комбінація Edge та Passthrough. Завершення TLS відбувається на роуті, а потім трафік шифрується знову перед передачею до застосунку. Це може бути корисним, якщо ви хочете використовувати різні сертифікати для зовнішньої та внутрішньої комунікації.

  10. У полі Insecure traffic визначте політику для трафіку типу HTTP. Доступні опції:

    • None

    • Allow

    • Redirect

  11. Натисніть Create та збережіть зміни. В результаті роут емуляцій зовнішньої взаємодії буде додано до списку доступних у проєкті вашого реєстру.

    mock integrations 2

  12. Перейдіть за посиланням до відповідного сервісу wiremock.

    mock integrations 3

    Обов’язково додайте ендпоінт /__admin/webapp у кінці URL сервісу, щоб уникнути помилки 403 Forbidden.

    mock integrations 4

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

    mock integrations 5

    Ознайомтеся із можливостями WireMock в офіційній документації продукту.

6. Тестування API за допомогою Postman

Ви можете використовувати колекцію моків через з’єднання із подом сервісу wiremock та використовувати API WireMock при тестуванні сценаріїв інтеграційної взаємодії.

Для цього вам може знадобитися Postman — інструмент для розробки та тестування API. За потреби, ви можете використовувати будь-який альтернативний варіант.

Також встановіть OpenShift CLI — утиліта командного рядка, яка надає доступ до управління та взаємодії з кластером OpenShift.

  1. Увійдіть до OpenShift-консолі.

  2. У правому верхньому куті інтерфейсу натисніть на користувача — <ваше ім’я> та скопіюйте команду для входу через oc cli — Copy login command.

  3. Натисніть Display Token та скопіюйте команду у полі Log in with this token. Команда може виглядати так:

    oc login --token=sha256~kjshdfhfdj_jnksdjnfksdnf-KMCZ0vMR2Y --server=https://api.1-9-6-1.mdtu-ddm.projects.epam.com:6443

  4. Відкрийте термінал або консоль на вашій операційній системі та вставте скопійовану команду для входу.

    Таким чином ви зможете взаємодіяти як адміністратор з OpenShift через oc cli.

  5. Налаштуйте переадресацію портів (port forwarding) із поду сервісу wiremock на вашу локальну машину. Для цього у терміналі виконайте наступну команду:

    Приклад 1. Переадресація портів для з’єднання з подом сервісу wiremock
    oc port-forward wiremock-644c996b78-5ftrx 9021:9021 -n abc-01

    • wiremock-644c996b78-5ftrx — назва поду із сервісом wiremock у проєкті вашого реєстру.

    • 9021:9021 — порти для переадресації.

      • Перший порт (9021 перед двокрапкою) — це порт на вашій локальній машині. За замовчуванням — це порт 9021. Ви можете обрати будь-який вільний порт.

      • Другий порт (9021 після двокрапки) — це порт на цільовому поді (wiremock-644c996b78-5ftrx) у просторі імен abc-01.

      Як перевірити список відкритих портів на локальній машині?

      Перевірити список відкритих портів на вашій машині можна за допомогою команди (для Windows):

      netstat -ano

      Ця команда відобразить список усіх активних TCP-з’єднань, їх портів та PID (Process ID) процесів, що використовують ці з’єднання.

      Якщо ви хочете перевірити конкретний порт, ви можете додати його в команду netstat з ключем findstr. Наприклад, щоб перевірити, чи вільний порт 8080, ви можете виконати наступну команду:

      netstat -ano | findstr 8080

      Якщо команда нічого не виводить, це означає, що порт 8080 вільний.

    • abc-01 — назва вашого реєстру.

    mock integrations 6

  6. Відкрийте застосунок Postman та створіть нову колекцію. Ви можете назвати її Wiremock, як приклад.

  7. Створіть новий GET-запит та надішліть його на ендпоінт http://localhost:9021/__admin/mappings. Таким чином, ви отримаєте список усіх доступних моків у сервісі wiremock, передбачених структурою вашого регламенту.

    mock integrations 7

  8. Надалі створюйте нові запити для перевірки заданих у моках правил та сценаріїв взаємодії із зовнішніми сервісами та системами.

7. Використання інтеграційних конекторів у бізнес-процесах

Після активації моків у Control Plane та налаштування шаблонів mock-integrations у регламенті, ви можете моделювати інтеграційну взаємодію у бізнес-процесах за допомогою відповідних SOAP та REST-конекторів.

Детальніше про інтеграційні конектори ви можете переглянути сторінках:

© 2023 Платформа Реєстрів.