3. Основные понятия СМЭВ QL

3.1. Ресурс

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

Пример определения ресурса в модели данных СМЭВ-QL:

resources:
  - tickets: *base_model
    name: Билеты
    fields: "id", "passengerid", "tripid", "number", "bycard", "price", "sold"

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

"query": {
        "tickets": {
            "conditions": {
                "number": 1
            },
            "attributes": ["id", "passengerid", "tripid", "number", "bycard", "price", "sold"]
        }

3.2. Базовая модель данных

Базовая модель данных - это описание типовых элементов и форматов данных, которые могут использоваться (наследоваться) при создании пользовательских моделей. Автоматически генерируется при создании СМЭВ QL и не может быть отредактирована вручную.

Базовая модель не описывает схему данных витрины и не участвует в логике СМЭВ QL при обработке запросов. Хранится в файловой системе СМЭВ QL сервера по пути: models>base>1.0>model.yaml

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

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

3.3. Модель данных

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

Каждая модель представляет из себя YAML-файл, который должен быть соединен с базовой моделью (Базовая модель данных) данных для прохождения валидации.

Хранится в файловой системе СМЭВ QL сервера по пути: models>custom>1.0>model.yaml

3.3.1. Структура модели данных

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

Мета-данные и поля модели

resources:
# slots — техническое название модели, по нему производятся все связи
- slots: *base_model
# значение name — название модели на русском языке
    name: Слоты
# 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

Второй блок модели описывает связи моделей друг с другом через ключи primary_key и foreign_key.

Ключи могут быть составными (описывается массивом), ключи не обязательно должны быть ключами из БД.

Связи имеют два типа:

  1. belongs_to

  2. has_many (один ко многим)

Связи модели

# Блок 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 ]

Блок ограничений и разрешений использования условий поиска.

Связи модели

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

Блок — extract, описывает названия source из которого нужно извлекать модель и ее таблицу.

Источники модели

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

Источники по условиям

В блоке c указанием источника в модели допускается указание условий его выбора через блок conditions. Блок 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

3.3.2. Загрузка

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

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

Примечание

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

3.3.3. Guard-атрибуты

Для ограничения возможности получения некоторых атрибутов без предварительного предоставления их же (или дополнительных) значения, извлекающим необходимо определить атрибуты-ограничители в блоке guard.

Пример:

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

В примере извлечение first_name не ограничивается. Для получения last_name фамилия должна быть передана в блоке conditions, а для получения snils в conditions должны присутствовать фамилия, имя и сам СНИЛС.

3.4. Распределённый запрос

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

Описание источников получения данных задается на уровне модели данных в блоке ``extract:``(sources_by_conditions). При этом Потребитель всегда обращается к одному СМЭВ QL, от которого ожидает получение всех данных о всех источников.

Пример схемы распределенного запроса

Рисунок - 3.11 Пример схемы распределенного запроса