Взаимодействие клиента с Системой посредством API Jasper#

API Jasper представляет из себя REST-сервис.

При обращении к API Jasper на запросы возвращаются стандартные HTTP-ответы. Обмен данными осуществляется в формате .xml по xsd-схемам, утверждённым на стороне API Jasper. При этом xml используется внешним интеграционным сервисом только при отправке запроса на выполнении xml-пакета в Системе.

Сами сведения по запросам, содержащие информацию об объектах системы и их состоянии, API Jasper отдаёт в формате .json.

Схема БД: хранение настроек интеграционных систем#

При развёртывании API Jasper на проекте в базе данных для него создаётся отдельная схема jasper: одна схема на один проект, в которой хранится вся необходимая информация, в том числе служебная, о работе API Jasper и внешней интеграционной системе в отдельных таблицах EfCore и IdentityServer.

В таблицы заносится информация о:

  • пользователе, являющимся администратором веб-приложения API Jasper (AspNetUsers);

  • клиентах проекта, зарегистрированных в API Jasper (Clients);

  • операциях, доступных для каждого зарегистрированного клиента (ef_scopes);

  • правах, назначенных на просмотр объектов Системы для каждого зарегистрированного клиента в рамках схемы проекта (ef_reading_rights);

  • маршрутизациях оповещений о событиях в Системе, запрашиваемых клиентом (ef_registrations_endpoints).

Логирование#

Все запросы к API Jasper: кто, когда и какие функции использовал – логируются.

Структурированные логи расположены в папке приложения API Jasper /var/log/gems/api/.

В отдельной таблице БД apiLog логируются тела запросов и ответов при обращении к runpackage.

Для IdentityServer есть отдельный файл логов, расположенный в папке /var/log/gems/api/IdentityServer. В него записывается информация о запросах на получение токена, об авторизованных клиентах и истёкшем сроке действия токена.

Формирование и отправка пакета данных в API Jasper#

  1. Клиент запрашивает у API Jasper xsd-схему, описывающую правила взаимодействия и формирования пакета данных на оправку. Эти же схемы представляют собой права на создание и/или редактирование объектов Cистемы.

  2. Клиент формирует пакет согласно описанию и отправляет его в API Jasper.

  3. API Jasper принимает пакет, проводит его валидацию по xsd-схеме, выполняет требуемые операции согласно структуре пакета и отправляет ответ на запрос клиента.

Схема формирования и отправки пакета данных в API Jasper:

../../_images/shem_api_client.png

Обработка действия кнопки «Отправить»#

Результат услуги, подготовленный в Системе, может быть отправлен клиенту посредством вызова действия кнопки Отправить в карточке объекта. Например, в карточке услуги:

../../_images/knopka_otprav.png

Кнопка Отправить реализована отдельным модулем, подключаемым при установке API Jasper. Запросы, формируемые при нажатии на неё, отправляются через RabbitMQ.

При нажатии на кнопку Отправить внешняя система получает сигнал забрать данные. Клиент получает ключ объекта, который нужно забрать. Валидация осуществляется на стороне клиента.

Клиент должен производить регистрацию данной кнопки для каждого экземпляра объекта, по которому он ожидает получить результат, например, услуги.

Схема отправки результата во внешний интеграционный сервис посредством вызова и обработки действия кнопки Отправить в карточке услуги:

../../_images/shema_vsaimod.png

Организация работы очередей#

Очереди сообщений реализованы с использованием RabbitMQ. В работе API Jasper используются 2 очереди:

  1. Notification_queue – предназначена для хранения сообщений, направляемых в интеграционный сервис из Системы через API Jasper. При нажатии кнопки Отправить в карточке объекта в notification_queue попадает сообщение, содержащее в себе:

    • ключ и тип объекта, из которого была вызвана обработка действия кнопки;

    • URL внешнего интеграционного сервиса. Обработчик сообщений из этой очереди направит по данному адресу сообщение.

  2. Status_queue – предназначена для хранения сообщений (уведомлений), создаваемых внешним интеграционным сервисом. Примером таких сообщений может быть описание текущего состояния некоторого процесса, например, информация об успешно пройденной валидации на стороне интеграционного сервиса.

    Сообщения данной очереди содержат:

    • ключ и тип объекта;

    • краткое описание состояния процесса, по которому было создано сообщение (уведомление).

В дальнейшем обработчик сообщений из этой очереди помещает информацию об описании состояния процесса в отдельное поле объекта Системы.

Количество обработчиков сообщений настраивается, и на обе очереди может смотреть сразу несколько обработчиков, которые делят между собой обработку. Очереди дублируют всю информацию в файловой системе и могут быть перезапущены без потери информации.

Уведомление об изменениях объекта [имитация нажатия кнопки «Отправить» при изменении через Jasper]#

Важно

  • Для отправки уведомления должна быть зарегистрирована кнопка «Отправить».

  • Если объект будет отредактирован через Jasper, это приведёт к нажатию кнопки «Отправить».

В API Jasper можно настроить автоматическое уведомление сторонней системы об изменениях типа объекта.

Для включения функционала необходимо добавить переменные окружения в файл Docker-compose.yml приложения API Jasper в секцию api – environment:

  • FeatureManagement_UseAutoNotificationsThirdPartySystem_EnabledFor_0_Name=AutoNotificationThirdPartySystemFilter

  • FeatureManagement_UseAutoNotificationsThirdPartySystem_EnabledFor_0_Parameters_TypeAliases_0=Alias_типа_объекта

../../_images/uvedomlenieAPI.png

Для уведомления об изменениях нескольких типов нужно добавить дополнительную строку, увеличив последний индекс на 1:

  • FeatureManagement_UseAutoNotificationsThirdPartySystem_EnabledFor_0_Parameters_TypeAliases_1=Alias_ещё_одного_типа_объекта

Важно

Необходимо, чтобы был доступ до «внешней ссылки» из контейнера, для этого можно добавить extra_hosts в docker-compose.yml для блоков api и rabbit:

rabbit:
.....
.....
    extra_hosts:
    - extenal-url.ru:11.11.11.11