6. Функции СМЭВ QL Сервера

6.1. Администрирование и конфигурирование

6.1.1. Создание СМЭВ QL Сервера

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

Таблица 6.2 Настраиваемые параметры

Параметр

Описание

Где задается

app name

Имя создаваемого экземпляра СМЭВ QL сервера. Параметр является обязательным для заполнения

в командной строке: java -jar smevql-server-all.jar new <new-app-name>

Предварительное состояние:

  1. Развернут дистрибутив СМЭВ QL сервер.

  2. Запущена консоль утилиты для работы со СМЭВ QL.

Результирующее состояние:

  1. Создана первичная структура папок и файлов СМЭВ QL.

  2. Ошибка выполнения команды.

Сценарий выполнения

  1. Администратор сервера в консоли вводит команду создания нового экземпляра СМЭВ QL с указанием имени:

java -jar smevql-server-all.jar new <new-app-name>

  1. Система выполняет создание экземпляра СМЭВ QL сервера с заданным именем:

  • если во время выполнения команды возникла ошибка, то сценарий завершается с результирующим состоянием 2;

  • иначе, команда выполнена успешно, создана первичная структура папок и файлов, завершение сценария с результирующим состоянием 1.

Результирующее состояние:

  1. СМЭВ QL сервер успешно запущен, создана первичная структура папок и файлов.

  2. Ошибка выполнения команды.

Первичная структура папок и файлов

Таблица 6.3 Первый уровень вложенности корневой папки smevql

Название

Тип

Описание

Уровень вложенности

application.yaml

yaml-file

Файл с описанием настроек СМЭВ QL сервер (Раздел 2.2.6.1)

1

credentials.yaml

yaml-file

Файл с описанием представления СМЭВ QL сервер (Раздел 2.2.6.1)

1

logs

folder

Папка с лог-файлами СМЭВ-QL сервер

1

models

folder

Папка с описанием моделей данных

1

readme.md

md-file

read-файл в формате markdown, описывает основные функции СМЭВ QL

1

smevql.jar

jar-file

Jar-файл с кодом СМЭВ QL

1

sources

folder

Папка с описанием источников данных

1

states

folder

Папка с описанием машин состояний

1

openapi.yaml

yaml-file

Файл с первичной спецификацией Open API СМЭВ QL

1
Таблица 6.4 Содержимое папки models

Название

Тип

Описание

Уровень вложенности

base

folder

Папка с версиями описания структуры базовой модели данных

2

current (symlink)

symlink

Ссылка на папку модели по умолчанию

3

1.0

folder

Папка с версией базовой модели данных

3

model

yaml-file

Файл с описанием базовой модели данных

4

Содержимое папки sources

По умолчанию, пустая папка, содержимое заполняется в процессе создания моделей источников.

Таблица 6.5 Содержимое папки logs

Название

Тип

Описание

Уровень вложенности

environment_name.log

log-file

Лог-файл СМЭВ QL

2

Содержимое папки states: по умолчанию, пустая папка, содержимое заполняется в процессе создания машин-состояний.

6.1.2. Конфигурирование СМЭВ-QL сервер

Пример конфигурации файла application.yml для СМЭВ QL сервера см. в разделе Раздел 2.2.6.1 Руководства администратора.

6.1.3. Запуск, остановка, перезапуск приложения СМЭВ QL сервер

Примеры команд и их описание приведено в Раздел 3.6.1.

6.1.4. OpenAPI СМЭВ-QL

6.1.4.1. Общее описание

Обращение потребителей данных или иных внешних систем к СМЭВ QL серверу происходит путем вызова REST-методов. Первичная спецификация Open API СМЭВ QL сервера поставляется в исходном дистрибутиве, которая в дальнейшем может обновляться на основании модели данных и модели машины-состояний.

Спецификация Open API хранится в файловой системе СМЭВ QL сервера по пути: smevql/openapi.yaml

6.1.4.2. Описание спецификации

Таблица 6.6 Описание спецификации

Группа

Метод

Назначение

States

(работа с моделью машины состояний)

GET/states

Получить описание всех моделей машин состояний

GET/states/{model}

Получить описание конкретной модели машины состояний

POST/states/{model}/{event}

Изменить статус (состояние) машины состояний. Спецификация метода строится на основании заполненной карты машины состояний.

Model

(работа с моделью данных)

GET/model

Получить описание всех моделей данных

GET/model/{model}

Получить описание конкретной модели данных

GET/model/{model}/{version}

Получить описание конкретной версии модели данных

GET/server/indexes/required

Получить список рекомендованных для создания индексов полей. Строится на используемых в связях моделей (connections) и блоке conditions.allowed моделей

Sources

(работа с моделью источников)

GET/sources

Получить описание модели источников

Data

(работа с данными поставщика)

GET/data/{token}

Запрос данных в асинхронном режиме по токену

GET/certificaties

Получить сертификат для проверки цифровой подписи на стороне клиента

POST/data

Ключевой запрос получения данных поставщика. Схема запроса по умолчанию не содержит объекты витрины, а обновляется отдельной процедурой на основании заполненной модели данных (Раздел 2.3.5.2.4).

POST/regulated-query

Выполнение СМЭВ QL РЗ

Push

(управление рассылками на изменения данных витрины)

POST/push/consumer/create

Зарегистрировать нового потребителя на получение уведомлений при изменении данных витрины

GET/push/consumer

Получить список всех потребителей, зарегистрированных на получение уведомлений при изменении данных витрины

GET/push/consumer/resources/{agent_target}

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

GET/push/consumer/agent_targets/{resource}

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

POST/push/consumer/delete/resource

Удалить отслеживание изменений конкретного ресурса для заданного потребителя

POST/push/consumer/delete/

Удалить отслеживание изменений всех ресурсов для заданного потребителя

Прочие служебные методы

GET/ping

Проверить сетевую доступность СМЭВ QL сервер

События

POST/in-event

Зарегистрировать новое событие

Подробное описание всех эндпоинтов в Раздел 2.2.6.5.

6.1.4.3. Обновление OpenAPI на основании изменений модели данных

Для применения изменений модели (или применения новой модели) данных в Open API СМЭВ QL необходимо выполнить следующие действия:

  1. Администратор системы выполняет команду запуска или перезапуска приложения (подробнее см. Раздел 3.6.1)

  2. Система определяет актуальную версию модели (старшая по номеру или версия явно указанная в current symlink).

  3. Система дополняет схемы OpenAPI атрибутами из модели.

  4. Система сохраняет обновленные данные Open API только в оперативной памяти (локальный файл openapi.yaml не меняется).

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

  1. Администратор системы выполняет в консоли команду генерации OpenAPI:

yaml g openapi model

  1. Система определяет актуальную версию модели данных (старшая по номеру или версия явно указанная в current symlink)

  2. Система дополняет схемы OpenAPI атрибутами из модели.

  3. Система обновляет локальный файл openapi.yaml.

6.1.5. Регистрация OpenAPI СМЭВ QL в СМЭВ4

Для возможности использования СМЭВ QL сервер, необходимо выполнить регистрацию OpenAPI в СМЭВ4 через ЕИП НСУД и выдать права доступа потребителям на выполнение запросов вида - Обмен с использованием регламентированных запросов типа «Rest-сервис» в системе ЛК УВ.

При регистрации REST-интерфейса потребуется указать следующие ключевые атрибуты:

  1. Мнемоника информационной системы поставщика данных.

  2. Указание префикса url REST-интерфейса СМЭВ QL сервер, например: smevql/api/v1

  3. Приложить заполненный файл openapi.yaml (Раздел 2.3.5.3.1.4)

6.2. Работа с моделями

6.2.1. Создание базовой модели

6.2.1.1. Общее описание

Базовая модель данных автоматически генерируется при создании СМЭВ QL и не должна редактироваться вручную.

Базовая модель служит для унификации описания типов данных и позволяет значительно сокращать описание атрибутов ресурса в модели данных (Модель данных).

Пример описания атрибута в модели данных без применения базовой модели:

id:
  name: Идентификатор
  type:
    - string
    - STRING
  length: 0
  nullable: null
  key: NONE

Пример описания атрибута в модели данных c применением базовой модели:

id: *ds

6.2.1.2. Общий сценарий выполнения

  1. Администратор сервера в консоли вводит команду создания экземпляра СМЭВ QL сервер:

java -jar smevql-server-all.jar new (new-app-name)

  1. Система создаёт новую версию папки и файла базовой модели с заполненным содержимым - model.yaml

Создание базовой модели

Рисунок - 6.1 Создание базовой модели

6.2.1.3. Описание базовой модели

default_string: &ds
  name: Строка
  type:
      - string
      - STRING
  length: 0
  nullable: NULL
  key: NONE
  source: NONE

default_number: &dn
  name: Число
  type:
      - integer
      - INTEGER
  length: 0
  nullable: NULL
  key: NONE
  source: NONE

primary_key: &pk
  name: Ключ
  type:
      - string
      - STRING
  length: 0
  nullable: NULL
  key: PRIMAY
  source: NONE

static_value: &sv
  name: Статическое значение
  type:
      - string
      - STRING
  length: 0
  nullable: NULL
  key: NONE
  source: STATIC //зарезервированное значение
  default_value: Значение //статическое значение без извлечения

env_value: &ev
  name: Значение из окружения
  type:
      - string
      - STRING
  length: 0
  nullable: NULL
  key: NONE
  source: ENV //зарезервированное значение
  default_value: Значение если нет переменной окружения
  env_key: ключ_переменной_окружения

base_model: &base_model
default_fields: &default_fields

6.2.2. Генерация модели данных

6.2.2.1. Общее описание

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

6.2.2.2. Сценарий выполнения

  1. Администратор сервера в консоли вводит команду генерации новой модели данных с обязательным указанием названия модели:

./smevql g model <model-name>

  1. Система проверяет, что имя модели уникально:

    1. если имя модели не уникально (модель данных с таким именем уже существует в файловой системе СМЭВ QL), то Система выводит соответствующее сообщение об ошибке.

    2. иначе, имя модели уникально, переход к выполнению следующего шага.

  2. Система создаёт папку с указанным наименованием и файл model.yaml

  3. Далее Администратор сервера вручную заполняет модель данных требуемыми значениями.

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

./smevql schema-gen -ds <source-name> -d <model-name>

Без указания параметра -ds будет формироваться модель на основе источника с названием Prostore.

6.2.2.3. Описание модели данных

Элемент модели

Описание

Пример

  • name:

Название модели данных

smevql

version:

Номер версии модели данных

1.0

resources:

Описание ресурсов модели данных

Пример блока resources

<resource_name>: *base_model

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

name:

Название ресурса на русском языке

description:

Дополнительное описание ресурса, обычно указывается его бизнес-смысл

fields:

Список полей ресурса. Для каждого поля указывается:

  • название поля;

  • тип данных (возможные типы данных определены в

Раздел 2.3.5.2.3);

  • опционально источник данных (source) в том случае, если он отличается от источника данных всего ресурса;

  • опционально ограничение на вывод данного поля в результатах запроса (Пример блока fields:).

connections:

Описание связей между ресурсами по заданным ключам

Пример блока connections

belongs_to:

has_many:

conditions:

Описание ограничений на использование полей в пользовательских запросах

Пример блока conditions

allowed:

Если заполнено, то поиск разрешен только по этим полям и полям с ключами

denied:

Если заполнено, то поиск запрещен по этим ключам

always:

Наличие условий в блоке always должно ко всем запросам ресурса добавлять эти условия, если указаны в запросе, то перетирать

extract:

Указание источника данных для ресурса

Пример блока extract

name:

Название (мнемоника) источника данных

table:

Название таблицы в схеме БД источника

conditions:

Массив условий применения источника на основании значений полученных в запросе атрибутов.

Все условия внутри источника действуют через логическое И (AND).

Если запрос подходит под два и более источников , то данные извлекаются и объединяются из всех подходящих.

Пример блока conditions

fetch:

Режим получения данных (синхронный или асинхронный). Содержит атрибуты:

  • policy - режим работы, поддерживается режимы sync | async | async_on_timeout (значение по умолчанию sync);

  • timeout - таймаут получения данных клиента (значение по умолчанию PT20S);

  • store_timeout - время хранения временных данных для асинхронного режима работы (значение по умолчанию PT15M);

  • retries - число попыток получения данных (значение по умолчанию 1).

Пример блока fetch

6.2.2.4. Пример блока fields

fields:
    <<: *default_fields
    first_name: *ds
    last_name:
        <<: *ds
        guard: [last_name]
    snils:
        <<: *ds
        guard: [last_name first_name snils]

6.2.2.5. Пример блока resources

resources:
# slots — техническое название модели, по нему производятся все связи
- slots: *base_model
# значение name — название модели на русском языке
    name: Слоты
# description - дополнительное описание ресурса
    description: таблица с указанием доступных и занятых временных интервалов
# fields — список полей модели
    fields:
# список полей может включать перечень полей из default_fields
    <<: *default_fields
# поля по-умолчанию наследуются от ds (default_string) из базовой модели
    id: *ds
    resource_id: *ds
# у поля может быть переопределен source (по-умолчанию у каждого поля источник всей модели)
    type: *ds
        source:
        field: tag_type
    age: *ds
        source:
        field: tag_age
    visitTime: *ds
    duration: *ds
    status: *ds
    create_ts: *ds
    update_ts: *ds
    update_ts: *ds

6.2.2.6. Пример блока connections

connections:
  belongs_to:
    - resource:
        primary_key: [ id ]
        foreign_key: [ resource_id ]
  has_many:
    - book:
        primary_key: [ id ]
        foreign_key: [ slot_id ]
    - unaccessible_period:
        primary_key: [ resource_id, type ]
        foreign_key: [ resource_id, type ]

6.2.2.7. Пример блока conditions

conditions:
    allowed: [id, name] # если заполнено, то поиск разрешен только по этим полям и полям с ключами
    denied: [snils] # если заполнено, то поиск запрещен по этим ключам
    always: # наличие условий в блоке always должно ко всем запросам ресурса добавлять эти условия, если указаны в запросе, то перетирать
    - region: ["=", "77"]
    - blocked: ["=", true]

6.2.2.8. Пример блока extract

extract:
  source:
  - name: prostore
    table: misdm.slots

6.2.2.9. Пример блока conditions

extract:
  source:
    - name: prostore1
      table: misdm.slots
      conditions:
        # попадание в промежуток
        - range:
            field: age
            from: 0
            to: 2
        - eq:
            field: color
            not: "blue"
    - name: prostore2
      table: misdm.39slots
      conditions:
        # ограничения по (не)равенству
        - eq:
            field: resource_id
            is: 1
    - name: prostore3
      table: misdm.39slots
      conditions:
        # ограничения по наличию в источнике
        - eq:
            field: snils
            extract:
            source: redis
            table: default_table
            key: resource_hashed_id
            algorithm: md5
            # select count(*) > 0 from offices.offices where resource_hashed_id = ?
            # параметр: md5(snils)
            is: true
    - name: prostore_default
      table: misdm.39slots
      conditions:
        - fallback: true

6.2.2.10. Пример блока fetch

fetch:
  policy: sync | async | async_on_timeout # на данном этапе реализуется только sync
  store_timeout: PT15M
  timeout: PT20S
  retries: 2

6.2.3. Автоматическое создание модели данных на основе схемы БД

6.2.3.1. Общее описание

Данная функция позволяет создать заполненную модель данных, на основе схемы БД подключенного источника (на основе схемы данных Prostore).

6.2.3.2. Сценарий выполнения

Предварительные условия:

  1. Настроена модель источника данных типа Prostore (Раздел 2.3.5.3.3.1).

  2. Создана базовая модель (Раздел 2.3.5.3.2.1).

Ход выполнения:

  1. Администратор сервера в консоли вводит команду генерации модели данных на основе схемы БД источника Prostore:

./smevql schema-gen -d <название схемы>

  1. Система проверят наличие базовой модели:

    1. если базовая модель отсутствует, то Система выводит соответствующее сообщение об ошибке;

    2. иначе, переход к выполнению следующего шага;

  2. Система проверяет, что имя модели (название схемы) уникально:

    1. если имя модели не уникально (модель данных с таким именем уже существует в файловой системе СМЭВ QL), то Система выводит соответствующее сообщение об ошибке;

    2. иначе, имя модели уникально, переход к выполнению следующего шага;

  3. Система создаёт папку с указанным наименованием и файл model.yaml;

  4. Система заполняет содержимое файла model.yaml по следующим правилам:

    1. Каждая таблица в схеме БД - это отдельный ресурс в модели данных;

    2. Каждый атрибут таблицы в схеме БД - это элемент блока fields: соответствующего ресурса;

    3. Блок connections: - пустой;

    4. Блок conditions: - пустой;

    5. Блок extract: - name: <название источника из модели источника>, table: <название таблицы из БД>.

Схема в БД Prostore

Рисунок - 6.2 Схема в БД Prostore

Сгенерированная модель данных:

- name: smevql
    version: 1.0
    data:
      resources:
        - passenger: *base_model
          name: Пассажиры
          description: Логическая таблица "Пассажиры"
          fields:
            id:
              !!merge <<: *ds
              name: ИД пассажира
            firstname:
              !!merge <<: *ds
              name: Имя
            lastname:
              !!merge <<: *ds
              name: Фамилия
           connections:
           extract:
            source:
              - name: prostore
                table: ms.passengers
         - trip: *base_model
           name: Рейс
           description: Логическая таблица "Рейс"
           fields:
            !!merge <<: *default_fields
            id:
              !!merge <<: *ds
              name: ИД рейса
            number:
              !!merge <<: *pkn
              name: Номер
            duration:
              !!merge <<: *dtm
              name: В пути
           connections:
           extract:
            source:
              - name: prostore
                table: ms.trips

6.2.4. Создание новой версии модели данных

6.2.4.1. Общее описание

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

Однако в рамках одного наименования модели (папки с названием модели) может быть активна только одна версия модели данных.

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

Разные версии одной модели

Рисунок - 6.3 Разные версии одной модели

Модели данных считываются, валидируются и загружаются в память из папки models при запуске СМЭВ QL сервера.

По умолчанию используется версия model, на которую ссылается symlink current, при его отсутствии по умолчанию считается старшая по номеру версия.

Модели и версии, начинающиеся с подчеркивания (_) НЕ загружаются, они находятся в стадии проектирования.

6.2.4.2. Сценарий выполнения

Предварительные условия:

  1. Подготовлена модель данных с учетом всех необходимых изменений (файл model.yaml).

Ход выполнения:

  1. Администратор системы выбирает папку с названием модели данных для которой необходимо создать новую версию.

  2. Администратор системы вручную создает новую папку с указанием нового номера версии (обычно это новое целочисленное значение).

  3. Администратор системы вручную переносит, заранее подготовленный файл model.yaml, в папку с новым номером версии.

6.2.5. Проверка валидности модели данных

6.2.5.1. Общее описание

Валидация модели данных выполняется при каждом запуске СМЭВ QL сервер и в случае возникновения ошибок, приложение не будет запущено.

Помимо этого можно предварительно проверить корректность заполнения модели данных путем вызова специальной команды в консоли приложения.

6.2.5.2. Сценарий выполнения

  1. Администратор сервера в консоли вводит команду проверки валидности модели данных:

    1. если требуется проверить все модели данных, то выполняется команда: ./smevql test model all.

    2. если требуется проверить конкретные модели, то выполняется команда (с указанием через запятую) наименований моделей: ./smevql test model <model-name1>, <model-name2>.

  2. Система проверяет корректность заполнения моделей данных и в случае наличия ошибок выведет соответствующее сообщение.

6.2.6. Маппинг типов данных СМЭВ QL - Prostore

Логический тип Prostore

Описание

Логический тип СМЭВ QL

Тип базовой модели СМЭВ QL

BOOLEAN

Логический (булевый) тип

BOOLEAN

&db, &pkb

CHAR (n)

Строка ограниченной длины (n символов). Размерность строки обязательна

STRING

&ds, &dst, &denv, &pks

VARCHAR [(n)]

Строка ограниченной длины (n символов). Размерность строки опциональна

STRING

&ds, &dst, &denv, &pks

LINK

Строка неограниченной длины. Предназначена для ссылочных полей

BINARY

&dbn, &pkbn

UUID

Строка ограниченной длины (36 символов)

STRING

&ds, &dst, &denv, &pks

INTEGER, алиас — INT32

Целое число фиксированной длины со знаком в диапазоне от -2147483648 до 2147483647

SHORT, INTEGER

&pksh, &dsh, &pkn, &dn

BIGINT, алиас — INT64

Целое число фиксированной длины со знаком в диапазоне -263, 263-1 [1]

LONG

&pkl, &dl

DOUBLE

Число с плавающей запятой с двойной точностью

DOUBLE

&dd, &pkd

FLOAT

Число с плавающей запятой

FLOAT

&pkf, &df

DATE

Дата (без времени суток)

DATE

&ddt, &pkdt

TIME, TIME (p)

Время (без даты).

Значение p задает точность отображаемого времени.

Возможные значения: от 0 (секунды) до 6 (микросекунды).

Значение по умолчанию - 6. Количество микросекунд находится в диапазоне от 0 до 86399999999

TIME

&dtm, &pktm

TIMESTAMP,

TIMESTAMP (p)

Дата и время.

Значение p задает точность отображаемого времени.

Возможные значения: от 0 (секунды) до 6 (микросекунды).

Значение по умолчанию - 6

TIMESTAMP

&pkts, &dts

Не поддерживается в Prostore

BYTE

&dbt, &pkbt

Не поддерживается в Prostore

BIG_DECIMAL

&dbd, &pkbd

6.3. Работа с источниками данных

6.3.1. Создание модели источников

6.3.1.1. Общее описание

Данная функция позволяет добавлять новую версию описания модели источников данных СМЭВ-QL.

В качестве источников данных для СМЭВ-QL сервер могут выступать:

  1. REST-интерфейс витрины данных (Prostore);

  2. Другой СМЭВ-QL сервер

Модель источников данных СМЭВ-QL хранится в файловой системе СМЭВ-QL сервера по пути: sources/custom/1.0/source.yaml

Допускается описание всех источников в рамках одной модели.

6.3.1.2. Общий сценарий выполнения

  1. Администратор сервера в консоли вводит команду генерации новой пустой модели источника:

./smevql g source <source-name>

  1. Система создаёт новую версию папки и файла модели источника с пустыми значениями - source.yaml

  2. Администратор сервера открывает на редактирование файл модели источника source.yaml и заполняет параметры необходимыми значениями.

Создание модели источников данных

Рисунок - 6.4 Создание модели источников данных

6.3.1.3. Структура source.yaml

Описание источника данных в формате YAML имеет следующую структуру:

Таблица 6.7 Описание источника данных

Параметр

Описание

Наименование

Наименование источника данных.

В рамках файла source.yaml источник всегда имеет название с постфиксом _source.

При этом именем источника в моделях данных считается часть без учета данного постфикса.

То есть источник egrn_source в модели данных model.yaml необходимо указывать как egrn.

type

Тип интеграционного взаимодействия. На текущий момент поддерживается только rest

version

adapter

Тип источника данных. Может принимать значения:

  • prostore;

  • smevql.

protocol

Указание протокола передачи данных. На текущий момент поддерживается только HTTP

host

Хост-адрес сервера источника данных

port

Порт сервера источника данных

path

Путь для вызова REST-метода API источника данных

template

Шаблон передачи REST-запроса к источнику

payload-path

headers

Значения по умолчанию для заголовка REST-запроса к источнику

threads-count

connection-timeout

Тайм-аут ожидания ответа от сервера источника

Описание источника данных в формате YAML имеет следующую структуру:

prostore_source:
  type: rest
  version: 1.0
  adapter: prostore
  protocol: http
  host: localhost
  port: 9090
  path: api/v1/datamarts/query?format=json
  template: '{ "query": "%{request}", "queryId": "%{request_id}" }'
  payload-path: result
  headers:
      - accept: application/json
      - content-type: application/json
  threads-count: 10
  connection-timeout: 0

smevql_server_source:
  type: rest
  version: 1.0
  adapter: smevql
  protocol: https
  host: localhost
  port: 9091
  path: api/query?format=json
  template: '{ "query": "%{request}" }'
  payload-path: result
  headers:
    - accept: application/json
    - content-type: application/json

6.3.2. Создание новой версии модели источников

6.3.2.1. Общее описание

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

Однако в рамках одного наименования модели (папки с названием модели) может быть активна только одна версия модели источников.

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

Создание новой версии модели источников данных

Рисунок - 6.5 Создание новой версии модели источников данных

Источники данных считываются, валидируются и загружаются в память из папки sources при запуске СМЭВ QL сервера.

По-умолчанию используется версия источника, на которую ссылается symlink current, при его отсутствии по-умолчанию считается старшая версия.

Источники и версии, начинающиеся с подчеркивания (_) НЕ загружаются, они находятся в стадии проектирования.

6.3.2.2. Сценарий выполнения

Предварительные условия:

  1. Подготовлена модель источников с учетом всех необходимых изменений (файл source.yaml).

Ход выполнения:

  1. Администратор системы выбирает папку с названием модели источников для которой необходимо создать новую версию.

  2. Администратор системы вручную создает новую папку с указанием нового номера версии (обычно это новое целочисленное значение).

  3. Администратор системы вручную переносит, заранее подготовленный файл source.yaml, в папку с новым номером версии.

6.3.3. Проверка доступности источников

6.3.3.1. Общее описание

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

6.3.3.2. Сценарий выполнения

  1. Администратор сервера в консоли вводит команду проверки доступности источников:

    1. если требуется проверить все источники, то выполняется команда: ./smevql test source all;

    2. если требуется проверить конкретный источник, то выполняется команда (с указанием через запятую) наименований источников: ./smevql test source <source-name1>, <source-name2>;

  2. Система отправляет проверочный запрос к источнику и дожидается ответа в течении заданного таймаута:

    1. если ответ не пришёл в течение заданного таймаута, то Система выводит соответствующее сообщение об ошибке, источник не доступен;

    2. иначе, ответ пришёл в течение заданного таймаута, источник доступен.

6.4. Работа с картами машин состояний

6.4.1. Создание карты машины-состояний

6.4.1.1. Общее описание

Карта машины состояний (Раздел 2.3.5.2.2) описывает её статусы и события, при вызове которых осуществляется переход к следующему статусу.

Карта состояний и переходов машины состояний описывается в виде YAML-файла state.yaml и хранится в файловой системе СМЭВ QL сервера по пути: states><model-name>><version number>>state.yaml

6.4.1.2. Структура карты машины состояний

Элемент

Описание

model:

Название карты машины состояний (модели стэйт-машины)

states:

Массив возможных состояний

state:

Название состояния

attributes:

Массив атрибутов, описывающих состояние. Каждый атрибут имеет следующие свойства:

  • name - название атрибута;

  • value - значение атрибута.

initial:

Признак исходного состояния.

Может быть определен только у одного состояния в рамках одной карты машины состояний.

delete:

Признак, указывающий что при переходе в данное состояние будут удалены данные в соответствии с условиями переданными в блоке conditions исходного запроса от клиента POST/states/{model}/{event}.

При этом значения атрибутов для такого статуса не применимы, они игнорируются.

Состояние с данным признаком считается конечным и не может использоваться в разделе from при описании событий.

static:

Признак, при установке которого не меняется статус, а только передается указанная в описании события часть запроса в блоке confirm к связанному источнику.

events:

Список событий изменения состояний.

Каждое событие вызывается отдельным методом POST/states/{model}/{event}

Важно! В любой модели машины состояний по умолчанию присутствует event с типом init, хотя он и не описан в явном виде.

Такое событие является обязательным и при его вызове в витрину добавляется новая запись и устанавливается статус исходного состояния (initial)

event:

Название события

from:

Массив состояний из которых возможен вызов события

to:

В какое состояние переходит стэйт-машина после наступления события

hooks:

Массив связанных событий, которые будут выполняться после перехода в заданное состояние.

На текущий момент в рамках hook возможен только вызов событий других стэйт-машин.

Каждый hook имеет следующие свойства:

  • model - название карты машины состояний;

  • event - название события.

confirm:

Вызов внешнего REST-метода.

Данное действие выполняется до осуществления перехода в рамках вызванного события.

Блок содержит следующие свойства:

Описание запроса:

  • source - название внешнего источника (мнемоника вызываемого источника);

  • endpoint - эндпоинт вызываемого REST-метода;

  • method - тип вызываемого REST-метода;

  • body - указание того, какое содержимое body необходимо передать при выполнении REST-запроса внешнему источнику. Возможные значения: full, state, conditions, payload, credentials.

    Источником для содержимого является соответствующий блок данных в body исходного запроса от клиента (POST/states/{model}/{event}).

Описание ответа:

  • accept - описание условия ответа, при соблюдении которого вызов внешнего REST-метода считается успешным.

    Если данное условие (получение заданного ответа) не выполняется, то переход стэйт-машины завершается ошибкой. Блок содержит следующие свойства:

    • jsonpath - получаемый в ответе атрибут;

    • eq - значение получаемого атрибута.

  • enrich - указание необходимости обновления данных на основании полученного ответа.

    Блок содержит следующие свойства:

    • allow - признак, указывающий о необходимости обновления данных (true - обновлять; false - только извлекать, без обновления ресурса);

    • jsonpath - указание того, из какой части ответа брать данные.

      При отсутствии объекта по пути jsonpath в confirm запросе возвращается ошибка 501 «Отсутствует объект при обращении по jsonpath», выполнение запроса прерывается.

    • attributes - массив атрибутов, которые необходимо взять из ответа.

      Если массив пустой [], то берутся все атрибуты из указанного jsonpath.

      При несоответствии атрибутов в блоке attributes и в jsonpath - в payload вернутся только те атрибуты, по которым есть соответствия с фиксацией в логах событий уровня WARN о несоответствующих атрибутах: Отсутствует атрибут *attribute_name" в $.update.payload.

      В случае, если в payload присутствуют атрибуты, аналогичные тем, что возвращаются при выполнении блока enrich, обновляются данные в соответствии со значениями вернувшимися при выполнении блока enrich.

      В этом случае в логах фиксируется запись "Изменение значений атрибутов:  *attribute_name" payload в соответствии со значениями блока enrich".

      Атрибуты payload ответа confirm обогащают payload основного запроса.

      Обновление данных в витрине в случае обогащения payload дополнительными атрибутами происходит независимо от значения updatable.

updatable:

Признак, указывающий, что необходимо обновить ресурс в рамках вызываемого события

updatable_attributes:

Массив атрибутов, которые необходимо обновить в рамках вызываемого события. Если массив пустой [], то обновляются все атрибуты. Источником данных для обновления является блок payload исходного запроса от клиента (POST/states/{model}/{event})

Пример структуры карты машины состояний:

model: slot # имя модели
states: # массив состояний объекта
  - state: available # название состояния available
      attributes: # массив атрибутов, описывающих состояние
      - name: status # состояние определятся значением атрибута status
          value: AVAILABLE # значение атрибута для описываемого состояния
      initial: true
  - state: booked
      attributes:
      - name: status
          value: RECORDED
  - state: reserved
      attributes:
      - name: status
          value: RESERVED
  - state: cancelled
      attributes:
      - name: status
          value: CANCELED
  - state: blocked
      attributes:
      - name: status
          value: BLOCKED
  - state: deleted
      delete: true
  events: # список событий изменения состояний, из них создаются методы API
  - event: book # создает метод POST /states/slot/book
      from: # массив состояний из которых возможен вызов события
      - available
      - reserved
      to: booked # в какое состояние переводится объект после события
      hooks: # массив связанных событий
      - model: book # после перевода надо вызвать событие init для модели book
          event: init
      confirm:
          source: rmis_rest # названия источника
          endpoint: /booking/book
          method: post
          body: payload # что включать в тело запроса (full|state|conditions|payload|credentials)
          accept: # условие принятия
              jsonpath: $.status.statusCode
              eq: 0 # ожидаем, что statusCode будет равен 0
          enrich:
          allow: true // по умолчанию false
          attributes: [] // пустой массив — все, а если перечислены, то только эти
          jsonpath: $.update.payload // ожидается что по этому адресу объект с атрибутами и значениями
  - event: reserve
      from: available
      to: reserved
      updatable: true // по умолчанию false для всех, кроме init, возможность изменять запись при переводе статуса
      updatable_attributes: [] // массив атрибутов, которые можно обновлять, пустой — можно все
  - event: block
      from: available
      to: blocked
  - event: cancel
      from:
      - available
      - reserved
      - booked
      - blocked
      to: cancelled
      hooks:
      - model: book
          event: cancel
  - event: delete
      from:
      - available
      - reserved
      - booked
      - blocked
      - cancelled
      to: deleted
      hooks: # массив связанных событий
      - model: book # после перевода надо вызвать событие delete для модели book
          event: delete

6.4.1.3. Сценарий выполнения

  1. Администратор системы в произвольном текстовом редакторе создает и заполняет файл (state.yaml) с описанием карты машины состояний.

  2. Администратор системы создает папку с названием модели стэйт-машины в рамках каталога states.

  3. Администратор системы создает папку с указанием номера версии модели стэйт-машины в рамках каталога с названием стэйт-машины.

  4. Администратор системы вручную переносит, заранее подготовленный файл state.yaml, в папку с новым номером версии.

  5. Для возможности вызова API методов новой карты машины состояния необходимо обновить openAPI СМЭВ QL (Раздел 2.3.5.3.1.4.3)

Создание карты машины-состояний

Рисунок - 6.6 Создание карты машины-состояний

6.4.2. Создание новой версии карты машины-состояний

6.4.2.1. Общее описание

СМЭВ QL может одновременно использовать несколько разных моделей стэйт-машин с разным наименованием.

Однако в рамках одного наименования модели (папки с названием модели) может быть активна только одна версия модели стэйт-машины.

Версия модели стэйт-машины характеризуется уникальным номером и наличием отдельной папки с данным номером в файловой системе СМЭВ QL.

Создание новой версии карты машины-состояний

Рисунок - 6.7 Создание новой версии карты машины-состояний

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

По-умолчанию используется версия стэйт-машины, на которую ссылается symlink current, при его отсутствии по-умолчанию считается старшая версия.

Карты машин состояний и версии, начинающиеся с подчеркивания (_) НЕ загружаются, они находятся в стадии проектирования.

6.4.2.2. Сценарий выполнения

Предварительные условия:

  1. Подготовлена модель стэйт-машины с учетом всех необходимых изменений (файл state.yaml).

Ход выполнения:

  1. Администратор системы выбирает папку с названием стэйт-машины для которой необходимо создать новую версию.

  2. Администратор системы вручную создает новую папку с указанием нового номера версии (обычно это новое целочисленное значение).

  3. Администратор системы вручную переносит, заранее подготовленный файл state.yaml, в папку с новым номером версии.

  4. Администратор перезапускает сервер (Раздел 3.6.1).

6.5. Обработка запроса к витрине

6.5.1. Запрос получения данных из витрины (POST/data)

6.5.1.1. Общее описание

Для выполнения запроса к СМЭВ QL серверу на получение данных витрины (или нескольких витрин, если запрос распределенный (Раздел 2.3.5.2.5)) потребитель должен вызвать опубликованный метод POST/data.

В рамках запроса необходимо передать в теле JSON-объект заданного формата.

POST /data содержит подробное описание.

6.5.2. Запрос изменения данных витрины через события машины состояний (POST/states/{model}/{event})

Для выполнения запроса к СМЭВ QL сервер на изменение данных витрины через машину состояний потребитель должен вызвать опубликованный метод POST/states/{model}/{event}, где model - название карты машины состояний, а event - событие карты машины состояний.

В рамках запроса необходимо передать в теле JSON-объект заданного формата.

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

  • Изменить статус машины состояния без обновления данных витрины;

  • Обновить данные витрины (добавить новые, изменить текущие);

  • Удалить данные витрины;

  • Вызывать событие другой машины состояния;

  • Добавить/обновить/удалить данные другой витрины.

POST /states/{model}/{event} содержит подробное описание.

6.5.3. Обработка запроса получения данных витрины

6.5.3.1. Общее описание

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

  1. Проверка запроса и доступов.

  2. Формирование плана исполнения запроса.

  3. Исполнение плана запроса.

  4. Передача ответа потребителю.

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

  1. Модель данных СМЭВ QL сервера успешно создана.

  2. Зарегистрирован метод получения данных витрины POST/data.

  3. Потребитель обладает правами на выполнение REST-запроса.

6.5.3.2. Проверка запроса и доступов

Проверка запроса и доступов

Рисунок - 6.8 Проверка запроса и доступов

Запускающее событие:

  • Получен запрос получения данных витрины (вызван метод POST/data)

Ход выполнения:

  1. СМЭВ QL (далее Система) проверяет тело запроса на соответствие заданной схеме (Обработка запроса к витрине):

    1. если запрос не соответствует заданной схеме, то Система передаёт соответствующее сообщение об ошибке, процесс завершается;

    2. иначе, формат запроса корректен, переход к выполнению следующего шага.

  2. Система проверяет доступ ИС Потребителя к данным витрины, для этого сравнивает полученный в запросе идентификатор системы-потребителя (блок credentials->system) c перечнем запрещенных и разрешенных, который задается в конфигурационном файле приложения application.yaml (black_list и white_list):

    1. если доступ запрещен, то Система передаёт соответствующее сообщение об ошибке, процесс завершается;

    2. иначе, доступ разрешен, переход к выполнению следующего шага.

  3. Система получает из блока персистентности Redis текущие значения лимитов на выполнение запросов.

  4. Система проверяет превышение установленных лимитов на выполнение запроса Потребителя к заданным ресурсам. Для этого сравнивает текущие полученные значения на шаге 3 с настройками лимитов, определенных в конфигурационном файле приложения application.yaml (limits):

    1. если допустимый лимит превышен, то Система передаёт соответствующее сообщение об ошибке, процесс завершается;

    2. иначе, лимиты не превышены, переход к выполнению этапа «Формирование плана исполнения запроса».

6.5.3.3. Формирование плана исполнения запроса

Формирование плана исполнения запроса

Рисунок - 6.9 Формирование плана исполнения запроса

Запускающее событие:

  • Запрос получения данных витрины прошел необходимые проверки.

Ход выполнения:

1. Система на основании вложенности ресурсов, заданной в запросе (query) определяет уровни плана выполнения запроса и sql-выражения. Формирование плана запроса основывается на внешнем объединении данных в сторону основной сущности.

Порядок формирования плана запроса:

  • на основе query определяется основная запрашиваемая сущность

  • на основе query определяются вспомогательные сущности

  • на основе query определяются conditions к основной сущности

  • на основе query определяются conditions к вспомогательным сущностям

  • на первом уровне плана формируется запрос к основной сущности на основе:

    • запрошенных атрибутов

    • данных модели

    • условий фильтрации

Отмечаются поля, составляющие PK.

Первичные ключи, даже отсутствующие в атрибутах запроса к серверу должны быть в запросе к источнику.

  • формируется запрос к вспомогательным сущностям на основе:

    • запрошенных атрибутов

    • данных модели

    • условий фильтрации

    • с добавлением фильтрации по PK основной или предшествующей сущности

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

Пример уровней плана на основе запроса:

Формирование плана исполнения запроса

Рисунок - 6.10 Формирование плана исполнения запроса

  1. Система проверяет, что все ресурсы из плана запроса определены в модели данных:

    1. если хотя бы один ресурс не описан в модели данных, то Система передаёт соответствующее сообщение об ошибке, процесс завершается;

    2. иначе, все ресурсы описаны в модели данных, переход к выполнению следующего шага.

  2. Система проверяет, что для каждого ресурса определён источник получения данных. Для этого по каждому ресурсу определяет его источник в модели данных (блок extract:), в т.ч. с учетом условий применения источника (extract->conditions:) и описан ли источник в модели source:

    1. если хотя бы один источник данных не определен в модели данных или не описан в модели источников, то Система передаёт соответствующее сообщение об ошибке, процесс завершается;

    2. иначе, для каждого ресурса определен источник данных, переход к выполнению следующего шага.

  3. Система определяет стратегию делегирования подзапросов (подзапросов более низкого уровня). Для этого определяет значение в параметре request→strategy конфигурационного файла приложения application.yaml (делегирование возможно только источнику smevql):

    1. если значение atomic - то последовательность выполнения подзапросов соответсвует иерархии уровней, определенной на шаге 1;

    2. иначе установлено значение delegate - делегирование подзапроса со всеми дочерними элементами другому СМЭВ QL. В таком случае, все делегированные подзапросы исключаются из плана запроса данного СМЭВ QL.

  4. Система проверяет, что в модели данных (блок connections:) существуют и корректно заполнены связи между всему основными и подчиненными ресурсами:

    1. если хотя бы одна связь между основным и подчиненным ресурсом не задана или некорректно описана, то то Система передаёт соответствующее сообщение об ошибке, процесс завершается;

    2. иначе, связи между ресурсами заполнены корректно, переход к выполнению следующего шага.

  5. Система проверяет, что перечень атрибутов, запрашиваемый Потребителем не запрещен на уровне модели данных. Для этого проверяет заполнение блока guard: в модели данных и определяет соблюдены ли условия по передачи данных атрибутов в запросе (блок conditions):

    1. если хотя бы один атрибут запрещен для передачи Потребителю (guard заполнен в модели, а требуемый conditions не заполнен в запросе), то Система передаёт соответствующее сообщение об ошибке, процесс завершается;

    2. иначе, все требуемые атрибуты разрешены для передачи Потребителю, переход к выполнению следующего шага.

  6. Система на основании блока fetch→show_events определяет возможность обогащения передаваемых атрибутов данными о возможных событиях (event) машины состояний. Текущий процесс завершается и вызывается исполнение плана запроса.

6.5.3.4. Исполнение плана запроса

Исполнение плана запроса

Рисунок - 6.11 Исполнение плана запроса

Запускающее событие:

  • Подготовлен план выполнения запроса

Ход выполнения:

Указанная последовательность выполняется для каждого подзапроса из плана. При этом сначала параллельно выполняются подзапросы первого уровня, затем подзапросы второго уровня на основе данных полученных на первом уровне и т.д. по всем уровням иерархии плана запроса.

В качестве ответа от Источника могут быть сами запрашиваемые данные (если обращение к источнику шло в синхронном режиме) или токен (если обращение к источнику шло в асинхронном режиме).

  1. Система отправляет подзапрос к источнику с указанным в плане sql-выражением. Так же на этом шаге Система обновляет счетчики лимитов в Redis, при этом количество увеличивается на величину подзапросов к источникам данных.

  2. Система ожидает ответ и определяет режим обработки подзапроса к источнику ресурса. Для этого определяет значение параметра fetch->policy в модели данных ресурса:

    1. если установлено значение sync или async_on_timeout и ответ пришёл в течение заданного таймаута, то режим обработки подзапроса синхронный, переход к выполнению шага 2;

    2. иначе, установлено значение async или async_on_timeout и исчтоник не отвечает в в течение заданного таймаута, то режим обработки подзапроса асинхронный, переход к выполнению шага 6.

  3. Система обрабатывает полученный ответ от источника или обрабатывает ситуацию, когда ответ не получен:

    1. если ответ получен и он некорректного формата или ответ не получен в заданный таймаут, то Система передаёт соответствующее сообщение об ошибке, процесс завершается;

    2. если, ответ корректен и получен в заданный таймаут, а источником данных является prostore, то данный процесс завершается и вызывается выполнение передачи ответа потребителю (Раздел 2.3.5.3.5.3.5);

    3. иначе, ответ корректен и получен в заданный таймаут, а источником данных является smevql, переход к выполнению следующего шага.

  4. Система проверяет, что ответ от источника подписан цифровой подписью (далее ЦП). Для этого извлекает данные из полученного ответа (блок signature) и отправляет данные ЦП на проверку в модуль Notarius. После чего дожидается результатов проверки ЦП от Notarius:

    1. если ЦП не прошла успешную проверку в Notarius или блок signature не заполнен источником, то ответ считается невалидным, Система передаёт соответствующее сообщение об ошибке, процесс завершается;

    2. иначе, ЦП прошла успешную проверку в Notarius, ответ валиден, переход к выполнению следующего шага.

  5. Система накладывает свою ЦП на ответ источника. Для этого отправляет запрос в модуль Notarius и ожидает получение ответа. После чего ответ подписан ЦП (заполнен блок partials в ответе для потребителя). Процесс завершается после получения всех ответов от всех источников и вызывается выполнение передачи ответа потребителю (Раздел 2.3.5.3.5.3.5).

  6. Система генерирует токен (по которому в дальнейшем Потребитель сможет отдельно запросить данные) и записывает его в блоке персистентности Redis.

  7. Система в качестве временного ответа от источника подставляет токен (Раздел 2.3.5.3.5.4). Процесс завершается после получения всех ответов от всех источников и вызывается выполнение передачи ответа потребителю.

6.5.3.5. Передача ответа потребителю

Передача ответа потребителю

Рисунок - 6.12 Передача ответа потребителю

Запускающее событие:

  • Получены все ответы от источников и/или токены.

Ход выполнения:

  1. Система формирует комплексный ответ на основе полученных ответов от источников и/или токенов. Формат ответа в таблице ниже:

Элемент

Описание

Пример

response

Объект, который содержит данные запрашиваемых ресурсов и/или токенов для асинхронного получения данных ресурсов

Пример блока response

Пример блока async

<resource_name>

Название ресурса, массив данных которого был получен в источнике.

Если запрос содержал подчиненные ресурсы, то данные таких ресурсов будут вставлены в массив объекта основного ресурса.

Если данные ресурса должны быть получены отдельно в асинхронном режиме, то ответ будет содержать блок async, который имеет следующие атрибуты:

  • token - токен для асинхронного обращения;

  • source - источник данных;

  • reason - тип асинхронного обращения, async - всегда асинхронное или async_on_timeout - асинхронное при превышении таймаута;

  • timeout - таймаут обращения к источнику;

  • request_in - время, по прошествии которого можно отправить повторный запрос получения данных;

  • retries_left - оставшееся количество попыток получения данных, если равен 0, то данные запросить невозможно.

credentials

Объект, содержащий общие данные запроса и информация о потребителе

Пример блока credentials

response

Объект описывает общие параметры ответа. Имеет следующие атрибуты:

  • id - идентификатор ответа;

  • sub_id - идентификатор подзапроса;

  • started_at - время начала формирования ответа;

  • finished_at - время окончания формирования ответа.

system

Объект описывает параметры системы-потребителя данных. Имеет следующие атрибуты:

  • mnemonic - мнемоника системы;

  • instance_id - идентификатор экземпляра системы;

  • user_id - идентификатор пользователя.

request

Объект описывает общие параметры запроса. Имеет следующие атрибуты:

  • id - идентификатор запроса;

  • sub_id - идентификатор подзапроса;

  • name - имя запроса;

  • purpose_id - идентификатор события, инициировавшего запрос;

  • audit - возможность аудита;

  • audit_id - идентификатор аудита. Заполняется только, если audit = true.

  • audit_token - токен аудита. Заполняется только, если audit = true.

signature

Объект, содержащий данные ЦП по каждому ответу от каждого источника, а так же ЦП комплексного ответа

complex

ЦП комплексного ответа, имеет следующие атрибуты:

  • digest - краткий обзор подписи;

  • signature - цифровая подпись.

partials

Массив ЦП по каждому полученному ответу от источников данных. Содержит следующие атрибуты:

  • digest - краткий обзор подписи;

  • signature - цифровая подпись;

  • response_id - идентификатор ответа от источника;

  • jsonpath - название ресурса.

6.5.3.6. Пример блока response

"response": {
        "ticket": [
            {
                "number": 1,
                "price": 701.0252675821603,
                "trip": [
                    {
                        "id": "f72f4157-e11b-4fe1-86a2-babaeb3ccd21",
                        "duration": "07:31:03"
                    }
                ]
            }
        ]
    }

6.5.3.7. Пример блока async

"async": {
        "token": "11111-22222-333333-4444-55555",
        "source": "region81",
        "reason": "async_on_timeout",
        "timeout": "500ms",
        "request_in": "10s",
        "retries_left": "9"
    }

6.5.3.8. Пример блока credentials

"credentials": {
        "response": {
            "id": "fc7953cb-99ad-4a78-b49d-c3dce2c4bb89",
            "sub_id": "a8744e12-49ce-4524-861d-0e3b9a763d14",
            "started_at": "2023-02-13 07:55:23 +0300",
            "finished_at": "2023-02-13 07:55:23 +0300"
        },
        "system": {
            "mnemonic": "117bed7f-1c07-4079-a446-1161588db4e5",
            "instance_id": "ccb4a88f-f44b-43e7-8a97-3e45c8345e90",
            "user_id": "5ed38461-0907-486a-930a-7b443482932c"
        },
        "request": {
            "id": "df5a0073-c6be-4d8c-8eb2-9b2f4188a429",
            "sub_id": "0cdb59ce-224b-4118-8da1-c5ea08a5d955",
            "name": "driver_data",
            "purpose_id": "ed1170f1-3caa-4985-aa38-c9c5a190b770",
            "audit": "false",
            "audit_id": "fc1048fe-323d-4eeb-92df-5710b3d1d100",
            "audit_token": "39e47aac-45d2-44c1-8c26-2d9b28b1703b"
        }
    },
    "signature": {
        "complex": {
            "digest": "985925e62ce3494a4e73f20676f1506ef64380f0",
            "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
        },
        "partials": [
            {
                "digest": "985925e62ce3494a4e73f20676f1506ef64380f0",
                "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
                "response_id": "fc7953cb-99ad-4a78-b49d-c3dce2c4bb89",
                "jsonpath": "$.response.office"
            }
        ]
    }
}

6.5.4. Асинхронное получение данных клиентом

6.5.4.1. Общее описание

Разные источники с разной скоростью передают данные и по скорости передачи данных их условно можно разделить на «быстрые» и «медленные».

При взаимодействии с «быстрыми» источниками обмен клиента (потребителя) со СМЭВ QL происходит в синхронном режиме в таком случае запрашиваемые данные передаются с разу в момент обращения, а при взаимодействии с «медленными» источниками обмен происходит в асинхронном режиме, в таком случае данные передаются с определенным временным лагом. Указание типа взаимодействия, синхронное или асинхронное, определяется на уровне модели данных в блоке fetch->policy.

Для потребителя наличие в ответе блока async с токеном вместо данных означает, что данные необходимо получить отдельным запросом, вызвав метод GET/data/{token}.

6.5.4.2. Передача асинхронных данных от источника в СМЭВ QL

Предварительные условия:

СМЭВ QL отправил источнику запрос получения данных (Раздел 2.3.5.3.5.3) и сохранил токен.

Ход выполнения:

  1. Источник подготавливает и передает данные в асинхронном режиме.

  2. СМЭВ QL записывает полученные данные в блоке персистентности в спейсе responses с временем жизни store_timeout, где в качестве ключа выступает ранее сформированный токен.

Пример записи асинхронных данных в блоке персистентности:

  • ключ (токен): 11111-22222-333333-4444-55555

  • значение (данные от источника)

{"referral": [
  {
    "to_post_name": "врач-терапевт участковый",
    "end_date": null,
    "speciality_id": "119",
    "to_mo_id": "325",
    "mo": [
            {
              "id": "325",
              "name": "ГКБ 222; Кардиология"
            }
          ]
    }
  ]
}

6.5.4.3. Запрос асинхронных данных потребителем

Предварительные условия:

  • Потребитель получил ответ от СМЭВ QL с блоком async

Ход выполнения:

  1. Потребитель, спустя рекомендованное время (параметр async->request_in в ответе), отправляет запрос получения асинхронных данных. Для этого вызывает метод GET/data/{token}, где в качестве {token} передаёт значение, полученное ранее в ответе (async→token).

  2. СМЭВ QL сервер проверяет наличие данных по токену:

    1. если данные ещё не поступили от источника, то обновляет счётчик обращений от клиента и формирует ответ вида:

 {
     "response": {},
     "asynced": {
     "referral": [
         {
         "async":{
         "source": "region12",
         "reason": "receiving_data",
         "timeout": "10s",
         "request_in": "10s",
         "retries_left": "5"
             }
         }
         ]
     }
 }

b. иначе, данные были получены от источника, Система формирует ответ с данными вида:

{
    "response": {
      "referral": [
        {
      "to_post_name": "врач-терапевт участковый",
      "end_date": null,
      "speciality_id": "119",
      "to_mo_id": "325",
      "mo": [
              {
                "id": "325",
                "name": "ГКБ 222; Кардиология"
              }
            ]
        }
    ]
  },

  1. СМЭВ QL сервер подписывает ответ ЦП с помощью Notarius и передаёт потребителю подписанный ответ.

Примечание

Потребитель продолжает запрашивать данные с рекомендованным интервалом пока не получит данные или пока количество попыток retries_left не будет равно 0.

6.5.5. Обработка запроса изменения данных витрины через машину состояний

6.5.5.1. Общее описание

Машина состояний СМЭВ QL сервер имеет определенное количество состояний (states), переход между которыми осуществляется посредством вызова событий (events).

В зависимости типа вызываемого события выполняется разная логика по обновлению данных витрины.

6.5.5.2. Основной сценарий выполнения

Запускающее событие:

Потребитель вызвал событие посредством выполнения запроса POST/states/{model}/{event}.

Схема процесса:

Обработка запроса изменения данных витрины через машину состояний

Рисунок - 6.13 Обработка запроса изменения данных витрины через машину состояний

Ход событий:

  1. Система проверяет тип вызываемого события:

    1. если событие с типом init (POST/states/{model}/init), то вызывается альтернативное направление (Раздел 2.3.5.3.5.5.3);

    2. иначе, событие не init, переход к выполнению следующего шага.

  2. Система проверяет наличие блока confirm у вызванного события:

    1. если событие содержит блок confirm, то вызывается альтернативное направление (Раздел 2.3.5.3.5.5.4);

    2. иначе, событие не содержит блок confirm, переход к выполнению следующего шага.

  3. Система получает данные из Prostore для ресурса, вызванной стэйт-машины и сохраняет их в оперативной памяти для последующего обращения. В качестве критерия используются:

    • Условия в блоке conditions исходного запроса

    • Значения attributes: из текущего состояния стэйт-машины

Количество записей, получаемых из Prostore ограничено настройкой max_updated_rows в конфигурационном файле приложения application.yaml. После получения данных, осуществляется переход к выполнению следующего шага.

  1. Система проверяет в какое состояние должна перейти стэйт-машина после выполнения вызванного события. Для этого у вызванного события читается параметр to:

    1. если стэйт-машина должна перейти в состояние с признаком delete = true, то вызывается альтернативное направление (Раздел 2.3.5.3.5.5.5);

    2. иначе, стэйт-машина должна перейти в состояние с признаком delete = false (неуказанный признак delete у события приравнивается к значению false), переход к выполнению следующего шага.

  2. Система выполняет проверку наличия атрибутов, заданных в блоке payload исходного запроса, в модели данных ресурса. Атрибуты отсутствующие в модели данных ресурса игнорируются (не участвуют в последующем обновлении данных витрины). После данной проверки, осуществляется переход к выполнению следующего шага.

  3. Система формирует SQL-выражение (определяет какие атрибуты должны быть обновлены) для обновления данных витрины (для выполнения операции upsert в prostore) с учетом следующих правил:

    • Атрибуты из payload исходного запроса применяются только, если у вызванного события признак updatable: true;

    • Атрибуты из payload исходного запроса ограничиваются блоком updatable_attributes: (если он указан) вызванного события;

    • Атрибуты, полученные при выполнении confirm (Раздел 2.3.5.3.5.5.4) из блока enrich, применяются всегда;

    • Атрибуты, заданные в блоке attributes: текущего состояния стэйт-машины, применяются всегда, за исключением случая, когда у текущего состояния установлен признак static: true.

    После формирования SQL-выражения, осуществляется переход к выполнению следующего шага.

  4. Система обновляет данные ресурса в Prostore (операция upsert) значениями атрибутов, определенных на шаге 6 и только для тех записей, которые были получены на шаге 3. После обновления данных осуществляет переход к выполнению следующего шага. Опционально: если в конфигурационном файле application.yaml, параметр state_machine_enabled: true, то вызывает процесс передачи уведомления об изменении данных витрины.

  5. Система переводит стэйт-машину в состояние, указанное в параметре to: вызванного события. После этого осуществляет переход к выполнению следующего шага.

  6. Система проверят наличие блока hooks у вызванного события:

    1. если событие содержит блок hooks, то вызывается альтернативное направление Раздел 2.3.5.3.5.5.6;

    2. иначе, обработка события считается выполненной, завершение основного направления.

6.5.5.3. Альтернативное направление для событий с типом init

Данное альтернативное направление запускается из шага 1 основного направления, когда было вызвано событие стэйт-машины с типом init. Данный тип события предполагает, что в витрину данных будут добавлены новые записи.

  1. Система выполняет проверку наличия атрибутов, заданных в блоке payload исходного запроса, в модели данных ресурса. Атрибуты отсутствующие в модели данных ресурса игнорируются (не участвуют в последующем обновлении данных витрины). После данной проверки, осуществляется переход к выполнению следующего шага.

  2. Система формирует SQL-выражение для добавления новых записей ресурса с учетом атрибутов, отобранных на шаге 1 данного альтернативного направления. После этого переходит к выполнению следующего шага.

  3. Система добавляет новые записи ресурса в Prostore (операция upsert). После этого осуществляет переход к выполнению следующего шага.

  4. Система переводит стэйт-машину в состояние, у которого задан признак initial: true. После чего завершается выполнение данного альтернативного и основного сценария.

Опционально: если в конфигурационном файле application.yaml, параметр state_machine_enabled: true, то вызывает процесс передачи уведомления об изменении данных витрины (Раздел 2.3.5.3.6.5).

6.5.5.4. Альтернативное направление для событий с блоком confirm

Данное альтернативное направление запускается из шага 2 основного направления, когда вызванное событие имеет блок confirm.

Такое событие предполагает обращение к внешнему источнику с целью передачи ему и получения от него дополнительных данных.

  1. Система формирует и передаёт REST-запрос внешнему источнику. Формирование запроса и определение адресата происходит на основании параметров, указанных в блоке confirm запускаемого события: source, endpoint, method, body. После этого переходит к выполнению следующего шага.

  2. Система обрабатывает полученный ответ. Для этого читает условия проверки ответа, заданное в блоке confirm->accept вызванного события:

    1. если ответ не соответствует условиям, заданным в accept, то Система передаст соответствующую ошибку Потребителю. Завершение данного альтернативного и основного направлений.

    2. иначе, ответ соответствует условиям, заданным в accept или блок accept не задан, переход к выполнению следующего шага.

  3. Система проверяет наличия блока enrich в описании вызванного события:

    1. если блок enrich отсутствует, то выполняется переход к шагу 3 основного направления. Данное альтернативное направление завершается.

    2. иначе, блок enrich задан, переход к выполнению следующего шага.

  4. Система извлекает данные из полученного на шаге 2 ответа и сохраняет их для последующего использования. Далее выполняется переход к шагу 3 основного направления. Данное альтернативное направление завершается.

6.5.5.5. Альтернативное направление при переходе в состояние delete

Данное альтернативное направление запускается из шага 4 основного направления, когда было вызвано событие после выполнения которого стэйт-машина должна перейти в состояние с признаком delete. Данный тип события предполагает, что в должны быть удалены данные ресурса из витрины.

  1. Система удаляет записи ресурса, полученные на шаге 3 основного направления.

  2. Система переводит стэйт-машину в состояние, у которого задан признак delete: true. После чего осуществляет переход к выполнению шага 9 основного направления. Данное альтернативное направление завершается.

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

6.5.5.6. Альтернативное направление для событий с блоком hooks

Данное альтернативное направление запускается из шага 9 основного направления, когда вызванное событие имеет блок hooks. Такое событие предполагает вызов другого события машины состояния, таким образом формируя вложенные вызовы событий. Количество уровней вложенных вызовов ограничено настройкой max_nested_event в конфигурационном файле приложения application.yaml. Если в блоке hooks определены несколько переходов (допускается указание массива), то описанные действия выполняются для каждого перехода.

  1. Система формирует REST-запрос для вызова другого события стэйт-машины по следующим правилам:

    • URL метода POST/states/{model}/{event}: {model} - берется из параметра model блока hooks; {event} - берется из параметра event блока hooks

    • conditions: Заполняется идентификаторами записей нового вызываемого ресурса (название ресурса соответствует названию model). Берутся записи исходного ресурса, полученные на шаге 3 основного направления, далее по связям в модели данных определяются идентификаторы записей для нового ресурса;

    • payload: Строится на основе payload исходного запроса, выбираются атрибуты объекта, название которого совпадает с новым вызываемым ресурсом.

  2. Система передаёт REST-запрос для вызова события стэйт-машины. Переход к выполнению шага 1 основного направления, но уже с данными другого события и ресурса. Завершение данного альтернативного направления.

6.5.6. Обработка регламентированного СМЭВ QL запроса

6.5.6.1. Общее описание

Для выполнения запроса к СМЭВ QL РЗ потребитель должен вызвать опубликованный метод POST /regulated-query.

В рамках запроса необходимо передать в теле JSON-объект заданного формата.

Таблица 2.11 содержит описание формата запроса POST /regulated-query.

Таблица 6.8 Обработка регламентированного СМЭВ QL запроса

Элемент

Описание

Пример

mnemonic

Мнемоника регламентированного запроса СМЭВ QL

"mnemonic": "test_query"

majorVersion

Мажорная версия запроса

"majorVersion": 1

minorVersion

Минорная версия запроса

"minorVersion": 0

params

Объект, содержащий значения параметров запроса в формате «параметр»: «значение»

 
"params":
{
    "month": 1
}

credentials

Объект, содержащий общие данные запроса и информация о потребителе, аналогичен запросу данных (Раздел 2.3.5.3.5)

6.5.6.2. Алгоритм обработки запроса

При поступлении СМЭВ QL РЗ от Потребителя СМЭВ QL сервер запускается процесс его обработки:

  1. Проверка запроса и доступов:

    а) СМЭВ QL РЗ с такой мнемоникой и версией зарегистрирован;

    б) проверка мнемоники Инициатора по black_list и white_list;

    в) проверка параметров запроса на соответствие описанию в шаблоне;

  2. Формирование запроса данных на основе СМЭВ QL РЗ и полученных параметров;

  3. Исполнение запроса в соответсвии с Раздел 2.3.5.3.5.3.

6.6. Уведомления при изменении данных витрины (push-сервис)

6.6.1. Регистрация получателя уведомлений

6.6.1.1. Общее описание

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

Помимо самого факта уведомления об изменении данных, можно получать определенные атрибуты ресурса, которые будут переданы в рамках нотификации.

Регистрация получателя уведомлений

Рисунок - 6.14 Регистрация получателя уведомлений

Предварительные условия:

  • Потребитель (получатель уведомлений) вызвал запрос на регистрацию получения уведомлений POST/push/consumer/create

Ход выполнения:

  1. СМЭВ QL сервер (далее Система) проверяет входящий запрос на соответствие заданной схеме (Раздел 2.3.5.3.6.1.2):

    1. если формат запроса некорректен, то Система возвращает соответствующую ошибку и завершает исполнение сценария.

    2. иначе, запрос корректного формата, переход к выполнению следующего шага.

  2. Система проверяет к какому типу относится источник данных заданного в запросе ресурса:

    1. если тип источника = smevql, то Система возвращает соответствующую ошибку и завершает исполнение сценария.

    2. иначе, тип источника = prostore, переход к выполнению следующего шага.

  3. Система сохраняет данные о получателе уведомлений в redis hash с названием push:consumers:[agent_target]:[resource], значение представляется в виде json:

{
  "bag": ["sample_field1", "sample_field2"],
  "started_at": "2022-01-01 00:00:00",
  "finished_at": "2022-12-31 23:59:59"
}

  1. Система передаёт ответ с указанием ключа:

{
  "created_consumer": {
  "key": "push:consumers:epgu:books"
  }
}

Завершает выполнение сценария.

6.6.1.2. Описание запроса POST/push/consumer/create

Таблица 6.9 Описание запроса POST/push/consumer/create

Элемент

Описание

create_consumer

Объект, содержащий информацию о получателе уведомлений и отслеживаемом ресурсе

agent

Объект, содержащий информацию об агентах СМЭВ4. Содержит следующие атрибуты:

  • source - мнемоника агента поставщика данных;

  • target - мнемоника агента получателя уведомлений.

resource

Название ресурса, изменения данных которого необходимо отслеживать

bag

Массив атрибутов ресурса, которые необходимо передавать получателю в момент уведомления об изменении данных

started_at

Время начала отслеживания изменений

finished_at

Время окончания отслеживания изменений

Пример:

{
    "create_consumer": {
        "agent": {
            "source": "zdrav777",
            "target": "epgu"
        },
        "resource": "books",
        "bag": ["sample_field1", "sample_field2"],
        "started_at": "2022-01-01 00:00:00",
        "finished_at": "2022-12-31 23:59:59"
    }
}

6.6.2. Удаление получателя уведомлений

6.6.2.1. Общее описание

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

  • Удаление получателя уведомлений на конкретный ресурс: POST/push/consumer/delete/resource

  • Удаление получателя уведомлений на все ресурсы: POST/push/consumer/delete

6.6.2.2. Сценарий выполнения

Удаление получателя уведомлений

Рисунок - 6.15 Удаление получателя уведомлений

Предварительные условия:

  • Потребитель (получатель уведомлений) вызвал запрос на удаление получения уведомлений POST/push/consumer/delete или POST/push/consumer/delete/resource

Ход выполнения:

  1. Система проверяет входящий запрос на соответствие заданной схеме (Раздел 2.3.5.3.6.2.3):

    1. если формат запроса некорректен, то Система возвращает соответствующую ошибку и завершает исполнение сценария.

    2. иначе, запрос POST/push/consumer/delete/resource корректного формата, переход к выполнению шага 2 или запрос POST/push/consumer/delete корректного формата, переход к выполнению шага 3.

  2. Система удаляет данные о получателе уведомлений на конкретный ресурс из redis:

    1. hash с названием push:consumers:[agent_target]:[resource];

    2. cсылку на hash из set c названием push:consumers:by:agent_target:[agent_target];

    3. ссылку на hash из set c названием push:consumers:by:resource:[resource];

    4. Переходит к выполнению шага 4.

  3. Система удаляет данные о получателе уведомлений на все ресурсы из redis:

    1. получает список hash из set c названием push:consumers:by:agent_target:[agent_target], далее по всем hash:

      • удаляет из set push:consumers:by:resource:[resource] имя hash;

      • удаляет set c названием push:consumers:by:agent:target:[agent_target];

      • удаляет hash;

    2. Переходит к выполнению шага 4.

  4. Система передаёт ответ с указанием удаленных ключей:

[
  {
    "deleted_consumer": {
    "key": "push:consumers:epgu:books"
    }
  },
...
]

  1. Завершает выполнение сценария.

6.6.2.3. Описание запроса

Таблица 6.10 Описание запроса на удаление получателя уведомлений

Элемент

Описание

delete_consumer

Объект, содержащий информацию о получателе уведомлений и отслеживаемом ресурсе

agent

Объект, содержащий информацию об агентах СМЭВ4. Содержит следующие атрибуты:

  • source - мнемоника агента поставщика данных;

  • target - мнемоника агента получателя уведомлений.

resource

Название ресурса, при изменении данных которого должны перестать приходить уведомления для заданного получателя. Заполняется только в запросе POST/push/consumer/delete/resource

Пример:

{
    "delete_consumer": {
        "agent": {
            "source": "zdrav777",
            "target": "epgu"
        },
        "resource": "books"
    }
}

6.6.3. Запрос списка получателей уведомлений

6.6.3.1. Общее описание

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

  • Получатели уведомлений конкретного ресурса: GET/push/consumer/agent_targets/{resource};

  • Все получатели уведомлений данного СМЭВ QL: GET/push/consumer.

6.6.3.2. Сценарий выполнения

Запрос списка получателей уведомлений

Рисунок - 6.16 Запрос списка получателей уведомлений

Предварительные условия:

  • Клиент вызвал запрос списка получателей уведомлений GET/push/consumer или GET/push/consumer/agent_targets/{resource}.

Ход выполнения:

  1. Система выполняет поиск данных о получателях уведомлений в redis. При этом, если был вызван метод GET/push/consumer, то Система получает все имена hash из set push:consumers и значения всех hash, а если был вызван метод GET/push/consumer/agent_targets/{resource}, то Система получает имена hash из set push:consumers:by:resource:[resource] и значения hash в рамках указанного ресурса.

    1. если данные не были найдены, то Система возвращает соответствующую ошибку и завершает исполнение сценария.

    2. иначе, данные были найдены, переход к выполнению следующего шага.

  2. Система формирует и передаёт ответ клиенту с указанием:

    1. перечня всех получателей уведомлений, если был вызван метод GET/push/consumer.

    2. перечня получателей уведомлений при изменении конкретного ресурса, если был вызван метод GET/push/consumer/agent_targets/{resource}.

Формат ответа не меняется в зависимости от вызванного метода, отличается только количество передаваемых данных. Пример ответа:

[
  {
    "agent": {
        "target": "epgu"
        },
    "key": "push:consumers:epgu:books"
    "resource": "books",
    "bag": ["sample_field1", "sample_field2"],
    "started_at": "2022-01-01 00:00:00",
    "finished_at": "2022-12-31 23:59:59"
  },
...
]

6.6.4. Запрос данных об отслеживаемых ресурсах

6.6.4.1. Общее описание

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

Для этого клиенту необходимо вызвать метод GET/push/consumer/resources/{agent_target}, где в качестве {agent_target} передать значение мнемоники Агента Потребителя.

6.6.4.2. Сценарий выполнения

Запрос данных об отслеживаемых ресурсах

Рисунок - 6.17 Запрос данных об отслеживаемых ресурсах

Предварительные условия:

  • Клиент вызвал запрос списка отслеживаемых ресурсов GET/push/consumer/resources/{agent_target}.

Ход событий:

  1. Система выполняет поиск данных об отслеживаемых ресурсах в redis: получает имена hash из set push:consumers:by:agent_target:[agent_target] и значения hash.

    1. если данные не были найдены, то Система возвращает соответствующую ошибку и завершает исполнение сценария.

    2. иначе, данные были найдены, переход к выполнению следующего шага.

  2. Система формирует и передаёт ответ клиенту. Завершает выполнение сценария.

Пример ответа:

[
  {
    "agent": {
        "target": "epgu"
        },
    "key": "push:consumers:epgu:books"
    "resource": "books",
    "bag": ["sample_field1", "sample_field2"],
    "started_at": "2022-01-01 00:00:00",
    "finished_at": "2022-12-31 23:59:59"
  },
...
]

6.6.5. Передача уведомления при вызове события машины-состояний

6.6.5.1. Общее описание

Передача уведомлений об изменении данных витрины средствами СМЭВ QL сервер возможна при выполнении определенного перехода машины состояний (Раздел 2.3.5.3.5.5).

Формирование и передача уведомления происходит в следующих случаях:

  • Добавление новой записи в Prostore (для событий с типом init);

  • Удаление данных в Prostore (при переходе в состояние с типом delete);

  • Обновление данных в Prostore.

6.6.5.2. Сценарий выполнения

Передача уведомления при вызове события машины-состояний

Рисунок - 6.18 Передача уведомления при вызове события машины-состояний

Предварительные условия:

  • Стэйт машина передала перечень измененных (новые, обновлённые, удалённые) записей ресурсов;

  • Получатель зарегистрировал REST-метод (POST/api/v1/smevql/notify) для приёма уведомлений.

Ход событий:

Данные шаги выполняются в цикле для каждой записи измененного ресурса.

  1. Система проверяет есть ли зарегистрированные получатели уведомлений при изменении заданного ресурса. Для этого читает из redis set c названием push:consumers:by:resource ссылки на зарегистрированных получателей, для каждой ссылки: читает из redis hash данные получателя; проверяет активность получателя на текущий момент.

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

    2. иначе, найден один или более активных получателей, переход к выполнению следующего шага.

  2. Система формирует сообщение (содержимое уведомления) для каждого получателя, определенного на шаге 1 (Раздел 2.3.5.3.6.5.3). При необходимости (если при регистрации получения уведомлений (Раздел 2.3.5.3.6.1) был заполнен раздел bag) получает дополнительные атрибуты измененного ресурса из витрины. Далее переходит к выполнению следующего шага.

  3. Система отправляет уведомления параллельно каждому получателю (отправка уведомления выполняется методом post на адрес агента) и дожидается ответа:

    1. если ответа не поступило в течение заданного таймаута или в ответе получена ошибка (400-500), то Система фиксирует попытку отправки (накопление счётчика) и переходит к выполнению следующего шага.

    2. иначе, уведомление было успешно отправлено получателю, завершение сценария для данной записи измененного ресурса.

  4. Система определяет требуется ли выполнить повторную отправку уведомления. Для этого сравнивает текущее значение счётчика попыток отправки уведомления с параметром, заданным в конфигурационном файле application.yaml push->retry->max_attempts:

    1. если максимальное количество попыток отправки уведомления превышено, то повторная отправка не требуется, Система сохраняет соответствующее сообщение об ошибке в лог, завершение сценария для данной записи измененного ресурса.

    2. иначе, требуется повторная попытка отправки уведомления, Система возвращается к выполнению шага 3.

6.6.5.3. Описание формата уведомления

Таблица 6.11 Описание формата уведомления

Элемент

Описание

agent

Объект, содержащий информацию об агентах СМЭВ4

source

мнемоника агента поставщика данных

target

мнемоника агента получателя уведомлений

payload

Сутевые данные уведомления

type

Тип уведомления.

Заполняется значение entity, это означает, что уведомление инициировано событием стэйт машины

source

Мнемоника источника данных измененного ресурса

entity

Данные, полученные из стэйт машины. Содержит следующие атрибуты:

  • resource - название измененного ресурса;

  • entity_id - идентификатор записи измененного ресурса;

  • state - состояние стэйт машины;

  • updated_at - время изменения записи ресурса;

  • bag - перечень атрибутов измененного ресурса со значениями.

push_id

Идентификатор уведомления

Пример:

{
    "notification": {
        "agent": {
            "source": "zdrav777",
            "target": "epgu"
        },
        "payload": {
          "type": entity
          "source": "prostore",
          "entity": {
            "resource": "books",
            "entity_id": 25,
            "state": "received",
            "updated_at": "2023-11-23 12:25:31",
            "bag": {
            "sample_field1": "sample_value"
            }
          }
        },
        "push_id": "UUID"

    }
}

6.6.6. Регистрация метода для получения уведомлений на стороне клиента

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

  1. Развернуть на своей стороне REST-сервис, в котором реализовать метод POST/api/v1/smevql/notify;

  2. Настроить REST-сервис для взаимодействия с Агентом СМЭВ4 Потребителя;

  3. Зарегистрировать REST-сервис в СМЭВ4;

  4. Добавить критерии доступа (права поставщику данных) для запросов к развернутому REST-сервису;

  5. Выполнить процедуру регистрации получения уведомлений в СМЭВ QL.

Таблица 6.12 Спецификация запроса

Элемент

Описание

agent

Объект, содержащий информацию об агентах СМЭВ4

source

мнемоника агента поставщика данных

target

мнемоника агента получателя уведомлений

payload

Сутевые данные уведомления

type

Тип уведомления.

На текущий момент всегда заполняется значение entity, это означает, что уведомление инициировано событием стэйт машины

source

Мнемоника источника данных измененного ресурса

entity

Данные, полученные из стэйт машины. Содержит следующие атрибуты:

  • resource - название измененного ресурса;

  • entity_id - идентификатор записи измененного ресурса;

  • state - состояние стэйт машины;

  • updated_at - время изменения записи ресурса;

  • bag - перечень атрибутов измененного ресурса со значениями.

push_id

Идентификатор уведомления

Приммер:

{
    "notification": {
        "agent": {
            "source": "zdrav777",
            "target": "epgu"
        },
        "payload": {
          "type": entity
          "source": "prostore",
          "entity": {
            "resource": "books",
            "entity_id": 25,
            "state": "received",
            "updated_at": "2023-11-23 12:25:31",
            "bag": {
            "sample_field1": "sample_value"
            }
          }
        },
        "push_id": "UUID"

    }
}

6.6.7. Передача уведомления на основе сообщения топика Prostore

6.6.7.1. Общее описание

При изменении данных витрины, Prostore формирует событие типа WRITE_OK и передаёт его в системный топик status.event.

Примеры сообщений системного топика:

//пример сообщения для версионированной таблицы
key: {"datamart":"foo","datetime":"2024-02-05 09:52:40.65","event":"WRITE_OK","eventLogId":"f5706095-9dc9-445f-bc93-11683676e3b3"}
value: {"entity":"cat","cn":1,"ts":1707126760643000,"rowsAffected":1}

//пример сообщения для не версионированной таблицы
key: {"datamart":"foo","datetime":"2024-02-05 14:34:23.119","event":"WRITE_OK","eventLogId":"ebb8d74c-d0c2-4f2c-9177-872d1bcb64c6"}
value: {"entity":"catp","cn":null,"ts":null,"rowsAffected":1}

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

6.6.7.2. Сценарий выполнения

Схема передачи уведомления на основе сообщения топика Prostore

Рисунок - 6.19 Схема передачи уведомления на основе сообщения топика Prostore

Предварительные условия:

  • Получатель зарегистрировал REST-метод POST/api/v1/smevql/notify для приёма уведомлений;

  • В топике status.event появилось сообщение типа WRITE_OK.

Ход событий:

  1. СМЭВ QL (далее Система) проверяет изменение данных выполнено в таблице вида standalone:

    1. если да, то переходит к выполнению следующего шага

    2. иначе, изменения не в standalone таблице, переход к выполнению шага 3.

  2. Система определяет readable название standalone-таблицы. Для этого берет, полученное в сообщении название writable, и ищет соответствующее ему readable название в блоке standalone-tables конфигурационного файла application.yaml. Далее переходит к выполнению следующего шага.

  3. Далее Система выполняет поиск ресурса, к которому относится измененная таблица, на основе загруженных моделей данных:

    1. если ресурс не найден, то Система сохраняет соответствующее сообщение в лог и завершает выполнение сценария.

    2. иначе, ресурс определен, переход к выполнению следующего шага.

  4. Система проверяет есть ли зарегистрированные получатели уведомлений при изменении заданного ресурса. Для этого читает из redis set c названием push:consumers:by:resource ссылки на зарегистрированных получателей, для каждой ссылки: читает из redis hash данные получателя; проверяет активность получателя на текущий момент.

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

    2. иначе, найден один или более активных получателей, переход к выполнению следующего шага.

  5. Затем формирует запрос к Prostore для получения данных о существовании и типе изменённой таблицы. После чего переходит к выполнению следующего шага.

  6. Система получает ответ с информацией об измененной таблице:

    1. если таблица не существует в Prostore, то Система сохраняет соответствующее сообщение в лог и завершает выполнение сценария.

    2. иначе, таблица существует в Prostore, переход к выполнению следующего шага.

  7. Система обрабатывает значение полученного типа таблицы:

    1. если таблица нетемпоральная (включая proxy-таблицы) , то переход к выполнению следующего шага.

    2. иначе, таблица темпоральная, переход к выполнению шага 9.

  8. Система формирует sql-запрос к Prostore для получения даты последнего изменения (anchor) и даты удаления (soft-delete) записи. После чего переходит к выполнению следующего шага.

  9. Система формирует сообщение (содержимое уведомления) для каждого получателя, определенного на шаге 4 (формат уведомления см. Таблица 2.16). При этом если при регистрации получения уведомлений был заполнен раздел bag, то он не формируется. Далее переходит к выполнению следующего шага.

  10. Система отправляет уведомления параллельно каждому получателю (отправка уведомления выполняется методом POST/api/v1/smevql/notify на адрес агента) и дожидается ответа:

  1. если ответа не поступило в течение заданного таймаута или в ответе получена ошибка (400-500), то Система фиксирует попытку отправки (накопление счётчика) и переходит к выполнению следующего шага.

  2. иначе, уведомление было успешно отправлено получателю, завершение сценария для данной записи измененного ресурса.

  1. Система определяет требуется ли выполнить повторную отправку уведомления. Для этого сравнивает текущее значение счётчика попыток отправки уведомления с параметром, заданным в конфигурационном файле application.yaml push->retry->max_attempts:

    1. если максимальное количество попыток отправки уведомления превышено, то повторная отправка не требуется, Система сохраняет соответствующее сообщение об ошибке в лог, завершение сценария для данной записи измененного ресурса.

    2. иначе, требуется повторная попытка отправки уведомления, Система возвращается к выполнению шага 10.

Таблица 6.13 Описание формата уведомления

Элемент

Описание

agent

Объект, содержащий информацию об агентах СМЭВ4

source

мнемоника агента поставщика данных

target

мнемоника агента получателя уведомлений

payload

Сутевые данные уведомления

type

Тип уведомления.

Заполняется значение batch, это означает, что уведомление инициировано событием системного топика Prostore

source

немоника источника данных измененного ресурса

batch

Данные, полученные из сообщения системного топика Prostore.

Содержит следующие атрибуты:

  • resource - название измененного ресурса

  • updated_at - время изменения события

  • sys_cn - номер изменения

  • anchor - время изменения записи в БД. Для темпоральных таблиц всегда null

  • soft-delete - время удаления записи в БД. Для темпоральных таблиц всегда null

push_id

Идентификатор уведомления

Пример:

{
    "notification": {
        "agent": {
            "source": "zdrav777",
            "target": "epgu"
        },
        "payload": {
        "type": batch
        "source": "prostor",
        "batch": {
            "resource": "books",
            "updated_at": "2023-11-23 12:25:31",
            "sys_cn": 134,
            "anchor": null,
            "soft-delete": null
            }
        },
        "push_id": "UUID"
    }
}

6.7. Работа с Регламентированными СМЭВ QL запросами

6.7.1. Создание СМЭВ QL РЗ

Для создания СМЭВ QL РЗ необходимо создать директорию соответствующую мнемонике запроса в директории queries в файловой системе СМЭВ QL сервера.

Мнемоники СМЭВ QL РЗ являются регистронезависимыми. В случае обнаружения дублирующих запросов при загрузке или валидации СМЭВ QL сервер возвращает warning с сообщением о дублировании РЗ. В случае дублирования должен использоваться первый найденный РЗ, а другие игнорироваться.

В данной директории должны содержаться поддерриктории версий СМЭВ QL РЗ, в каждой из которых расположен файл шаблона запроса query.json.

Файловая система queries

Рисунок - 6.20 Файловая система queries

6.7.1.1. Формат описания шаблона запроса

Шаблон запроса описывается в формате JSON и состоит из двух блоков: query и params.

Требовния к блоку запроса (query):

  1. Блок должен соответствовать схеме для стандартного запроса данных, за исключением наличия мест для подстановки параметров;

  2. Подстановка параметра в блок запроса (query) выполняется с использование двоеточия перед мнемоникой параметра («:month» из примера);

  3. Не должен содержать параметры не описанные в блоке параметров;

  4. Должен содержать все параметры, описанные в блоке параметров.

Требовния к блоку параметров (params):

  1. Данный блок является опциональным (допустимо создание запросов без параметров);

  2. Должен содержать массив параметров, для каждого из которых указывается:

    а) Мнемоника (должна быть уникальна для данного РЗ, регистронезависимая);

    б) Описание;

    в) Тип параметра необходимо выбирать из JSON типов:

    1. STRING

    2. NUMBER

    3. INTEGER

    4. BOOLEAN

    5. ARRAY

    6. OBJECT

Другие блоки, кроме query и params в шаблоне запрещены.

Пример определения СМЭВ QL РЗ:

{   // аналогично блоку query в запросе к СМЭВ QL серверу POST /data
    "query": {
        "ticket": {
            "conditions": {
                // подстановка параметров
                "month": ":month"
            },
            "attributes": ["id", "price"]
        }
    },
    // блок описания параметров
    "params": [{
            "mnemonic": "month",
            "descripton": "Месяц за который необходимо выгрузить статистику",
            "type": "INTEGER"
        }
    ]
}

6.7.2. Создание новой версии СМЭВ QL РЗ

Добавление новых версий СМЭВ QL РЗ производится Администратором сервиса в ручную. Для этого необходимо в директории соответствующей мнемонике запроса создать новую поддиректорию с номером версии и новым файлом query.json.

При добавлении версии СМЭВ QL РЗ не требуется какое-либо изменение модели данных СМЭВ QL.

6.7.3. Проверка валидности СМЭВ QL РЗ

Функция валидации СМЭВ QL РЗ вызывается вручную Администратором сервиса из консоли, командой:

./smevql test query <query-name1>.<major_version>.<minor_version> <query-name2>.<major_version>.<minor_version>  ... | all

При этом проверяется

  • список СМЭВ QL РЗ <query-name1>.<major_version>.<minor_version> <query-name2>.<major_version>.<minor_version> ...;

  • все СМЭВ QL РЗ, при выборе опции all.

Каждый из РЗ проверяется на соответствие формату описания, а также на наличие дублей.