Работа с модулем СМЭВ QL

Начало работы со СМЭВ QL сервером

Для начала обозначим основные шаги для начала работы со СМЭВ QL сервером:
  1.   Установка и запуск:
          1.1     Создать приложение;
          1.2     Запустить сервер.

  2.   Корректировка конфигурационного файла:
  3.   Генерация данных:

          3.1     Базовый источник данных или генерация нового источника;
          3.2     Генерация модели из существующей Витрины данных или генерация новой.

  4.   Проверка работы и выполнение запросов.

В данной статье разберем самый частый случай – подключение СМЭВ QL к существующей структуре в Витрине данных.

  1.   Установка и запуск

          1.1     Создание нового приложения – СМЭВ QL сервер:

Первый шаг в работе с СМЭВ QL сервером - создание нового приложения. Для этого используется специальная команда, которая автоматически сформирует базовую структуру приложения:

java -jar smevql-server.jar new myprojectname

где:

• smevql-server.jar – java-архив компонента СМЭВ QL сервер;
• myprojectname – название проекта.

Команда выполняет следующие действия:

• Создает директорию с указанным названием проекта;
• Генерирует шаблонную структуру проекта;
• Формирует исполняемый файл smevql для дальнейшего управления. 

          1.2     Управление сервером

Для запуска СМЭВ QL сервера перейдите в рабочую директорию и выполните команду:

./smevql start -e development

При запуске с ключом -e можно указать окружение:

• development;
• test;
• production.

По умолчанию используется development. Дополнительно выполняется автоматическая проверка конфигурационных файлов и моделей данных.

При необходимости можно использовать следующие команды для остановки и перезапуска сервиса:

# Остановка сервера ./smevql stop # Перезапуск сервера ./smevql restart

   2.   Конфигурационный файл

Далее необходимо скорректировать конфигурационный файл application.yaml и внести значения в блок параметров хранения информации:

storage: # Блок параметров хранения информации   adapter: redis # redis|postgres   pool: # Настройка подключений     - host: ""       port: ""       database: "" # имя БД, используется для адаптера postgres       schema: "" # схема БД, используется для адаптера postgres   max-pool-size: 20 # Максимальный размер пула соединений   user: "" # Пользователь для подключения к redis|postgres   password: "" # Пароль

Рекомендуется настроить подключение к Redis.

  Примечание

Необходимо обязательно перезапускать СМЭВ QL сервер для применения  внесённых настроек следующей командой

Команда для перезапуска сервера:

# Перезапуск сервера ./smevql restart

  3.   Генерация данных 

После создания приложения, автоматически создается файл source.yaml, который и является базовым источником данных, содержащим настройки подключения.
В качестве источника могут быть:

• prostore – витрина данных;
• smevql – другой СМЭВ QL сервер;
• agent – ПОДД-Агент.

Пример источника на основе Prostore:

prostore_source: type: rest version: '1.0' adapter: prostore protocol: http host: smevql-dtm-prostore01.ru-central1.internal port: 9090 path: api/v1/datamarts/query?format=json headers:     - content-type: application/json threads-count: 4 connection-timeout: 30

где:

• prostore_source – уникальное имя для источника данных;
• type – тип интеграционного взаимодействия. На текущий момент поддерживается только rest;
• version – номер версии источника данных. По умолчанию: 1.0;
• adapter – вид источника. Поддерживается: prostore, smevql и agent;
• protocol – указание протокола передачи данных. На текущий момент поддерживается только http;
• host – хост-адрес сервера источника данных;
• port – порт сервера источника;
• path – Endpoint для выполнения запросов. По умолчанию: api/v1/datamarts/query?format=json;
• headers – указание формата данных. По умолчанию: content-type: application/json;
• threads-count – количество параллельных потоков обработки данных. По умолчанию: 4;
• connection-timeout – таймаут подключения. По умолчанию: 30 секунд.

Как упоминалось ранее, базового источника достаточно для преобладающего большинства случаев использования СМЭВ QL сервера.

Для создания нового или дополнительного источника необходимо выполнить команду:

./smevql g source mysourcename

В директории с указанным именем mysourcename создастся новый файл source.yaml, который необходимо скорректировать, указав параметры подключения к предполагаемому источнику данных.

          3.2     Модель данных

Следующим шагом, запускаем генератор модели на основе существующей структуры в Витрине данных:

./smevql schema-gen mymodelname -h localhost -p 9090 -d demo_view

где:

• mymodelname - имя директории, куда будет выгружена модель;
• -h localhost -p 9090 – хост и порт Prostore;
• -d demo_view – существующая витрина данных.

Для подключения существующей структуры к другому ранее созданному источнику, воспользуйтесь командой:

./smevql schema-gen mymodelname -ds mysourcename -d demo_view

где:

• mysourcename – ранее созданный источник данных.

И еще раз обязательно перезапускаем СМЭВ QL сервер для регистрации в системе созданной модели данных.

Теперь все готово для выполнения запросов.

          1)     Служебные запросы

Для проверки работы СМЭВ QL сервера необходимо выполнить GET запрос.

Пример:

curl -X 'GET' 'http://localhost:8080/smevql/api/v1/ping' -H 'accept: plain/text'

где:

• http://localhost:8080 – хост и порт СМЭВ QL сервера;
• /smevql/api/v1/ - префикс для всех роутов;
• ping – API проверки доступности СМЭВ QL сервера.

Пример успешного отклика сервера:

pong

Для проверки настроенных источников воспользуйтесь следующим GET-запросом:

curl -X 'GET' 'http://localhost:8080/smevql/api/v1/sources' -H 'accept: application/json'

где:

• sources – API для получения массива с настроенными источниками данных.

Для проверки настроенных моделей воспользуйтесь следующим GET-запросом:

curl -X 'GET' 'http://localhost:8080/smevql/api/v1/model' -H 'accept: application/json'

где:

• model – API для получения массива с настроенными моделями.

          2)     Пользовательские запросы

Запросы к серверу выполняются методом POST и содержат в теле JSON-объект, состоящий из обязательных блоков: Query и Credentials.

Пример:

{   "query": {       "ticket": {       "conditions": {           "phone": "(347) 246-53-00"       },       "attributes": [           "id",           "price"       ]     }   },   "credentials": {     "system": {       "mnemonic": "3fa45f64-5717-4562-b3fc-2c963f66afa6",       "instance_id": "3fa45f64-5717-4562-b3fc-2c963f66afa6",       "user_id": "3fa45f64-5717-4562-b3fc-2c963f66afa6"     },     "request": {       "id": "6fa45f64-5717-4562-b3fc-2c963f66afa6",       "sub_id": "7fa45f64-5717-4562-b3fc-2c963f66afa6",       "name": "query",       "purpose_id": "8fa45f64-5717-4562-b3fc-2c963f66afa6",       "audit": true,       "audit_id": "9fa45f64-5717-4562-b3fc-2c963f66afa6",       "audit_token": "b3fc"     },     "signature": {       "digest": "digest",       "signature": "signature"     }   } }

где:

• query – атрибут запроса данных внутри указывается название сущности, данные которой нужно получить.
• conditions – указывается условие фильтрации записей (опционально):
          –>     правила задания условий:
               –     Объединение условий только по and;
               –     Операции сравнения:
                    a)     = (по умолчанию);
                    b)     >;
                    c)     >=;
                    d)     <;
                    e)     <=;
                    f)     in.
               –     Условия сравнения применимы к численным типам, датам, временам и таймштампам.
          –>     варианты определения условий фильтрации:
               –     Простое равенство – "name": "Ivan";
               –     Сравнение краткое – "area": [">","130"];
               –     Сравнение полное – «area»: {«op»: «>», «value»: «130»};
               –     Комплексное условие – "area": [">","130"], "floor": ["in", [1, 2]];
               –     Применение OR (ИЛИ) – "name": "Ivan", "or": [{"vin": "в1"}, {"vin2": "в2", "car": "bmw"}.
• fetch – опциональный блок условий, в котором указываются:
               –     условия сортировки (order);
               –     условия выбора страниц (page);
               –     условия выборки доступных для каждого ресурса событий машины состояния (show_events);
               –     применение локализованных переменных (localize);
               –     условия выбора версии данных на указанную дату, диапазон дат, дельту, диапазон дельт (for_system_time, for_system_time_started, for_system_time_finished).
• attributes – атрибуты, значения которых необходимо получить при выполнении запроса;
• credentials – объект, содержащий общие данные запроса, и информация о потребителе;
• mnemonic – мнемоника системы. Указана в файле credentials.yaml в рабочей директории СМЭВ QL сервера;
• instance_id – идентификатор экземпляра системы. Указан в файле credentials.yaml в рабочей директории СМЭВ QL сервера;
• user_id – самостоятельно сгенерированный идентификатор пользователя;
• request – объект описывает общие параметры запроса;
• id – идентификатор запроса;
• sub_id – идентификатор подзапроса;
• name – имя запроса;
• purpose_id – идентификатор события, инициировавшего запрос;
• audit – возможность аудита;
• audit_id – идентификатор аудита. Заполняется только, если audit = true;
• audit_token – токен аудита. Заполняется только, если audit = true;
• signature – Объект, описывает параметры ЭЦП;
• digest – дайджест подписи (не заполняется);
• signature – подпись (не заполняется).

Приведем пример POST-запроса для получения данных:

curl -X 'POST' 'http://localhost:8080/smevql/api/v1/data' -H 'accept: application/json' -H 'Content-Type: application/json' -d '{   "query": {       "ticket": {       "conditions": {},       "attributes": [           "id",           "price"       ]     }   },   "credentials": {     "system": {       "mnemonic": "3fa45f64-5717-4562-b3fc-2c963f66afa6",       "instance_id": "3fa45f64-5717-4562-b3fc-2c963f66afa6",       "user_id": "3fa45f64-5717-4562-b3fc-2c963f66afa6"     },     "request": {       "id": "6fa45f64-5717-4562-b3fc-2c963f66afa6",       "sub_id": "7fa45f64-5717-4562-b3fc-2c963f66afa6",       "name": "query",       "purpose_id": "8fa45f64-5717-4562-b3fc-2c963f66afa6",       "audit": false,       "audit_id": "9fa45f64-5717-4562-b3fc-2c963f66afa6",       "audit_token": "b3fc"     },     "signature": {       "digest": null,       "signature": null     }   } }'

где:

• data - API для получения данных.

Пример успешного ответа:

{     "response": {         "ticket": [             {                 "price": 298.8082301905419,                 "id": "3424f5b3-e337-4d0d-a046-a1c491ab3300"             },             {                 "price": 67.79323025646744,                 "id": "ad14fce2-04f5-45b8-b430-3ff9efb5d4ca"             }         ]     },     "credentials": {         "system": {             "mnemonic": "3fa45f64-5717-4562-b3fc-2c963f66afa6",             "instance_id": "4fa45f64-5717-4562-b3fc-2c963f66afa6",             "user_id": "5fa45f64-5717-4562-b3fc-2c963f66afa6"         },         "request": {             "id": "6fa45f64-5717-4562-b3fc-2c963f66afa6",             "sub_id": "7fa45f64-5717-4562-b3fc-2c963f66afa6",             "name": "query",             "purpose_id": "8fa45f64-5717-4562-b3fc-2c963f66afa6",             "audit": false,             "audit_id": "9fa45f64-5717-4562-b3fc-2c963f66afa6",             "audit_token": "b3fc"         },         "signature": {             "digest": null,             "signature": null         },         "response": {             "id": "ec26f676-5931-11ee-9044-eb1795d841ef",             "sub_id": "ec26f677-5931-11ee-9044-eb1795d841ef",             "started_at": "2023-09-22 13:22:24.456 +0300",             "finished_at": "2023-09-22 13:22:24.530 +0300"         }     } }

где:

• response – объект с описанием ресурсов, содержащих массивы данных запросов;
• resourse_data – массивы данных, запрашиваемых ресурсов (имя объекта).