Введение ========== Общие Сведения ---------------- Настоящий документ описывает правила и приёмы использования возможностей инфраструктуры электронного правительства (далее – ИЭП), которые позволяют участникам межведомственного взаимодействия (далее – УВ) решать задачи передачи сведений с использованием единого сервиса доступа к данным СМЭВ (далее – СМЭВ4) между информационными системами участников взаимодействия (далее – ИС УВ). Термины и сокращения, используемые в данном документе, представлены в соответствующем разделе. Сторонние руководства и инструкции, приведенные в данном документе размещены на портале `ЕСКС `_. Нормативно-правовые основания ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Данный документ разработан в целях реализации и во исполнение: - Постановления Правительства Российской Федерации от 8 сентября 2010 года № 697 «О единой системе межведомственного электронного взаимодействия»; - Распоряжения Правительства Российской Федерации от 3 июня 2019 года №1189-р «Об утверждении Концепции создания и функционирования национальной системы управления данными и плана мероприятий («дорожную карту») по созданию национальной системы управления данными на 2019–2021 годы» (далее – Концепция); - Постановления Правительства Российской Федерации от 3 июня 2019 года № 710 «О проведении эксперимента по повышению качества и связанности данных, содержащихся в государственных информационных ресурсах»; - Федерального закона от 27 июля 2010 г. № 210-ФЗ «Об организации предоставления государственных и муниципальных услуг»; - мероприятий федерального проекта «Цифровое государственное управление» национальной программы «Экономика данных и цифровая трансформация государства», паспорт которого утвержден протоколом проектного комитета по национальному проекту «Экономика данных и цифровая трансформация государства» от 26 ноября 2024 г. № 1: - 06.01.011.001.004 «Разработка функциональных и технических требований к информационным системам НСУД (включая требования к функциям получения, очистки и преобразования данных, хранения и обработки данных, визуального представления данных, управления метаданными, межведомственного взаимодействия); - 06.01.011.001.006 Разработка, адаптация программного обеспечения и разработка архитектуры и проектных решений на НСУД и ее части, внедрение функционала НСУД, включая пусконаладочные работы, проведение предварительных испытаний, проведение опытной эксплуатации, доработку программного обеспечения, дополнительную наладку технических средств и проведение приемочных испытаний НСУД в соответствии с 06.01.011.001.005. Виды информационного обмена с использованием СМЭВ ---------------------------------------------------- Виды информационного обмена, поддерживаемые СМЭВ4, приведены в :numref:`tab_info`. .. _tab_info: .. table:: Виды информационного обмена +---+----------------------------+------------------------------------------------------------------------------+ | № | Вид информационного обмена | Характеристика | +===+============================+==============================================================================+ | 1 | Обмен с использованием | Обмен с использованием регламентированных запросов типа «SQL-запрос». | | | SQL-запросов | | | | | :numref:`rz_exchange` содержит описание данного вида обмена. | +---+----------------------------+------------------------------------------------------------------------------+ | 2 | Обмен с использованием | Обмен данными с использованием регламентированных запросов типа «Рассылка | | | Рассылок (для Компонента | (для Компонента «Витрина данных» версии 1.x)» в соответствии с созданной | | | «Витрина данных» версии | подпиской. | | | 1.x) | | | | | :numref:`distribution_exchange_1` содержит описание данного вида обмена. | | | | | | | | Поддерживается только для Компонента «Витрина данных» версии ниже 2.x. | +---+----------------------------+------------------------------------------------------------------------------+ | 3 | Обмен с использованием | Обмен с использованием регламентированных запросов типа «Рассылка (для | | | Рассылок (для Компонента | Компонента «Витрина данных» версии 2.x)». | | | «Витрина данных» версии | | | | 2.x) | :numref:`distribution_exchange_2` содержит описание данного вида обмена. | | | | | | | | Поддерживается только для Компонента «Витрина данных» версии 2.x и выше. | +---+----------------------------+------------------------------------------------------------------------------+ | 4 | Обмен с использованием | Обмен с использованием регламентированных запросов типа «Rest-сервис» к | | | запросов к REST-сервису ИС | зарегистрированным в СМЭВ4 REST-сервисам ИС Ответчика. | | | Ответчика | | | | | :numref:`rest_exchange` содержит описание данного вида обмена. | +---+----------------------------+------------------------------------------------------------------------------+ Участники информационного обмена с использованием СМЭВ4 -------------------------------------------------------------- **Участник взаимодействия** - это орган или организация, участвующие в информационном обмене через СМЭВ4. :numref:`participants` иллюстрирует общую схему взаимодействия участников. .. _participants: .. figure:: img/participants.png :align: center :alt: Участники информационного обмена с использованием СМЭВ4 Участники информационного обмена с использованием СМЭВ4 При участии в информационном обмене через СМЭВ4 УВ может одновременно выступать как в роли Поставщика и/или Ответчика, так и в роли Потребителя данных и/или Инициатора запроса в зависимости от используемого вида обмена. *В информационных обменах с использованием Витрин данных* УВ может иметь роль Поставщика и Потребителя. Каждый УВ может выступать одновременно как в качестве Поставщика данных, предоставляя данные со своих Витрин, так и в качестве Потребителя данных, выполняя запросы к другим УВ. **Потребители данных** имеют возможность получать сведения из Витрины Поставщиков данных следующими способами: 1. используя Регламентированный SQL-запрос (:numref:`rz_exchange`); 2. сформировав подписку на регламентированный запрос типа «Рассылка» и получая сведения в виде уведомлений об изменениях (:numref:`distribution_exchange_1` и :numref:`distribution_exchange_2`). **Поставщики данных** обеспечивают доступ к актуальным данным на Витринах: 1. размещают и актуализируют данные на Витринах; 2. осуществляют подключение Витрин к СМЭВ4; *В информационных обменах с использованием запросов к REST-сервису ИС Ответчика* (без использования Витрин) УВ может иметь роль Инициатора и Ответчика. Каждый УВ может выступать одновременно как в качестве Ответчика, предоставляя данные c сервиса ИС, так и в качестве Инициатора запроса, выполняя запросы к другим УВ. **Инициаторы запроса** имеют возможность получать сведения из ИС Ответчика, выполнив запрос к REST-сервису ИС Ответчика (:numref:`rest_exchange`). **Ответчики** разворачивают REST-сервисы и предоставляют к ним доступ через СМЭВ4. Информационный обмен участников взаимодействия с использованием СМЭВ4 --------------------------------------------------------------------------- Для осуществления информационного обмена с использованием СМЭВ4 должно быть обеспечено подключение ИС УВ к СМЭВ4 с помощью Агента СМЭВ4 в соответствии с «Руководством администратора Агента СМЭВ4». .. _rz_exchange: Обмен с использованием Регламентированных SQL-запросов ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _rz_exchange_description: Общее описание информационного обмена ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Обмен с использованием регламентированных SQL-запросов используется для получения сведений из Витрины Поставщика данных. Данный механизм обеспечивает: 1. разграничение доступа ИС Потребителей данных к регламентированным SQL-запросам путём использования принципа выдачи/изъятия прав через ЛК УВ; 2. (опционально) лимитирование запросов ИС Потребителей данных к регламентированным SQL-запросам / Витринам данных; 3. (опционально) задание в ЕИП НСУД последовательности выполнения подзапросов к Витрине данных при регистрации распределенных регламентированных SQL-запросов; 4. (опционально) сохранение данных запросов и ответов, переданных в процессе информационного обмена; 5. (опционально) юридическую значимость обмена. Требования к участникам взаимодействия ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Требования к Поставщикам данных ################################ Поставщик данных для участия в информационном обмене с использованием Регламентированных SQL-запросов должен выполнить следующие требования. .. _tab_providers_requirements: .. table:: Требования к Поставщикам данных +----+--------------------------------+------------------------------------------------------+ | № | Требования | Инструкция | +====+================================+======================================================+ | 1 | Зарегистрировать ИС в СМЭВ4 | Инструкция приведена в документе «Регламент | | | | Правила и процедуры работы в СМЭВ 4» | +----+--------------------------------+------------------------------------------------------+ | 2 | Развернуть и настроить в | Инструкция приведена в документе «Руководство | | | своем контуре Агент СМЭВ4 | администратора Агента СМЭВ4» | +----+--------------------------------+ | | 3 | Обеспечить сетевую связанность | | | | Агента с СМЭВ4 | | +----+--------------------------------+------------------------------------------------------+ | 4 | Развернуть в своем контуре | Исходные коды и документация Компонента «Витрина | | | Компонент Витрина данных | данных» размещены в НФАП | +----+--------------------------------+ | | 5 | Настроить Компонент Витрина | | | | данных для взаимодействия с | | | | Агентом | | +----+--------------------------------+------------------------------------------------------+ | 6 | Настроить «Сервис Формирования | Инструкция приведена в документе «Руководство | | | документов» и pebble-шаблоны | администратора Компонента «Витрина данных» | | | для формирования печатных форм | | | | (опционально, если Поставщик | | | | предоставляет печатные формы) | | +----+--------------------------------+------------------------------------------------------+ | 7 | Загрузить модель данных | Инструкция приведена в документе «Инструкция по | | | Витрины в СМЭВ4 | работе в ЕИП НСУД» | +----+--------------------------------+ | | 8 | Связать Витрину данных и ИС | | | | | | +----+--------------------------------+------------------------------------------------------+ | 9 | Зарегистрировать | Инструкция приведена в документе «Инструкция по | | | Регламентированные SQL-запросы | работе в ЕИП НСУД» | | | в СМЭВ4 | | +----+--------------------------------+------------------------------------------------------+ | 10 | Создать представление view | :numref:`view_create_rule` | | | | | | | (только для витрин версии 2.0.0| | | | и выше) | | +----+--------------------------------+------------------------------------------------------+ | 11 | Добавить критерии доступа к | Инструкция приведена в документе «Руководство | | | Регламентированному | пользователя ЛК УВ» | | | SQL-запросу (Согласовать право | | | | доступа) | | +----+--------------------------------+------------------------------------------------------+ Требования к Потребителям данных ################################### Потребитель данных для участия в информационном обмене с использованием Регламентированных SQL-запросов должен выполнить следующие требования. .. _tab_consumer_requirements: .. table:: Требования к Потребителям данных +---+----------------------------------+------------------------------------------------------+ | № | Требования | Инструкция | +===+==================================+======================================================+ | 1 | Зарегистрировать ИС в СМЭВ4 | Инструкция приведена в документе «Регламент | | | | Правила и процедуры работы в СМЭВ 4» | +---+----------------------------------+------------------------------------------------------+ | 2 | Развернуть и настроить в своем | Инструкция приведена в «Руководство администратора | | | контуре Агент СМЭВ4 | Агента СМЭВ4» | +---+----------------------------------+ | | 3 | Обеспечить сетевую связанность | | | | Агента с СМЭВ4 | | +---+----------------------------------+ | | 4 | Обеспечить свободный объем | | | | оперативной памяти на стороне | | | | Агента не менее размера | | | | передаваемых и получаемых данных | | +---+----------------------------------+------------------------------------------------------+ | 5 | Настроить ИС для выполнения | :numref:`consumer_protocol` | | | запросов и обработки данных, | | | | получаемых от СМЭВ4 для | | | | взаимодействия с Агентом СМЭВ4 | | +---+----------------------------------+------------------------------------------------------+ | 6 | Согласовать право доступа к | Инструкция приведена в «Руководство пользователя | | | Регламентированному | ЛК УВ» | | | SQL-запросу для своей ИС | | +---+----------------------------------+------------------------------------------------------+ .. _participants_interaction: Взаимодействие участников обмена ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Взаимодействие Ядра СМЭВ4 с Агентами СМЭВ4 осуществляется с использованием Протокола СМЭВ4. 2. Взаимодействие Агента Поставщика данных с Витриной Поставщика данных осуществляется с использованием зарезервированных топиков брокера сообщений Apache Kafka. :numref:`provider_kafka_topics` содержит перечень топиков Apache Kafka. 3. Взаимодействие ИС Потребителя с Агентом Потребителя осуществляется через REST или JDBC-интерфейс в соответствии со спецификацией :numref:`consumer_protocol`. :numref:`participants_interaction_img` иллюстрирует общую схему взаимодействия участников обмена. .. _participants_interaction_img: .. figure:: img/participants_interaction.png :align: center :alt: Информационный обмен при выполнении Регламентированного SQL-запроса с использованием СМЭВ4 Информационный обмен при выполнении Регламентированного SQL-запроса с использованием СМЭВ4 Информационный обмен с использованием SQL-РЗ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :numref:`query_process` содержит диаграмму последовательности осуществления информационного обмена с использованием Регламентированных SQL-запросов. *В контуре Потребителя данных (УВ 3 или 4 на схемах):* 1. ИС Потребителя данных передаёт SQL-запрос Агенту СМЭВ4. Передача запроса может осуществляться с использованием: - JDBC-подключения; - REST-интерфейса. Настройки подключения выполняются в рамках настройки ИС для взаимодействия с Агентом СМЭВ4 согласно «Руководству администратора Агента СМЭВ4». :numref:`consumer_protocol` содержит Спецификацию взаимодействия. 2. Агент Потребителя данных проверяет наличие включенного режима блокировки на отправку запросов (:numref:`blocking`). Дальнейшие шаги выполняются в случае отсутствия блокировки. 3. Агент Потребителя подписывает запрос ЭП ОВ. 4. Агент Потребителя передает полученный запрос в Ядро СМЭВ4. *Ядро СМЭВ4 (после получения запроса от Агента Потребителя данных):* 5. Выполняет проверку ЭП ОВ, которой подписан запрос, проверку запроса на корректность и наличие у Потребителя доступа на выполнение запросов к данным. Если хотя бы одна из проверок возвращает отрицательный результат, то прекращает выполнение запроса и возвращает Агенту Потребителя соответствующую ошибку в качестве результата запроса. 6. Выполняет преобразование полученной мнемоники Регламентированного SQL-запроса в SQL-выражение в соответствии с загруженным определением и формирует один или несколько запросов в адрес Витрин Поставщиков данных (далее – подзапросы). 7. Выполняет проверку соответствия ограничениям, заданным в Ядре СМЭВ4: - на интенсивность запросов от ИС Потребителя данных за интервал времени; - на общий объем данных в запросе и подзапросах за интервал времени. В случае превышения установленных ограничений Ядро СМЭВ4 прекращает выполнение запроса или подзапроса и возвращает Агенту Потребителя сообщение о включении режима блокировки. Агент Потребителя при получении такого сообщения активирует режим блокировки и отвечает ошибкой на запросы от Потребителя к заблокированному ресурсу. 8. Передаёт каждый подзапрос в соответствующий Агент Поставщика. *В контуре Поставщика данных (УВ 1 и 2 на схемах):* 9. Агент Поставщика данных получает запрос и проверяет ЭП ОВ, которой подписан запрос. Дополнительно для простых исходных запросов Потребителя данных в рамках получения подзапроса от Ядра СМЭВ4 в Агент Поставщика передается исходный запрос с ЭП ОВ и сертификатом Потребителя данных, отправившего исходный запрос. *Если на стороне Агента Поставщика данных развернут и включен Сервис проверки полномочий:* 10. Сервис проверки полномочий выполняет проверку подтверждения доступа на выполнение Регламентированного SQL-запроса для Потребителя данных, отправившего запрос. Если для запроса не подтвержден доступ, то Агент Поставщика прекращает выполнение запроса и возвращает Агенту Потребителя соответствующую ошибку в качестве результата запроса. При подтвержденном доступе выполнение запроса продолжается. *В контуре Поставщика данных (УВ 1 и 2 на схемах):* 11. Агент Поставщика данных помещает запрос в зарезервированный топик брокера сообщений Apache Kafka. 12. Витрина данных формирует результат выполнения подзапроса. 13. Агент Поставщика данных считывает результат выполнения подзапроса из зарезервированного топика брокера сообщений Apache Kafka. 14. Агент Поставщика подписывает результат ЭП ОВ. 15. Агент Поставщика формирует ответ и передает его в Ядро СМЭВ4. .. _query_process: .. figure:: img/query_process.png :align: center :alt: Диаграмма последовательности процесса выполнения SQL-запроса Диаграмма последовательности процесса выполнения SQL-запроса *Ядро СМЭВ4:* 16. Осуществляет проверку ЭП ОВ УВ. 17. После получения результатов по всем подзапросам Ядро СМЭВ4 формирует результат для исходного запроса. Если хотя бы по одному была получена ошибка, Ядро СМЭВ4 прекращает выполнение запроса и возвращает Агенту Потребителя соответствующую ошибку в качестве результата запроса. 18. Отправляет результат Агенту Потребителя. *В контуре Потребителя данных (УВ 3 или 4 на схемах):* 19. Агент Потребителя данных проверяет ЭП ОВ. 20. Агент Потребителя данных передает ИС с использованием JDBC-подключения или REST-интерфейса результат запроса. .. _distribution_exchange_1: Обмен с использованием Рассылок (для Компонента «Витрина данных» версии 1.x) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _distribution_interaction_description: Общее описание информационного обмена ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ СМЭВ4 и Компонент «Витрина данных» позволяют организовать процесс автоматического: - информирования Потребителя данных об изменениях на Витрине Поставщика данных посредством передачи изменений (дельт); - размещения и актуализации данных из Витрины Поставщика данных в контуре Потребителя данных посредством передачи снапшота и дельт. Такой обмен осуществляется по Подписке Потребителя данных на получение изменений данных с использованием регламентированного запроса типа «Рассылка (для Компонента «Витрина данных» версии 1.x)». [1]_ При этом обязательным условием является использование на стороне Потребителя и Поставщика версии Компонента «Витрина данных» не выше 2.0, т.к. начиная с версии 2.0 и выше в Компоненте «Витрина данных» изменилась архитектура взаимодействия с Агентом СМЭВ4 без использования Kafka. Для тех Потребителей, которые используют Компонент «Витрина данных» версии 2.х и выше и хотят применять обмен вида Рассылка, необходимо выбрать механизм регламентированного запроса типа «Рассылка (для Компонента «Витрина данных» версии 2.x)», подробнее: :numref:`distribution_exchange_2`. Подписка позволяет автоматически загружать изменения данных из Витрины Поставщика в Витрину Потребителя. Потребитель посылает запросы напрямую в свою Витрину, в результате чего сокращается продолжительность сеансов обмена. .. note:: Информационный обмен по подписке при возникновении сбоев может быть приостановлен. Приостановка обмена означает прекращение запроса новых дельт у Поставщика и отправки их Потребителю. Приём уведомлений о наличии новых дельт от Поставщика в Ядре СМЭВ4 продолжается. Приостановка и возобновление обмена осуществляется СЦ. .. [1] Регламентированный запрос типа «Рассылка (для Компонента «Витрина данных» версии 1.x)» и права доступа на него регистрируются аналогично Регламентированному SQL-запросу. :numref:`tab_subscription` и :numref:`subscription_view` показывают виды подписок. .. _tab_subscription : .. table:: Виды подписок +---+----------------+-----------------------------------------------------------------------------------------------------------------+ | | Вид | Характеристика | +===+================+=================================================================================================================+ | 1 | Простая | Подписка на один простой Регламентированный запрос типа «Рассылка (для Компонента «Витрина данных» версии 1.x)» | +---+----------------+-----------------------------------------------------------------------------------------------------------------+ | 2 | Множественная | Подписка на несколько простых Регламентированных запросов типа | | | | «Рассылка (для Компонента «Витрина данных» версии 1.x)» к таблицам одной Витрины данных | +---+----------------+-----------------------------------------------------------------------------------------------------------------+ | 3 | Распределённая | Подписка на один распределённый Регламентированный запрос типа | | | | «Рассылка (для Компонента «Витрина данных» версии 1.x)» | +---+----------------+-----------------------------------------------------------------------------------------------------------------+ .. _subscription_view: .. figure:: img/subscription_view.png :align: center :alt: Виды подписок Виды подписок .. note:: Множественная и распределённая подписки одновременно не работают на одной Витрине (Витрина 1 на :numref:`subscription_view` не может одновременно участвовать в подписках на схемах в центре и справа). Для использования Регламентированного запроса типа «Рассылка (для Компонента «Витрина данных» версии 1.x)» в подписке он должен удовлетворять следующим требованиям: 1. **Общие требования** к Регламентированного запроса типа «Рассылка (для Компонента «Витрина данных» версии 1.x)» для использования в подписке: 1.1. Недопустимо использование в SQL-запросе параметров (за исключением статического where). 1.2. Недопустимо использование в SQL-запросе set-операций (``union``, ``minus``, ``intersect`` и т.п.), оконных функций, коррелирующих подзапросов, группирующих функций, сортировок, обобщенных табличных выражений (CTE), объединений (``semi-join``). 1.3. Используемые в запросе функции должны поддерживаться Витринами Поставщиков. 2. Дополнительные требования **для нераспределённых подписок:** 2.1. Количество источников данных в SQL-запросе должно быть равно одному. 3. Дополнительные требования для **нераспределённых (множественных) подписок:** 3.1. Количество источников данных в SQL-запросе должно быть равно одному. 3.2. Во всех SQL-запросах должна быть указана одна и та же Витрина (таблицы могут быть разными). 4. Дополнительные требования **для распределённых подписок:** 4.1. Количество источников данных должно быть равно двум (обработка большего количества в СМЭВ4 не поддерживается). 4.2. Объединение данных в SQL-запросе должно осуществляться с помощью ``inner join`` (обработка ``outer join`` в СМЭВ4 не поддерживается). :numref:`distribution_subscription` содержит описание метаданных подписки. Жизненный цикл подписки состоит из следующих этапов: 1. подготовительные мероприятия для регистрации подписки в соответствии с :numref:`distribution_participants_requiremets`; 2. регистрация подписки в СМЭВ4 и Витринах Поставщиков и Потребителей в соответствии с :numref:`subscription_registration`; 3. осуществление информационного обмена по подписке в соответствии с :numref:`subscription_interaction`, включающего в себя: - уведомление о наличии дельты от Поставщика; - передачу уведомления о наличии дельты Потребителю; - запрос у Поставщика дельты по инициативе Потребителя или СМЭВ4; - передача дельты Потребителю; 4. удаление подписки в СМЭВ4 и Витринах Поставщиков в соответствии с :numref:`subscription_delete`. Информационный обмен по Рассылке сопровождается следующими **ограничениями**: 1. Подписка не обновляется. При необходимости изменений формируется новая подписка с новым идентификатором. 2. В Витрине Потребителя недопустима произвольная запись данных, кроме процесса получения новых дельт от Витрины Поставщика. 3. Механизма ограничения объема пакета отправляемых дельт не предусмотрено. .. _distribution_participants_requiremets: Требования к участникам взаимодействия ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _distribution_providers_requirements: Требования к Поставщикам данных ################################# Поставщик данных для участия в информационном обмене по Рассылке должен выполнить следующие требования. .. _tab_distribution_provider: .. table:: Требования к Поставщикам данных для использования Рассылок +----+---------------------------------------+---------------------------------------------------------+ | № | Требование | Инструкция | +====+=======================================+=========================================================+ | 1 | Зарегистрировать ИС в СМЭВ4 | Инструкция приведена в документе «Регламент | | | | Правила и процедуры работы в СМЭВ 4» | +----+---------------------------------------+---------------------------------------------------------+ | 2 | Развернуть и настроить в своем | Инструкция приведена в документе «Руководство | | | контуре Агент СМЭВ4 | администратора Агента СМЭВ4» | +----+---------------------------------------+ | | 3 | Обеспечить сетевую связанность Агента | | | | с СМЭВ4 | | +----+---------------------------------------+---------------------------------------------------------+ | 4 | Развернуть в своем контуре Компонент | Исходные коды и документация Компонента «Витрина данных»| | | «Витрина данных» версии не выше 2.0 | размещены в НФАП | +----+---------------------------------------+ | | 5 | Настроить Компонент «Витрина данных» | | | | для взаимодействия с Агентом СМЭВ4 | | +----+---------------------------------------+---------------------------------------------------------+ | 6 | Загрузить модель данных Витрины в | Инструкция приведена в документе «Инструкция по работе | | | СМЭВ4 | в ЕИП НСУД» | +----+---------------------------------------+ | | 7 | Связать Витрину данных и ИС | | +----+---------------------------------------+---------------------------------------------------------+ | 8 | Зарегистрировать Регламентированный | Через ЛК УВ, в соответствии с документом «Руководство | | | запрос типа «Рассылка (для Компонента | пользователя ЛК УВ» | | | «Витрина данных» версии 1.x)», | | | | по которому будет выполняться подписка| | | | в СМЭВ4 | | +----+---------------------------------------+ | | 9 | Добавить критерии доступа к | | | | Регламентированному запросу типа | | | | «Рассылка (для Компонента «Витрина | | | | данных» версии 1.x)» | | +----+---------------------------------------+---------------------------------------------------------+ | 10 | Согласовать право доступа Потребителя | Инструкция приведена в документе «Регламенте по | | | к Регламентированному запросу типа | подключению к СМЭВ4» | | | «Рассылка (для Компонента «Витрина | | | | данных» версии 1.x)», по которому | | | | будет выполняться Подписка | | +----+---------------------------------------+ | | 11 | Зарегистрировать Подписку в СМЭВ4 | | +----+---------------------------------------+---------------------------------------------------------+ .. _distribution_consumers_requirements: Требования к Потребителям данных ################################# Потребитель данных для участия в информационном обмене по рассылке должен выполнить следующие требования. .. _tab_distribution_consumers_requirements: .. table:: Требования к Потребителям данных для использования Рассылок +----+----------------------------------------+---------------------------------------------------------+ | № | Требование | Инструкция | +====+========================================+=========================================================+ | 1 | Зарегистрировать ИС в СМЭВ4 | Инструкция приведена в документе «Регламент | | | | Правила и процедуры работы в СМЭВ 4» | +----+----------------------------------------+---------------------------------------------------------+ | 2 | Развернуть и настроить в своем | Инструкция приведена в документе «Руководство | | | контуре Агент СМЭВ4 | администратора Агента СМЭВ4» | +----+----------------------------------------+ | | 3 | Обеспечить сетевую связанность Агента | | | | с СМЭВ4 | | +----+----------------------------------------+ | | 4 | Обеспечить свободный объем оперативной | | | | памяти на стороне Агента не менее | | | | размера передаваемых и получаемых | | | | данных | | +----+----------------------------------------+---------------------------------------------------------+ | 5 | Развернуть в своем контуре Компонент | Исходные коды и документация Компонента «Витрина данных»| | | «Витрина данных» версии не выше 2.0 | размещены в НФАП | | | для хранения данных по подписке | | +----+----------------------------------------+ | | 6 | Настроить Компонент «Витрина данных» | | | | для взаимодействия с Агентом СМЭВ4 | | +----+----------------------------------------+---------------------------------------------------------+ | 7 | Загрузить модель данных Витрины в | Инструкция приведена в документе «Инструкция по работе | | | СМЭВ4 (модель-заглушка) | в ЕИП НСУД» | +----+----------------------------------------+ | | 8 | Связать Витрину данных и ИС | | +----+----------------------------------------+---------------------------------------------------------+ | 9 | Согласовать право доступа к | Инструкция приведена в документе «Регламент | | | Регламентированному запросу типа | Правила и процедуры работы в СМЭВ 4» | | | «Рассылка (для Компонента «Витрина | | | | данных» версии 1.x)», по которому | | | | будет выполняться Подписка с | | | | Поставщиком данных | | +----+----------------------------------------+---------------------------------------------------------+ .. _distribution_participants_interaction: Взаимодействия участников обмена ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Взаимодействие Ядра СМЭВ4 с Агентами СМЭВ4 осуществляется с использованием Протокола СМЭВ4. 2. Взаимодействие Агента Поставщика данных с Витриной Поставщика данных осуществляется с использованием зарезервированных топиков брокера сообщений Apache Kafka. :numref:`provider_kafka_topics` содержит перечень топиков Apache Kafka. 3. Взаимодействие Агента Потребителя данных с Витриной Потребителя осуществляется с использованием зарезервированных топиков брокера сообщений Apache Kafka. :numref:`consumer_kafka_topics` содержит перечень топиков Apache Kafka; :numref:`distribution` иллюстрирует общую схему взаимодействия участников обмена. .. _distribution: .. figure:: img/distribution.png :align: center :alt: Информационный обмен с использованием Рассылок Информационный обмен с использованием Рассылок .. _distribution_stages_description: Описание этапов ^^^^^^^^^^^^^^^^ .. _subscription_registration: Регистрация подписки ###################### :numref:`img_subscription_registration` демонстрирует порядок регистрации подписки, соответствующее описание процесса приведено ниже. .. _img_subscription_registration: .. figure:: img/subscription_registration.png :align: center :alt: Диаграмма последовательности – Регистрация подписки Диаграмма последовательности – Регистрация подписки 1. Запрос на регистрацию подписки передаётся в СМЭВ4 в соответствии с :numref:`distribution_subscription`. *Ядро СМЭВ4:* 2. Осуществляет следующие проверки: - проверка уникальности идентификатора подписки в запросе; - в случае множественной подписки, проверка Регламентированных запросов типа «Рассылка (для Компонента «Витрина данных» версии 1.x)» на то, что они нераспределённые и источником во всех запросах является одна Витрина; - проверка Регламентированного запроса типа «Рассылка (для Компонента «Витрина данных» версии 1.x)» на его наличие в СМЭВ4; - проверка соответствия Регламентированного запроса типа «Рассылка (для Компонента «Витрина данных» версии 1.x)» требованиям для использования в подписке (приведены в :numref:`distribution_interaction_description`); - проверка соответствия Регламентированных запросов на использование допустимого для информационного обмена по подписке количества Поставщиков; - проверка наличия зарегистрированных в СМЭВ4 Витрин Поставщиков и Потребителя; - проверка наличия прав доступа ИС Потребителя к Регламентированному запросу типа «Рассылка (для Компонента «Витрина данных» версии 1.x)», указанному в регистрируемой подписке; - проверка, является ли действующей версия Регламентированного запроса типа «Рассылка (для Компонента «Витрина данных» версии 1.x)»; - в случае распределённой подписки - проверка на отсутствие значения в поле «cronExpression». 3. Отправляет ответ со статусом обработки запроса. 4. Определяет перечень подзапросов: - если подписка нераспределённая, то формируется один подзапрос на получение дельты (тип - DATA); - если подписка распределённая, формирует набор подзапросов: - подзапрос ключей Витрины Поставщика 1 (тип - KEYS); - подзапрос ключей Витрины Поставщика 2 (тип - KEYS); - подзапрос ключей Витрины Поставщика 1 с фильтрацией по ключам Витрины Поставщика 2 (тип - KEYS_FILTERED); - подзапрос ключей Витрины Поставщика 2 с фильтрацией по ключам Витрины Поставщика 1 (тип - KEYS_FILTERED); - подзапрос дельты Витрины Поставщика 1 с фильтрацией по ключам Витрины Поставщика 2 (тип - DATA_FILTERED); - подзапрос дельты Витрины Поставщика 2 с фильтрацией по ключам Витрины Поставщика 1 (тип - DATA_FILTERED); - подзапрос объединения частей дельт на Потребителе (тип - FINAL). 5. ( 12 ) отправляет запрос на регистрацию подписки всем участвующим в подписке Поставщикам в соответствующие Агенты СМЭВ4. *Агент Поставщика данных:* 6. ( 13 ) осуществляет проверку ЭП Ядра СМЭВ4; 7. ( 14 ) передает запрос на регистрацию подписки Витрине в топик ``<префикс>.replication.rq``. *Витрина Поставщика данных:* 8. ( 15 ) осуществляет проверку запроса на регистрацию подписки: - проверка уникальности идентификатора подписки; - проверка наличия витрины, указанной в подписке; - проверка наличия таблицы, указанной в подписке; - проверка корректности sql-запроса; - проверка соответствия полей sql-запроса таблице Витрины Поставщика; - проверка наличия атрибутов «primaryKey» и «shardingKey» в структуре итоговой таблицы. 9. ( 16 ) регистрирует подписку (устанавливает статус подписки – активная (OPENED)) 10. ( 17 ) отправляет ответ в Агент Поставщика данных: - в случае успешной обработки запроса – структуру таблиц в топик ``<префикс>.replication.rs``. - в случае неуспешной обработки запроса – уведомление об ошибке в топик ``<префикс>.replication.err``. *Агент Поставщика данных:* 11 ( 18 ). Пересылает структуру таблиц в Ядро СМЭВ4. *Ядро СМЭВ4:* 19. Пересылает структуру таблиц Агенту Потребителя данных. *Агент Потребителя данных:* 20. Осуществляет проверку ЭП Ядра СМЭВ4; 21. Передает в Витрину данных структуру таблиц с использованием топика ``<префикс>.replication.in.rq``. *Витрина Потребителя данных:* 22. Осуществляет проверку запроса на регистрацию подписки: - проверка уникальности идентификатора подписки; - проверка уникальности целевой таблицы подписки; - проверка корректности sql-запроса на объединение данных. 23. Регистрирует подписку (устанавливает статус подписки – активная (OPENED)) 24. Отправляет ответ в Агент Потребителя данных: - в случае успешной обработки - уведомление об успешном создании структуры данных в топик ``<префикс>.replication.in.rs``. - в случае неуспешной обработки - уведомление об ошибке в топик ``<префикс>.replication.in.err``. *Агент Потребителя данных:* 25. Отправляет в Ядро СМЭВ4 статус обработки структуры таблиц Витриной данных. *Ядро СМЭВ4:* 26. Регистрирует подписку. .. _subscription_interaction: Информационный обмен #################################### :numref:`img_distribution_interaction` иллюстрирует порядок информационного обмена, соответствующее описание процесса приведено ниже. Загрузка снапшота осуществляется аналогично последующей загрузке дельт. *Витрина Поставщика данных:* 1. Передаёт в Агент Поставщика уведомление о наличии дельты в топик ``<префикс>.delta.notification``. *Агент Поставщика данных:* 2. Передаёт уведомление в Ядро СМЭВ4. .. _img_distribution_interaction: .. figure:: img/distribution_interaction.png :align: center :alt: Диаграмма последовательности – Информационный обмен Диаграмма последовательности – Информационный обмен *Ядро СМЭВ4:* 1. по наличию расписания (cronExpression) определяет, кто является инициатором запроса дельты – Ядро СМЭВ4 или Потребитель [2]_. В случае распределённых подписок расписание не задаётся, инициатором запроса дельты всегда является Потребитель. - если расписание задано, осуществляет запрос дельты самостоятельно (переход к шагу 11). При этом если Потребитель еще не прислал ответ о результате применения предыдущего пакета дельт, новый не запрашивается; - если расписание не задано, осуществляет отправка уведомления Потребителю (переход к шагу 4); 2. отправляет уведомление о наличии дельты в Агент Потребителя и не запрашивает дельту пока не придёт команда от Потребителя. *Агент Потребителя данных:* 5. передаёт уведомление о наличии дельты Витрине Потребителя в топик ``<префикс>.delta.notification.in``. *Витрина Потребителя данных:* 6. обрабатывает уведомление о наличии новой дельты; 7. в случае распределённой подписки определяет порядок обращения к Поставщикам; 8. посылает запрос на получение дельты в командный топик ``<префикс>.command.podd``. *Агент Потребителя данных:* 9. передаёт запрос в Ядро СМЭВ4. *Ядро СМЭВ4:* 10. обрабатывает запрос на получение дельты; 11. проверяет права доступа Потребителя данных. **Если подписка нераспределённая:** *Ядро СМЭВ4:* 12. передаёт запрос дельты на Агент Поставщика. *Агент Поставщика данных:* 13. передаёт запрос дельты Витрине Поставщика в топик ``<префикс>.delta.rq``. *Витрина данных Поставщика:* 14. обрабатывает запрос дельты; 15. передаёт дельту в Агент Поставщика: - в случае успешной обработки запроса результат в топик ``<префикс>.delta.rs``. - в случае неуспешной обработки запроса - уведомление об ошибке в топик ``<префикс>.delta.err``. *Агент Поставщика данных:* 16. передаёт дельту в Ядро СМЭВ4. **Если подписка распределённая:** *Ядро СМЭВ4:* 17. передаёт запрос ключей (без фильтрации) в Агент Поставщика 1 *Агент Поставщика данных 1:* 18. передаёт запрос ключей (без фильтрации) Витрине Поставщика в топик ``<префикс>.delta.rq``. *Витрина Поставщика данных 1:* 19. обрабатывает запрос; 20. передаёт дельту в Агент Поставщика 1: - в случае успешной обработки запроса результат в топик ``<префикс>.delta.rs``. - в случае неуспешной обработки запроса - уведомление об ошибке в топик ``<префикс>.delta.err``. *Агент Поставщика данных 1:* 21. передаёт ключи в Ядро СМЭВ4. *Ядро СМЭВ4:* 22. передаёт запрос ключей (с фильтрацией по ключам Витрины 1) в Агент Поставщика 2. *Агент Поставщика данных 2:* 23. передаёт запрос ключей (с фильтрацией по ключам Витрины 1) Витрине Поставщика 2 в топик ``<префикс>.delta.tp``. *Витрина Поставщика данных 2:* 24. обрабатывает запрос; 25. передаёт пересечение ключей в Агент Поставщика 2: - в случае успешной обработки запроса результат в топик ``<префикс>.delta.rs``. - в случае неуспешной обработки запроса - уведомление об ошибке в топик ``<префикс>.delta.err``. *Агент Поставщика данных 2:* 26. передаёт пересечение ключей в Ядро СМЭВ4. *Ядро СМЭВ4:* 27. ( 33 ) передаёт запрос дельты (с фильтрацией по ключам) в Агент Поставщика 1 (2). *Агент Поставщика данных 1 (2):* 28. ( 34 ) передаёт запрос дельты (с фильтрацией по ключам) в Витрине Поставщика 1 (2). *Витрина Поставщика данных 1 (2):* 29. ( 35 ) обрабатывает запрос; 30. ( 36 ) передаёт дельту в Агент Поставщика 1 (2). *Агент Поставщика данных 1 (2):* 31. ( 37 ) осуществляет простановку ЭП Поставщика 1 (2) 32. ( 38 ) передаёт пересечение ключей в Ядро СМЭВ4. *Ядро СМЭВ4:* 39. передаёт дельту в Агент Потребителя *Агент Потребителя данных* 40. ( 44 ) проверяет ЭП Поставщика; 41. ( 45 ) передаёт дельту в Витрину Потребителя. *Витрина данных Потребителя:* 42. ( 46 ) обрабатывает полученную дельту; 43 ( 47 ). применяет дельту; 48. ( 50 ) передаёт статус применения дельты. *Агент Потребителя данных* 49. ( 51 ) передаёт статус применения дельты в Ядро СМЭВ4. .. [2] компонент «Витрина данных» поддерживает самостоятельный запрос дельты только для распределённых подписок. .. _subscription_delete: Удаление подписки ################### :numref:`img_subscription_delete` иллюстрирует порядок отмены подписки, соответствующее описание процесса приведено ниже. .. _img_subscription_delete: .. figure:: img/subscription_delete.png :align: center :alt: Диаграмма последовательности – Удаление подписки Диаграмма последовательности – Удаление подписки 1. Запрос на удаление подписки передаётся в СМЭВ4 в соответствии c :numref:`distribution_subscription`. *Ядро СМЭВ4:* 2. осуществляет проверку запроса на отмену подписки на наличие в СМЭВ4 подписки с указанным идентификатором; 3. отправляет ответ со статусом обработки запроса; 4. ( 11 ) отправляет запрос на отмену подписки всем участвующим в подписке Поставщикам в соответствующие Агенты. *Агент Поставщика данных:* 5. ( 12 ) осуществляет проверку ЭП Ядра СМЭВ4; 6. ( 13 ) отправляет запрос Витрине Поставщика в топик ``<префикс>.replication.cancel.rq``. *Витрина Поставщика данных:* 7. ( 14 ) осуществляет проверку запроса на отмену подписки; 8. ( 15 ) отменяет подписку (устанавливает статус подписки – отменённая (CANCELED)); 9. ( 16 ) отправляет ответ в Агент Поставщика данных в топик ``<префикс>.replication.cancel.rs``. *Агент Поставщика данных:* 10. ( 17 ) отправляет в Ядро СМЭВ4 статус обработки запроса на отмену подписки. *Ядро СМЭВ4:* 18. удаляет подписку после получения ответа от всех Поставщиков вне зависимости от статуса этих ответов (успех/ошибка). При этом статус Поставщика временно (до удаления) в случае успеха меняется на CANCELLED, а в случае ошибки – ERROR. .. _distribution_exchange_2: Обмен с использованием Рассылок (для Компонента «Витрина данных» версии 2.x) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _distribution_interaction_2_description: Общее описание информационного обмена ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ СМЭВ4 и Компонент «Витрина данных» позволяют организовать процесс автоматического: - Запуска выполнения Регламентированных SQL-запросов с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)» по расписанию; - Размещения и актуализация данных из Витрины Поставщика данных в контуре Потребителя данных посредством передачи снапшота и версий данных за указанный диапазон номеров операций (CN). Потребитель данных на своей стороне обеспечивает механизм периодического запуска выполнения Регламентированных SQL-запросов с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)» одним из следующих способов: - **Способ 1: Подключение собственного сервиса к Агенту СМЭВ4** – при таком способе вся логика по периодическому вызову SQL-запросов реализуется на стороне внешнего приложения. Такой способ применяется в случае, если Потребитель не использует у себя Компонент «Витрина данных». Данные, полученные по результатам выполнения SQL-запроса сохраняются средствами внешнего приложения Потребителя. - **Способ 2: Использование стандартного механизма материализованных представлений в Компонента «Витрина данных» версии не ниже 2.x** – при таком способе вся логика по вызову SQL-запросов реализуется на стороне Prostore. Такой способ применяется в случае, если Потребитель использует у себя Компонент «Витрина данных» [3]_. Данные, полученные по результатам выполнения SQL-запроса сохраняются в созданных материализованных представлениях. Подробное описание процесса синхронизации данных через механизм материализованных представлений приведено в `документации на ПО Prostore `_. Под «логикой вызова SQL-запроса» понимается: - Определение вызываемого SQL-РЗ; - Определение расписания вызова SQL-РЗ; - Динамическое определение нужной версии (диапазона) данных при вызове; - Передача запроса в Агента СМЭВ4. Выполнение Регламентированного SQL-запроса с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)» происходит в два этапа: - На первом этапе запрашивается текущий (последний актуальный) номер CN, для каждой таблицы, заданной в SQL-выражении. Этот номер операции CN передаётся Потребителю для возможности определения им нужной версии данных. Потребитель на своей стороне должен сохранять номера последних применённых CN (в случае с использованием на стороне Потребителя Компонент «Витрина данных» версии не ниже 2.0 эта функция выполняется автоматически). - На втором этапе выполняется SELECT-запрос данных определенной версии (с заданным диапазоном CN). Выполнение запроса происходит циклически с последовательным увеличением диапазона CN, что обеспечивает полное и корректное получение всех версий данных из Витрины Поставщика. .. [3] Должен использоваться Компонент «Витрина данных» версии 2.х и выше SQL-выражение, задаваемое для SQL-запросов с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)» может быть таким, которое удовлетворяет требованиям, указанным в :numref:`sql_request_definition`. Однако рекомендуется при составлении SQL-выражения придерживаться следующих правил: 1. Определить какие изменения в данных требуется получать. Например, только добавленные записи или только удалённые записи и т.д. Для этого удобно использовать выражения вида ``FOR SYSTEM_TIME``. 2. Задать диапазоны для извлечения версии данных. В качестве диапазона извлечения версии данных можно применять номера операций CN. Т.к. диапазон номеров CN является переменной величиной, то лучше их задавать в качестве именованных параметров. При этом название именованного параметра удобно задавать по следующей маске: <мнемоника датамарта>_<наименование таблицы>_<граница диапазона cn>. Пример SQL-выражения для SQL-запросов с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)»: .. code-block:: sql SELECT id, col1, col2, 0 as sys_op FROM fias.addr_obj FOR SYSTEM_TIME STARTED CN (:fias_addr_obj_cn1, :fias_addr_obj_cn2) as obj_add_alias UNION ALL SELECT id, null, null, 1 as sys_op FROM fias.addr_obj FOR SYSTEM_TIME FINISHED CN (:fias_addr_obj_cn1, :fias_addr_obj_cn2) as obj_del_alias Этот SQL-запрос объединяет данные о изменениях в таблице ``fias.addr_obj`` за определённый диапазон номеров изменений CN. Запрос состоит из двух частей, объединённых через UNION ALL: - первая часть выбирает записи, которые были добавлены или изменены в указанном диапазоне (``FOR SYSTEM_TIME STARTED``), возвращая их ``id``, ``col1``, ``col2`` и помечая их как операции добавления (``0 as sys_op``). - вторая часть выбирает записи, которые были удалены в указанном диапазоне (``FOR SYSTEM_TIME FINISHED``), возвращая только их ``id`` и помечая как операции удаления (``1 as sys_op``), с null-значениями для остальных полей. Итоговый результат показывает все изменения (добавления/изменения и удаления), произошедшие с таблицей ``addr_obj`` между номерами изменений ``:fias_addr_obj_cn1`` и ``:fias_addr_obj_cn2``. Для работы SQL-РЗ категории «Рассылка (для Компонента «Витрина данных» версии 2.x)» не требуется создание подписки. .. _distribution_2_participants_requiremets: Требования к участникам взаимодействия ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _distribution_2_providers_requirements: Требования к Поставщикам данных ################################# Поставщик данных для участия в информационном обмене типа Регламентированный SQL-запрос с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)» должен выполнить следующие требования. .. _tab_distribution_2_consumers_requirements: .. table:: Требования к Поставщикам данных +----+---------------------------------------+---------------------------------------------------------+ | № | Требование | Инструкция | +====+=======================================+=========================================================+ | 1 | Зарегистрировать ИС в СМЭВ4 | Инструкция приведена в документе «Регламент | | | | Правила и процедуры работы в СМЭВ 4» | +----+---------------------------------------+---------------------------------------------------------+ | 2 | Развернуть и настроить в своем | Инструкция приведена в документе «Руководство | | | контуре Агент СМЭВ4 | администратора Агента СМЭВ4» | +----+---------------------------------------+ | | 3 | Обеспечить сетевую связанность Агента | | | | с СМЭВ4 | | +----+---------------------------------------+---------------------------------------------------------+ | 4 | Развернуть в своем контуре Компонент | Исходные коды и документация Компонента «Витрина данных»| | | «Витрина данных» версии 2.0 и выше | размещены в НФАП | +----+---------------------------------------+ | | 5 | Настроить Компонент «Витрина данных» | | | | для взаимодействия с Агентом СМЭВ4 | | +----+---------------------------------------+---------------------------------------------------------+ | 6 | Загрузить модель данных Витрины в | Инструкция приведена в документе «Инструкция по работе | | | СМЭВ4 | в ЕИП НСУД» | +----+---------------------------------------+ | | 7 | Связать Витрину данных и ИС | | +----+---------------------------------------+ | | 8 | Зарегистрировать Регламентированные | | | | SQL-запросы с категорией «Рассылка | | | | (для Компонента «Витрина данных» | | | | версии 2.x)» в СМЭВ4 | | +----+---------------------------------------+---------------------------------------------------------+ | 9 | Добавить критерии доступа к | Инструкция приведена в документе «Руководство | | | Регламентированному SQL-запросу | пользователя ЛК УВ» | | | (Согласовать право доступа) | | +----+---------------------------------------+---------------------------------------------------------+ .. _distribution_2_consumers_requirements: Требования к Потребителям данных ################################# Потребитель данных для участия в информационном обмене по типа Регламентированный SQL-запрос с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)» должен выполнить следующие требования. .. _tab_distribution_consumers_requirements: .. table:: Требования к Потребителям данных +----+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | № | Требование | Инструкция | +====+=======================================+=========================================================================================================================================+ | 1 | Зарегистрировать ИС в СМЭВ4 | Инструкция приведена в документе «Регламент Правила и процедуры работы в СМЭВ 4» | | | | | +----+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 2 | Развернуть и настроить в своем | Инструкция приведена в документе «Руководство администратора Агента СМЭВ4» | | | контуре Агент СМЭВ4 | | +----+---------------------------------------+ | | 3 | Обеспечить сетевую связанность Агента | | | | с СМЭВ4 | | +----+---------------------------------------+ | | 4 | Обеспечить свободный объем | | | | оперативной памяти на стороне Агента | | | | не менее размера передаваемых и | | | | получаемых данных | | +----+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | Пункты 5-8 опциональны и применяются только для тех Потребителей, которые используют Компонент «Витрина данных» версии 2.0 и выше | +----+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 5 | Развернуть в своем контуре Компонент | Исходные коды и документация Компонента «Витрина данных» размещены в НФАП. | | | «Витрина данных» версии 2.0.0 или | | | | выше для хранения данных | Создание материализованного представление описано в документации Prostore | +----+---------------------------------------+ https://prostore.datamart.ru/docs_prostore/working_with_schema/managing_entities/create_materialized_view/create_materialized_view.html | | 6 | Настроить Компонент «Витрина данных» | | | | для взаимодействия с Агентом СМЭВ4 | Инструкция приведена в документе «Руководство по установке Компонента «Витрина данных». | +----+---------------------------------------+ | | 7 | Создать материализованные | | | | представления для запуска SQL-РЗ и | | | | хранения результатов исполнения | | +----+---------------------------------------+ | | 8 | Связать Витрину данных и ИС | | +----+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | Пункт 9 опционален и применяются только для тех Потребителей, которые не используют Компонент «Витрина данных» | +----+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 9 | Настроить ИС для выполнения запросов | :numref:`consumer_protocol` | | | и обработки данных, получаемых от | | | | СМЭВ4 для взаимодействия с Агентом | | | | СМЭВ4 | | +----+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 10 | Согласовать право доступа к | Инструкция приведена в «Регламент Правила и процедуры работы в СМЭВ4» | | | Регламентированному запросу типа | | | | «Рассылка (для Компонента «Витрина | | | | данных» версии 2.x)» | | +----+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ .. _participants_2_interaction: Взаимодействие участников обмена ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Взаимодействие Ядра СМЭВ4 с Агентами СМЭВ4 осуществляется с использованием Протокола СМЭВ4. 2. Взаимодействие Агента Поставщика данных с Витриной Поставщика данных осуществляется с использованием Протокола HTTP. 3. Взаимодействие Агента Потребителя данных с Витриной Потребителя данных осуществляется с использованием Протокола HTTP. 4. Взаимодействие ИС Потребителя с Агентом Потребителя осуществляется через REST или JDBC-интерфейс в соответствии со спецификацией :numref:`consumer_protocol`. :numref:`img_2_distribution_interaction` иллюстрирует общую схему взаимодействия участников обмена. .. _img_2_distribution_interaction: .. figure:: img/img_2_distribution_interaction.png :align: center :alt: Информационный обмен типа Регламентированный SQL-запрос с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)» Информационный обмен типа Регламентированный SQL-запрос с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)» .. _distribution_2_stages_description: Описание этапов ^^^^^^^^^^^^^^^^ .. _subscription_2_registration: Регистрация в СМЭВ4 SQL-РЗ ################################ Подготовка УВ к использованию информационного обмена типа Регламентированный SQL-запрос с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)» описана в :numref:`distribution_2_participants_requiremets`. При регистрации SQL-РЗ необходимо указать категорию «Рассылка (для Компонента «Витрина данных» версии 2.x)». .. _matview_create: Создание материализованного представления ################################ В случае если Потребитель данных использует ПО “Витрина данных”, то ему необходимо создать материализованное представление для запуска SQL-РЗ с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)». Описание правил создания материализованного представления представлено в `документации Prostore `_. .. _subscription_2_interaction: Информационный обмен #################################### :numref:`img_2_distribution_interaction_diagram` иллюстрирует общую схему взаимодействия участников обмена. .. _img_2_distribution_interaction_diagram: .. figure:: img/img_2_distribution_interaction_diagram.png :align: center :alt: Диаграмма прохождения запроса типа Регламентированный SQL-запрос с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)» Диаграмма прохождения запроса типа Регламентированный SQL-запрос с категорией «Рассылка (для Компонента «Витрина данных» версии 2.x)» *В контуре Потребителя данных:* 1. ИС или ПО «Витрина данных» Потребителя данных передаёт SQL-запрос Агенту СМЭВ4 на получение номеров CN. Запрос передаётся с системным параметром ``settings_get_cn``, где в качестве значения для него указывается временная метка. Передача запроса может осуществляться с использованием: - JDBC-подключения; - REST-интерфейса. Настройки подключения выполняются в рамках настройки ИС для взаимодействия с Агентом СМЭВ4 согласно «Руководству администратора Агента СМЭВ4». :numref:`consumer_protocol` содержит Спецификацию взаимодействия. 2. Агент Потребителя данных проверяет наличие включенного режима блокировки на отправку запросов (:numref:`blocking`). Дальнейшие шаги выполняются в случае отсутствия блокировки. 3. Агент Потребителя подписывает запрос ЭП ОВ. 4. Агент Потребителя передает полученный запрос в Ядро СМЭВ4. *Ядро СМЭВ4 (после получения запроса от Агента Потребителя данных):* 5. Выполняет проверку ЭП ОВ, которой подписан запрос, проверку запроса на корректность и наличие у Потребителя доступа на выполнение запросов к данным. Если хотя бы одна из проверок возвращает отрицательный результат, то прекращает выполнение запроса и возвращает Агенту Потребителя соответствующую ошибку в качестве результата запроса. 6. Проверяет категорию запроса: - если, категория SQL-РЗ не равна «Рассылка (для Компонента «Витрина данных» версии 2.x)», то процесс завершается с ошибкой: «Нельзя выполнять запрос получения номера операции записи CN для категории регламентированного запроса, отличной от get_cn». - если, категория SQL-РЗ равна «Рассылка (для Компонента «Витрина данных» версии 2.x)», то формирует подзапросы на получение номеров CN по следующей логике: - извлекает по полученной мнемонике SQL-РЗ мнемонику датамарта и наименование таблицы (для каждой таблицы из sql-выражения); - формирует для каждой таблицы подзапрос вида GET_CN (``:tablename``, ``:tx``), где в качестве параметров подставляет наименование таблицы (в формате <мнемоника датамарта>.<наименование таблицы>) и таймстемп из исходного запроса (временная метка, заданная в системном параметре ``settings_get_cn``). 7. Выполняет проверку соответствия ограничениям, заданным в Ядре СМЭВ4: - на интенсивность запросов от ИС Потребителя данных за интервал времени; - на общий объем данных в запросе и подзапросах за интервал времени. В случае превышения установленных ограничений Ядро СМЭВ4 прекращает выполнение запроса или подзапроса и возвращает Агенту Потребителя сообщение о включении режима блокировки. Агент Потребителя при получении такого сообщения активирует режим блокировки и отвечает ошибкой на запросы от Потребителя к заблокированному ресурсу. 8. Передаёт каждый подзапрос вида GET_CN (``:tablename``, ``:tx``) в соответствующий Агент Поставщика. *В контуре Поставщика данных:* 9. Агент Поставщика данных получает запрос и проверяет ЭП ОВ, которой подписан запрос. Дополнительно для простых исходных запросов Потребителя данных в рамках получения подзапроса от Ядра СМЭВ4 в Агент Поставщика передается исходный запрос с ЭП ОВ и сертификатом Потребителя данных, отправившего исходный запрос. *Если на стороне Агента Поставщика данных развернут и включен Сервис проверки полномочий:* 10. Сервис проверки полномочий выполняет проверку подтверждения доступа на выполнение Регламентированного SQL-запроса (включая подзапрос вида GET_CN (``:tablename``, ``:tx``) для Потребителя данных, отправившего запрос. Если для запроса не подтвержден доступ, то Агент Поставщика прекращает выполнение запроса и возвращает Агенту Потребителя соответствующую ошибку в качестве результата запроса. При подтвержденном доступе выполнение запроса продолжается. 11. Агент Поставщика данных передаёт подзапрос вида GET_CN (``:tablename``, ``:tx``) по REST в Компоненте «Витрина данных». 12. Витрина данных формирует результат выполнения подзапроса вида GET_CN (``:tablename``, ``:tx``) путём обращения к БД. 13. Агент Поставщика данных получает по REST результат выполнения подзапроса. 14. Агент Поставщика подписывает результат ЭП ОВ. 15. Агент Поставщика формирует ответ c и передает его в Ядро СМЭВ4. *Ядро СМЭВ4:* 16. Осуществляет проверку ЭП ОВ УВ. 17. После получения результатов по всем подзапросам вида GET_CN (``:tablename``, ``:tx``) Ядро СМЭВ4 формирует результат для исходного запроса (агрегированный ответ). Если хотя бы по одному была получена ошибка, Ядро СМЭВ4 прекращает выполнение запроса и возвращает Агенту Потребителя соответствующую ошибку в качестве результата запроса. 18. Отправляет результат Агенту Потребителя. *В контуре Потребителя данных:* 19. Агент Потребителя данных проверяет ЭП ОВ. 20. Агент Потребителя данных передает ИС или в Компонент «Витрина данных» с использованием JDBC-подключения или REST-интерфейса результат запроса получения номеров CN. 21. ИС или Компонент «Витрина данных», используя полученные номера CN формирует запрос на получение версии данных за указанный диапазон. Значения диапазона задаются в виде соответствующих именованных параметров, пример SQL-выражения: .. code-block:: SELECT id, col1, col2, 0 as sys_op FROM fias.addr_obj FOR SYSTEM_TIME STARTED CN (:fias_addr_obj_cn1, :fias_addr_obj_cn2) as obj_add_alias UNION ALL SELECT id, null, null, 1 as sys_op FROM fias.addr_obj FOR SYSTEM_TIME FINISHED CN (:fias_addr_obj_cn1, :fias_addr_obj_cn2) as obj_del_alias 22. ИС или Компонент «Витрина данных» Потребителя данных передаёт SQL-запрос Агенту СМЭВ4 на получение данных за указанный диапазон CN. Передача запроса может осуществляться с использованием: - JDBC-подключения; - REST-интерфейса. Настройки подключения выполняются в рамках настройки ИС для взаимодействия с Агентом СМЭВ4 согласно «Руководству администратора Агента СМЭВ4». :numref:`consumer_protocol` содержит Спецификацию взаимодействия. 23. Агент Потребителя данных проверяет наличие включенного режима блокировки на отправку запросов (:numref:`blocking`). Дальнейшие шаги выполняются в случае отсутствия блокировки. 24. Агент Потребителя подписывает запрос ЭП ОВ. 25. Агент Потребителя передает полученный запрос в Ядро СМЭВ4. *Ядро СМЭВ4 (после получения запроса от Агента Потребителя данных):* 26. Выполняет проверку ЭП ОВ, которой подписан запрос, проверку запроса на корректность и наличие у Потребителя доступа на выполнение запросов к данным. Если хотя бы одна из проверок возвращает отрицательный результат, то прекращает выполнение запроса и возвращает Агенту Потребителя соответствующую ошибку в качестве результата запроса. 27. Выполняет преобразование полученной мнемоники Регламентированного SQL-запроса в SQL-выражение в соответствии с загруженным определением и формирует один или несколько запросов в адрес Витрин Поставщиков данных (далее – подзапросы). 28. Выполняет проверку соответствия ограничениям, заданным в Ядре СМЭВ4: - на интенсивность запросов от ИС Потребителя данных за интервал времени; - на общий объем данных в запросе и подзапросах за интервал времени. В случае превышения установленных ограничений Ядро СМЭВ4 прекращает выполнение запроса или подзапроса и возвращает Агенту Потребителя сообщение о включении режима блокировки. Агент Потребителя при получении такого сообщения активирует режим блокировки и отвечает ошибкой на запросы от Потребителя к заблокированному ресурсу. 29. Передаёт каждый подзапрос в соответствующий Агент Поставщика. *В контуре Поставщика данных (УВ 1 и 2 на схемах):* 30. Агент Поставщика данных получает запрос и проверяет ЭП ОВ, которой подписан запрос. Дополнительно для простых исходных запросов Потребителя данных в рамках получения подзапроса от Ядра СМЭВ4 в Агент Поставщика передается исходный запрос с ЭП ОВ и сертификатом Потребителя данных, отправившего исходный запрос. *Если на стороне Агента Поставщика данных развернут и включен Сервис проверки полномочий:* 31. Сервис проверки полномочий выполняет проверку подтверждения доступа на выполнение Регламентированного SQL-запроса для Потребителя данных, отправившего запрос. Если для запроса не подтвержден доступ, то Агент Поставщика прекращает выполнение запроса и возвращает Агенту Потребителя соответствующую ошибку в качестве результата запроса. При подтвержденном доступе выполнение запроса продолжается. 32. Агент Поставщика данных передаёт подзапрос по REST в Компонент «Витрина данных». 33. Витрина данных формирует результат выполнения подзапроса путём обращения к БД. 34. Агент Поставщика данных получает по REST результат выполнения подзапроса. 35. Агент Поставщика подписывает результат ЭП ОВ. 36. Агент Поставщика формирует ответ c и передает его в Ядро СМЭВ4. *Ядро СМЭВ4:* 37. Осуществляет проверку ЭП ОВ УВ. 38. После получения результатов по всем подзапросам Ядро СМЭВ4 формирует результат для исходного запроса. Если хотя бы по одному была получена ошибка, Ядро СМЭВ4 прекращает выполнение запроса и возвращает Агенту Потребителя соответствующую ошибку в качестве результата запроса. 39. Отправляет результат c данными за указанный диапазон CN Агенту Потребителя. *В контуре Потребителя данных:* 40. Агент Потребителя данных проверяет ЭП ОВ. 41. Агент Потребителя данных передает ИС или в ПО «Витрина данных» с использованием JDBC-подключения или REST-интерфейса результат запроса получения данных за диапазон CN. *Если на стороне Потребителя развернут Компонент «Витрина данных» и применялся механизм запуска SQL-РЗ через материализованное представление* 42. Компонент «Витрина данных» сохраняет полученные данные в таблице материализованного представления. .. _rest_exchange: Обмен с использованием запросов к REST-сервису ИС Ответчика ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _rest_exchange_description: Общее описание информационного обмена ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Обмен с использованием запросов к REST-сервису ИС Ответчика предназначен для сквозного («прозрачного») доступа ИС Инициаторов к REST-сервисам ИС Ответчиков. СМЭВ4 используется в качестве канала передачи данных. Также данный механизм обеспечивает: 1. регистрацию REST-сервисов ИС Ответчиков, описываемых спецификацией OpenAPI, в СМЭВ4 через ЛК УВ; 2. разграничение доступа Инициаторов к REST-сервисам ИС Ответчиков путём использования принципа выдачи/изъятия прав на взаимодействие ИС Потребителя с REST-сервисом ИС Ответчика через ЛК УВ; 3. форматно-логический контроль запросов ИС Инициаторов и ответов ИС Ответчиков на соответствие спецификации OpenAPI зарегистрированного в СМЭВ4 REST-сервиса; 4. (опционально) возможность передачи мнемоники Инициатора в REST-сервисы ИС Ответчиков, при использовании заголовка X-PODD-CLIENT-SYSTEM-MNEMONIC; 5. (опционально) лимитирование запросов к REST-сервисам ИС Ответчика; 6. (опционально) сохранение данных запросов и ответов, переданных в процессе информационного обмена; 7. (опционально) юридическую значимость обмена. .. _rest_participants_description: Требования к участникам взаимодействия ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _respondent_requirements: Требования к Ответчикам ########################## Ответчик для участия в информационном обмене с использованием запросов к REST-сервису ИС Ответчика должен выполнить следующие требования. .. _tab_respondent_requirements: .. table:: Требования к Ответчикам +----+------------------------------------------+---------------------------------------------------------+ | № | Требование | Инструкция | +====+==========================================+=========================================================+ | 1 | Зарегистрировать ИС в СМЭВ4 | Инструкция приведена в документе «Регламент | | | | Правила и процедуры работы в СМЭВ 4» | +----+------------------------------------------+---------------------------------------------------------+ | 2 | Развернуть и настроить в своем контуре | Инструкция приведена в документе «Руководство | | | Агент СМЭВ4 | администратора Агента СМЭВ4» | +----+------------------------------------------+ | | 3 | Обеспечить сетевую связанность Агента | | | | с СМЭВ4 | | +----+------------------------------------------+---------------------------------------------------------+ | 4 | Развернуть в своем контуре REST-сервис | - | | | ИС Ответчика | | +----+------------------------------------------+---------------------------------------------------------+ | 5 | Настроить REST-сервис ИС Ответчика, | В соответствии с :numref:`respondent_protocol` | | | который обрабатывает получаемые от | | | | СМЭВ4 запросы, для взаимодействия | | | | с Агентом СМЭВ4 | | +----+------------------------------------------+---------------------------------------------------------+ | 6 | Зарегистрировать REST-сервис ИС | Инструкция приведена в документе «Руководство | | | Ответчика (Регламентированный запрос | пользователя ЛК УВ» | | | типа «REST-сервис») в СМЭВ4 | | +----+------------------------------------------+ | | 7 | Добавить критерии доступа для запросов | | | | к развернутому REST-сервису | | +----+------------------------------------------+---------------------------------------------------------+ .. _initiators_requirements: Требования к Инициаторам запросов ################################## Инициатор для участия в информационном обмене с использованием запросов к REST-сервису ИС Ответчика должен выполнить следующие требования. .. _tab_initiators_requirements: .. table:: Требования к Инициаторам запросов +----+--------------------------------------------+---------------------------------------------------------+ | № | Требование | Инструкция | +====+============================================+=========================================================+ | 1 | Зарегистрировать ИС в СМЭВ4 | Инструкция приведена в документе «Регламент | | | | Правила и процедуры работы в СМЭВ 4» | +----+--------------------------------------------+---------------------------------------------------------+ | 2 | Развернуть и настроить в своем контуре | Инструкция приведена в документе «Руководство | | | Агент СМЭВ4 | администратора Агента СМЭВ4» | +----+--------------------------------------------+ | | 3 | Обеспечить сетевую связанность Агента | | | | с СМЭВ4 | | +----+--------------------------------------------+---------------------------------------------------------+ | 4 | Настроить ИС, которая выполняет запросы | В соответствии с :numref:`respondent_protocol` | | | и осуществляет обработку данных, | | | | получаемых от СМЭВ4, для | | | | взаимодействия с Агентом СМЭВ4 | | +----+--------------------------------------------+---------------------------------------------------------+ | 5 | Получить право доступа на выполнение | Инструкция приведена в документе «Руководство | | | запросов к REST-сервису Ответчика | пользователя ЛК УВ» | | | (Регламентированному запросу типа | | | | «REST-сервис») | | +----+--------------------------------------------+---------------------------------------------------------+ .. _rest_participants_interaction: Взаимодействие участников обмена ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Механизм обмена с использованием запросов к REST-сервису ИС Ответчика реализован в виде комплекса взаимодействующих программных средств и артефактов, приведенных на :numref:`img_rest_participants_interaction`. 1. Взаимодействие Ядра СМЭВ4 с Агентами СМЭВ4 осуществляется по Протоколу СМЭВ4. 2. Взаимодействие Агента Инициатора с ИС Инициатора осуществляется с использованием REST-интерфейса в соответствии с :numref:`consumer_tp_request`. 3. Взаимодействие Агента Ответчика с ИС Ответчика осуществляется в соответствии со спецификацией OpenAPI, загруженной в СМЭВ4 (:numref:`respondent_protocol`). .. _img_rest_participants_interaction: .. figure:: img/rest_participants_interaction.png :align: center :alt: Информационный обмен с использованием запросов к REST-сервису ИС Ответчика через СМЭВ4 Информационный обмен с использованием запросов к REST-сервису ИС Ответчика через СМЭВ4 .. _rest_stages_description: Описание этапов ^^^^^^^^^^^^^^^^^ .. _rest_respondent_registration: Регистрация в СМЭВ4 REST-сервиса ИС Ответчика ##################################################### Подготовка УВ к использованию механизма запросов к REST-сервисам ИС Ответчика описана в :numref:`rest_participants_description` настоящего документа. .. note:: основные положения по подготовке спецификаций OpenAPI для использования в СМЭВ4 приведены в :numref:`respondent_rest_services` настоящего документа. .. _seq_rest_rq_request: Информационный обмен с использованием REST-РЗ ################################################# *Взаимодействие ИС Инициатора и ИС Ответчика при выполнении запроса к REST-сервису ИС Ответчика* (:numref:`img_seq_rest_rq_request`): *Агент Инициатора:* 1. Получает запрос к REST-сервису ИС Ответчика. 2. Проверяет наличие активной блокировки на отправку запросов. 3. В случае отсутствия блокировки делит запрос на чанк метаданных и чанки тела запроса. 4. Подписывает чанк метаданных ЭП Инициатора. 5. Передает чанк метаданных в Ядро СМЭВ4. *Ядро СМЭВ4:* 6. Осуществляет проверку ЭП Инициатора для чанка метаданных. 7. Осуществляет поиск спецификации OpenAPI REST-сервиса ИС Ответчика. 8. Проверяет наличие у Инициатора прав доступа для обращения к REST-сервису Ответчика. 9. Опционально, если в спецификации параметр X-PODD-CLIENT-SYSTEM-MNEMONIC обязательный, то последовательно проверяет: - наличие заголовка X-PODD-CLIENT-SYSTEM-MNEMONIC; - значение в заголовке X-PODD-CLIENT-SYSTEM-MNEMONIC и сравнивает его с мнемоникой ИС Потребителя. 10. Выполняет валидацию на соответствие спецификации по чанку метаданных запроса: - валидация осуществляется по параметрам, заголовкам (в т.ч. обязательность наличия) и path; - тело запроса не валидируется. 11. Выполняет проверку соответствия ограничениям, заданным на REST-сервис ИС Ответчика: - на количество запросов от ИС Инициатора за интервал времени; - на объем данных, передаваемых ИС Потребителя по всем запросам за интервал времени. 12. Осуществляет маршрутизацию запроса. 13. Подписывает ЭП Ядра СМЭВ4 чанк метаданных запроса. 14. Передает в Агент Ответчика чанк метаданных или возвращает ошибку обработки запроса (при ее возникновении). 15. Получает подтверждение приема чанка метаданных от Агента Ответчика. 16. Опционально, если для спецификации установлен признак сохранять данные запроса и ответа. Сохраняет чанк метаданных запроса в хранилище Ядра СМЭВ4. 17. Передает подтверждение корректности запроса Агенту Инициатора. *Агент Инициатора:* 18. Подписывает ЭП Инициатора чанки тела. 19. Передает последовательно чанки тела запроса в Ядро СМЭВ4 с сохранением исходного порядка. *Ядро СМЭВ4:* 20. Проверяет ЭП Инициатора каждого чанка тела запроса. 21. Выполняет проверку соответствия ограничениям, заданным на REST-сервис ИС Ответчика: - на количество запросов от ИС Инициатора за интервал времени; - на объем данных, передаваемых ИС Потребителя по всем запросам за интервал времени. 22. Подписывает ЭП Ядра СМЭВ4 чанки тела запроса. 23. Последовательно передает чанки тела запроса в Агент Ответчика по протоколу СМЭВ4. 24. Получает подтверждение приема чанков тела запроса от Агента Ответчика (через Брокер). 25. Опционально, если для спецификации установлен признак сохранять данные запроса и ответа. Сохраняет чанк тела запроса в хранилище Ядра СМЭВ4. *Агент Ответчика:* 26. Проверяет ЭП Ядра. 27. Проверяет ЭП Инициатора. Если на стороне Агента Ответчика развернут и включен Сервис проверки полномочий: 28. Сервис проверки полномочий выполняет проверку подтверждения доступа на выполнение запроса к REST-сервису ИС Ответчика для Инициатора, отправившего запрос. 29. Если для запроса не подтвержден доступ, то Агент Поставщика прекращает выполнение запроса и возвращает Агенту Потребителя соответствующую ошибку в качестве результата запроса с использованием Протокола СМЭВ4. При подтвержденном доступе выполнение запроса продолжается. 30. Формирует абсолютный URL-адрес запроса к соответствующему методу REST-сервиса ИС Ответчика. 31. Отправляет запрос данных согласно URL-адресу. .. _img_seq_rest_rq_request: .. figure:: img/seq_rest_rq_request.png :align: center :alt: Диаграмма прохождения запроса к REST-сервису ИС Ответчика через СМЭВ4 Диаграмма прохождения запроса к REST-сервису ИС Ответчика через СМЭВ4 *Взаимодействие ИС Инициатора и ИС Ответчика при ответе на запрос к REST-сервису ИС Ответчика* (:numref:`img_seq_rest_rq_response`): *Агент Ответчика:* 1. Получает ответ на запрос от ИС Ответчика. 2. Делит ответ на запрос на чанк метаданных и чанки тела. 3. Подписывает чанк метаданных ЭП Ответчика. 4. Передает чанк метаданных в Ядро СМЭВ4. *Ядро СМЭВ4:* 5. Проверяет ЭП Ответчика чанка метаданных. 6. Выполняет проверку соответствия ограничениям, заданным на REST-сервис ИС Ответчика, на объем данных, возвращаемых ИС Инициатора по всем запросам за интервал времени. 7. Маршрутизирует ответ на запрос. 8. ( 21 ) Отправляет чанк метаданных в Агент Инициатора или возвращает ошибку обработки запроса Агенту Ответчика(при ее возникновении). 9. Получает подтверждение приема чанка метаданных от Агента Инициатора. 10. Опционально, если для спецификации установлен признак сохранять данные запроса и ответа, сохраняет чанк метаданных ответа в хранилище Ядра СМЭВ4. 11. Передает подтверждение корректности ответа на запрос в Агент Ответчика. *Агент Ответчика:* 12. Подписывает ЭП Ответчика чанки тела. 13. Отправляет последовательно чанки тела в Ядро СМЭВ4. *Ядро СМЭВ4:* 14. Проверяет ЭП Ответчика чанков тела. 15. Последовательно передает чанки тела в Агент Инициатора (через Брокер) по протоколу СМЭВ4. 16. Получает подтверждение приема чанков тела от Агента Инициатора (через Брокер). 17. Опционально, если для спецификации установлен признак сохранять данные запроса и ответа, сохраняет чанк тела ответа в хранилище Ядра СМЭВ4. *Агент Инициатора:* 18. Выполняет проверку ЭП Ответчика. 19. Извлекает из ответа на запрос HTTP код и тело (если присутствует). 20. Отправляет ответ ИС Инициатора. .. _img_seq_rest_rq_response: .. figure:: img/seq_rest_rq_response.png :align: center :alt: Диаграмма прохождения ответа на запрос к REST-сервису ИС Ответчика через СМЭВ4 Диаграмма прохождения ответа на запрос к REST-сервису ИС Ответчика через СМЭВ4 .. _smev_metadata: Метаданные СМЭВ4 ------------------------- Метаданные СМЭВ4 содержат информацию о следующих объектах: 1) модели данных Витрин Поставщиков данных; 2) определения Регламентированных SQL-запросов; 3) подписки Потребителей данных СМЭВ4 на регламентированный запрос типа «Рассылка (для Компонента «Витрина данных» версии 1.x)»; 4) REST-сервисы ИС Ответчиков, описываемые спецификацией OpenAPI; 5) права доступа Потребителей данных; 6) описание моделей виртуальных кластеров. .. _supported_formats: Поддерживаемые форматы ~~~~~~~~~~~~~~~~~~~~~~~ :numref:`tab_supported_formats` содержит ограничения на формат значений в загружаемых метаданных и сведения о проверках на стороне СМЭВ4. .. _tab_supported_formats: .. table:: Ограничения на формат значений в метаданных +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | № | Наименование | Тип | Требования к формату | +====+==================================================+=========+==============================================================================================================================================================================+ | 1 | Идентификатор | uuid | Маска: ``"([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})|(\{[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\})"`` | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 2 | Мнемоника (Витрины/ | String | Латинские буквы, цифры и символ "_", без пробелов. | | | Регламентированного запроса типа «SQL-запрос» / | | | | | Регламентированного запроса типа | | Первым символом должна быть буква. | | | «Рассылка» /атрибута/параметра) | | | | | | | Регистр не учитывается. | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 3 | Мнемоника (Витрины/ Регламентированного запроса | String | Запрещено использование зарезервированных ключевых слов SQL [4]_ | | | типа «SQL-запрос» / Регламентированного | | | | | запроса типа «Рассылка») | | | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 4 | Мнемоника (Регламентированного запроса типа | String | Запрещено использование префикса ``information_schema_`` | | | «SQL-запрос» /Регламентированного | | | | | запроса типа «Рассылка») | | | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 5 | Алиас атрибута в SQL запросе | String | Латинские буквы, цифры и символ "_", без пробелов. | | | | | | | | | | Первым символом должна быть буква. | | | | | | | | | | Регистр не учитывается. | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 6 | Версия (Витрины/ Регламентированного запроса | String | Должна соответствовать формату .< minor >: | | | типа «SQL-запрос»/ Регламентированного | | | | | запроса типа «Рассылка») | | - major типа int, >= 0; | | | | | | | | | | - minor типа int, >= 0. | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 7 | ОГРН УВ (владельца Витрины/ | String | ОГРН владельца Витрины должен соответствовать значению в ранее зарегистрированных версиях Витрины *Ожидаемый формат:* только цифры | | | Регламентированного запроса типа «SQL-запрос» / | | | | | Регламентированного запроса тип | | | | | «Рассылка») | | | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 8 | Даты поддержки (Витрины/ | Integer | В миллисекундах от эпохи. | | | | | | | | Регламентированного запроса типа «SQL-запрос» / | (int64) | Временной диапазон периода поддержки Регламентированного запроса типа «SQL-запрос» и Регламентированного запроса тип «Рассылка» должен входить в диапазоны поддержки всех | | | Регламентированного запроса тип | | Витрин, которые указаны в SQL данных Регламентированного запроса типа «SQL-запрос» и Регламентированного запроса тип «Рассылка». | | | «Рассылка») | | | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 9 | Текстовое описание (Витрины/ | String | *Ожидаемый формат:* латинские и русские буквы, цифры, печатные символы и символы разметки (пробел, перенос строки), максимум 2000 знаков | | | Регламентированного запроса типа «SQL-запрос» / | | | | | Регламентированного запроса тип | | | | | «Рассылка») | | | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 10 | Текст SQL-выражения (для | String | Поддерживаются возможности, указанные в :numref:`sql_syntax` данного документа | | | Регламентированного запроса типа «SQL-запрос» / | | | | | Регламентированного запроса тип | | | | | «Рассылка») | | | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 11 | Тип атрибута | String | - "BOOLEAN"; | | | | | | | | | | - "STRING"; | | | | | | | | | | - "INTEGER"; | | | | | | | | | | - "LONG"; | | | | | | | | | | - "FLOAT"; | | | | | | | | | | - "DOUBLE"; | | | | | | | | | | - "BIG_DECIMAL"; | | | | | | | | | | - "DATE"; | | | | | | | | | | - "TIME"; | | | | | | | | | | - "TIMESTAMP"; | | | | | | | | | | - "BINARY". | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 12 | Тип параметра | String | - "BOOLEAN"; | | | | | | | | | | - "STRING"; | | | | | | | | | | - "INTEGER"; | | | | | | | | | | - "LONG"; | | | | | | | | | | - "FLOAT"; | | | | | | | | | | - "DOUBLE"; | | | | | | | | | | - "BIG_DECIMAL"; | | | | | | | | | | - "DATE"; | | | | | | | | | | - "TIME"; | | | | | | | | | | - "TIMESTAMP". | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 13 | Префикс в URL для REST-сервиса ИС | String | Латинские буквы, цифры, символы. Из зарезервированных символов допустимы '/' и '_' | | | Ответчика (basepath) | | | | | | | - непустая строка; | | | | | | | | | | - начинается с символа '/'; | | | | | | | | | | - содержит символы после '/'. Допускается несколько элементов пути, например level1/level2/level3. Двойные слэши '//' недопустимы; | | | | | | | | | | - параметры недопустимы, например /{parameter}; | | | | | | | | | | - заканчивается символом, отличным от '/'. | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 14 | Спецификации OpenAPI для REST-сервиса | - | Поддерживаемые форматы: JSON, YAML. Максимальный размер 1 Мб | | | ИС Ответчика | | | +----+--------------------------------------------------+---------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. [4] https://calcite.apache.org/docs/reference.html#keywords .. _provider_model_data: Модель данных Витрины Поставщика данных ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Все передаваемые, получаемые и распространяемые посредством СМЭВ4 сведения должны соответствовать моделям данных Витрины Поставщика данных в Ядре СМЭВ4. Модели данных загружаются в Ядро СМЭВ4 из ФГИС «ЕИП НСУД» в соответствии с инструкцией по работе с ФГИС «ЕИП НСУД». **Модель данных Витрины Поставщика данных содержит:** 1. уникальную мнемонику Витрины; 2. ОГРН владельца Витрины; 3. версии Витрины, содержащие структуру сущностей. **Каждая версия Витрины содержит:** 1. номер версии Витрины; 2. описание для версии Витрины; 3. срок действия версии Витрины Поставщика данных (дата начала и дата окончания действия версии Витрины); 4. перечень таблиц версии Витрины со следующей информацией: - мнемоника и описание таблицы; - перечень атрибутов таблицы с указанием типа данных; - первичный ключ, состоящий из мнемоник атрибутов таблицы; - массив уникальных ключей, состоящий из мнемоник атрибутов таблицы; - атрибут linkingRecord, который необходим для автоматической подстановки в SQL-запросы условия фильтрации (WHERE) по конкретному источнику (витрине) при работе с кластером витрин. **Правила/ограничения использования:** 1. Модель данных Витрины Поставщика данных загружена в Ядро СМЭВ4, если загружена как минимум одна (первая) версия Витрины. 2. Значение ОГРН владельца должно быть одинаковым для всех версий Витрины. При несоответствии ОГРН значениям в ранее зарегистрированных версиях Витрины СМЭВ4 вернет ошибку регистрации. 3. Актуальной версией Витрины считается максимальная по номеру среди действующих. 4. Если в новой версии Витрины требуется расширить перечень доступных данных, при этом Потребители, уже имеющие полный доступ к Витрине, не должны автоматически получить доступ к новой версии, то изменение следует выполнить через регистрацию новой Витрины (с новой мнемоникой), а не через выпуск новой ее версии. 5. Для выполнения запроса к определенной версии Витрины необходимо в запросе после мнемоники витрины явно указать номер версии. Пример приведен в :numref:`original_query_transform` настоящего документа. .. _datamart_profile: Профиль Витрины Поставщика данных ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Способ передачи и поддержка системных параметров при выполнении подзапросов к Витрине определяются в Профиле витрины, информация о них размещается в метахранилище Ядра СМЭВ4. Профиль витрины содержит следующие настройки: 1) subQueryParamSupport – способ передачи подзапроса при выполнении РЗ с параметрами на стороне Витрины, возможные значения: - NOT_SUPPORTED: отправка подзапроса с параметрами, подставленными в SQL-выражение (значение по-умолчанию); - DYNAMIC_PARAM_SUPPORT: отправка подзапроса с блоком динамических параметров, подстановка осуществляется на стороне Адаптера Витрины; - NAMED_PARAM_SUPPORT: отправка подзапроса с блоком именованных параметров, подстановка осуществляется на стороне Адаптера Витрины. .. note:: При использовании Агента СМЭВ4 совместно с Сервисом проверки полномочий Prohibitor необходимо установить настройку subQueryParamSupport: "DYNAMIC_PARAM_SUPPORT" 2) forSystemTimeParameterSupport – поддержка системного параметра РЗ для запроса актуальных, на заданный момент времени, данных из Витрины: - false: Адаптер Витрины не поддерживает обработку параметра; - true: Адаптер Витрины поддерживает обработку параметра (значение по-умолчанию). Изменения в настройки Профиля витрины могут вносить специалисты службы эксплуатации СМЭВ4 по запросу от участника взаимодействия. .. _sql_request_definition: Определения Регламентированных SQL-запросов ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Регистрация Регламентированного SQL-запроса в СМЭВ4 осуществляется с использованием ЕИП НСУД в соответствии с инструкцией по работе с ФГИС «ЕИП НСУД». **Состав атрибутов определения Регламентированного SQL-запроса:** 1. мнемоника Регламентированного SQL-запроса; 2. версии Регламентированного SQL-запроса. .. _sql_rz_content: Содержание Регламентированного SQL-запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Каждая версия Регламентированного SQL-запроса содержит:** 1. описание Регламентированного SQL-запроса (краткое и полное); 2. ОГРН владельца Регламентированного SQL-запроса; 3. номер версии Регламентированного SQL-запроса; 4. срок действия Регламентированного SQL-запроса (дата начала и дата окончания действия, в рамках которых возможно выполнение соответствующего запроса); 5. SQL-выражение в соответствии с :numref:`sql_syntax` данного документа и указанными ниже ограничениями; 6. последовательность выполнения подзапросов к витринам поставщиков (только для распределенных запросов); 7. (опционально) признак необходимости сохранять данные запросов и ответов. Если не передан, присваивается значение по умолчанию - false . Примечание: может быть изменено по запросу в службу эксплуатации СМЭВ4. 8. (при наличии) список параметров. Описание параметра включает в себя: - мнемоника параметра; - тип параметра; - описание параметра; - значение по умолчанию. 9. (при наличии) список табличных параметров. Описание параметров включает в себя: - мнемоника табличного параметра; - описание колонок табличного параметра: - мнемоника колонки; - тип колонки; - описание колонки. 10. (для Регламентированных запросов без SQL-выражения – запросов печатных форм) список атрибутов, возвращаемых в ответе на SQL-РЗ, включающих: - мнемоника атрибута; - тип атрибута; - описание атрибута. 11. (опционально) признак необходимости обеспечения юридической значимости обмена. .. _rules_use: Правила/ограничения использования ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Версия Регламентированного SQL-запроса не подлежит модификации. При необходимости изменить SQL-выражение создается запрос с новой версией. 2. ОГРН Владельца и мнемоника Регламентированного SQL-запроса задаются для каждой версии отдельно, поэтому контроль их соответствия у версий ложится на создателей этих версий. 3. Актуальной версией Регламентированного SQL-запроса считается максимальная по номеру среди действующих. 4. Если в новой версии Регламентированного SQL-запроса требуется изменить входные или выходные данные, при этом Потребители, уже имеющие доступ к Регламентированному SQL-запросу, не должны автоматически получить доступ к новой версии, то изменение следует выполнить через регистрацию нового Регламентированного SQL-запроса (с новой мнемоникой), а не через выпуск новой его версии. 5. Временной диапазон срока действия Регламентированного SQL-запроса должен входить в диапазоны поддержки всех Витрин, которые указаны в SQL-выражении данного Регламентированного SQL-запроса. 6. Параметры Регламентированного SQL-запроса должны соответствовать условиям: - табличные и именованные параметры в SQL-выражении должны соответствовать параметрам в списке; - мнемоники параметров должны быть уникальными в рамках Регламентированного SQL-запроса, уникальность именованных и табличных параметров сквозная; - мнемоника параметра не должна начинаться с ``settings_`` (префикс системного именованного параметра); - при задании параметров в SQL-выражении через «?» порядок параметров в списке должен соответствовать порядку их представления в SQL-выражении; - при задании параметров в SQL-выражении через «?» количество параметров в SQL-выражении должно соответствовать количеству параметров в списке; - для Регламентированных запросов без SQL-выражения (запросов печатных форм): - обязателен входной параметр «DocType», определяющий тип формируемого документа (указывается первым параметром); - допустимо указание опциональных параметров, используемых для получения данных из Витрины (указываются после обязательно «DocType»); - и выходные атрибуты, определяющие состав ответа на запрос: - DocType – тип сформированного документа; - FileName – имя файла сформированного документа; - Content – содержимое сформированного документа в base64 (можно задать любой тип данных). 7. SQL-выражение для Регламентированного SQL-запроса должно соответствовать условиям: - Витрины, имена возвращаемых атрибутов, таблицы и схема данных должны соответствовать метаданным Витрины, сохраненным в Ядре СМЭВ4; - должна быть указана конкретная версия Витрины (правильно – dtm.1.0.table; неправильно – dtm.table); - указанная версия Витрины должна быть зарегистрирована в СМЭВ4; - не должно быть указано несколько версий одной Витрины; - простой запрос должен быть к одной Витрине; - для простого запроса Витрина в SQL-выражении должна соответствовать Витрине, указанной в полной мнемонике Регламентированного SQL-запроса; - распределенный запрос должен быть к двум или более Витринам; - не должно быть обращений к другим Регламентированного SQL-запроса; - в SQL-выражении должны быть указаны конкретные возвращаемые атрибуты (возврат всех атрибутов через * запрещен). При использовании табличных параметров необходимо явно перечислять поля таблиц, по которым будет выполняться фильтрация записей или объединение таблиц. Исключение: возможно использовать * внутри операторов (пример: count ( * )); - возвращаемые Потребителю атрибуты должны быть уникальны с учетом подставленных алисов; - SQL-выражение отсутствует в Регламентированных запросах без SQL-выражения (запросах печатных форм). 8. Возможность указания дополнительных условий фильтрации и операций над получаемыми данными (order by, limit, where, перечисление полей вместо * и любые другие запросы отличные от select * from <мнемоника Витрины>.<версия Регламентированного SQL-запроса (опционально)>.<мнемоника Регламентированного SQL-запроса>(<параметры>)) при вызове регламентированного SQL-запроса ограничена. При наличии потребности использовать такие надстройки рекомендуется обратиться к поставщику данных для добавления их в SQL-выражение. 9. Если Регламентированный SQL-запрос планируется использовать в качестве Регламентированного запроса типа «Рассылка (для Компонента «Витрина данных» версии 1.x)», то он должен соответствовать требованиям, приведённым в :numref:`distribution_interaction_description`. 10. Если для Регламентированного SQL-запроса включена оптимизация, то SQL-выражение этого запроса может быть преобразовано системой для ускорения или оптимизации использования ресурсов, при его выполнении. Если оптимизация выключена, то преобразование структуры SQL-выражения не выполняется. .. note:: Оптимизация всегда выполняется для следующих типов запросов: - распределенные SQL-РЗ - РЗ без SQL-выражения - запросы печатных форм - SQL-РЗ с переданными в вызове надстройками Для остальных типов запросов оптимизация не выполняется. .. _view_create_rule: Правило создания представлений ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: Данное правило распространяется только для витрины версии 2.0.0 и выше Для каждой таблицы, указанной в основном SQL-выражении, вызываемого SQL-РЗ должны быть предварительно созданы представления ``view``. Запрос на создание ``view`` строится следующим образом: - ``CREATE VIEW`` - команда создания ``view``; - Наименование представления. Формируется по следующему принципу: ``v<мажорный номер версии SQL-РЗ>_<наименование таблицы>`` - ``SELECT * FROM <наименование таблицы>``. Запрос, который определяет, какие данные будут отображаться в представлении. Пример запроса на создание view: .. code-block:: CREATE VIEW v1_tbl1 AS SELECT * FROM tbl1 .. _distribution_subscription: Подписки Потребителей данных СМЭВ4 на регламентированный запрос типа «Рассылка (для Компонента «Витрина данных» версии 1.x)» ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Подписка предоставляет возможность Потребителю данных оперативно получать изменяющиеся в Витринах Поставщиков данные. :numref:`tab_distribution_subscription` содержит Метаданные подписки. .. _tab_distribution_subscription: .. table:: Метаданные Подписки +-----+------------------+-----------------------------------------------------------+ | № | Атрибут | Описание | +=====+==================+===========================================================+ | 1 | subscriptionId | Уникальный идентификатор подписки. | | | | | | | | Генерируется СМЭВ4 в соответствии с форматом UUID. | +-----+------------------+-----------------------------------------------------------+ | 2 | RQs | Массив регламентированных запросов типа «Рассылка (для | | | | Компонента «Витрина данных» версии 1.x)». | | | | | | | | При указании нескольких запросов используется | | | | множественная подписка. Использование распределённых | | | | запросов в таком случае недопустимо. | +-----+------------------+-----------------------------------------------------------+ | 2.1 | queryMnemonic | Полная мнемоника Регламентированного запроса: | | | | <мнемоника витрины>.<мнемоника РЗ>. | | | | | | | | Для распределенного запроса: podd.<мнемоника РЗ>. | +-----+------------------+-----------------------------------------------------------+ | 2.2 | version | Номер версии Регламентированного запроса в формате: | | | | . | +-----+------------------+-----------------------------------------------------------+ | 3 | datamartMnemonic | Мнемоника Витрины Потребителя (без учёта версионности) | +-----+------------------+-----------------------------------------------------------+ | 4 | name | Наименование подписки (для краткой формулировки). | | | | | | | | Опционально. | +-----+------------------+-----------------------------------------------------------+ | 5 | description | Описание подписки (для подробного описания). | | | | | | | | Опционально. | +-----+------------------+-----------------------------------------------------------+ | 6 | isSnapshot | Признак того, что сначала Потребителю нужно выгрузить | | | | снапшот. | | | | | | | | Значение по умолчанию - ``false``. | | | | | | | | Опционально. | +-----+------------------+-----------------------------------------------------------+ | 7 | initiator | Признак того, кто является инициатором запроса новой | | | | дельты: | | | | | | | | - "PODD" - Ядро СМЭВ4; | | | | | | | | - "CONSUMER" – Потребитель (Ядро СМЭВ4 передаёт | | | | уведомления о наличии дельт Потребителю, который | | | | инициирует запрос в соответствии с собственными | | | | настройками). | | | | | | | | Значение по умолчанию - PODD. | | | | | | | | Опционально. | +-----+------------------+-----------------------------------------------------------+ | 8 | schedule | Расписание запроса Ядром СМЭВ4 дельт у Витрины | | | | Поставщика. | | | | | | | | Представляет собой cron-выражение. | | | | | | | | Для подписок, в которых инициатором является Потребитель, | | | | значение атрибута всегда отсутствует. | | | | | | | | Опционально. | +-----+------------------+-----------------------------------------------------------+ | 9 | status | Статус подписки, формируется СМЭВ4 по ходу | | | | регистрации и удаления подписки: | | | | | | | | - REGISTRATION_REQUEST – Подписка принята к регистрации в | | | | СМЭВ4; | | | | | | | | - REGISTRATION_ON_PRODUCER – Подписка регистрируется на | | | | Поставщике; | | | | | | | | - REGISTRATION_ON_PRODUCER_ERROR – Подписка не | | | | зарегистрирована на Поставщике, возникла ошибка; | | | | | | | | - REGISTRATION_ON_CONSUMER – Подписка регистрируется на | | | | Потребителе; | | | | | | | | - REGISTRATION_ON_CONSUMER_ERROR – Подписка не | | | | зарегистрирована на Потребителе, возникла ошибка; | | | | | | | | - REGISTERED – Подписка зарегистрирована; | | | | | | | | - CANCEL_REQUEST – Принят запрос на удаление подписки | | | | (обмен по ней останавливается); | | | | | | | | - CANCEL_ON_PRODUCER (Удаление на Поставщике); | | | | | | | | - CANCEL_ON_CONSUMER (Удаление на Потребителе). | +-----+------------------+-----------------------------------------------------------+ Функционирование Агента СМЭВ4 и Ядра СМЭВ4 при формировании первоначальной выгрузки и передачи изменений по подписке от Витрины Поставщика данных в Витрину Потребителя данных приведено в :numref:`rest_exchange_description` и :numref:`distribution_consumer_protocol` данного документа. Регистрация подписки осуществляется через: - ЛК УВ; - ЕИП в случае тиражирования подписок (создание копии подписки, в которой изменяется только идентификатор и витрина потребителя). - СЭ в случае необходимости ручного вмешательства. Удаление подписки осуществляется через: - ЛК УВ; - СЭ в случае необходимости ручного вмешательства. .. _respondent_rest_services: REST-сервисы ИС Ответчиков ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Регистрация REST-сервиса ИС Ответчика (Регламентированного запроса типа REST-сервис) в СМЭВ4 осуществляется с использованием ЛК УВ в соответствии с инструкцией в документе «Руководстве пользователя ЛК УВ». REST-сервис ИС Ответчика в СМЭВ4 определяется следующими атрибутами: 1. Мнемоника ИС Ответчика. 2. Префикс в URL методов API (basepath) 3. Наименование спецификации. 4. Спецификация OpenAPI, описывающая REST-сервис ИС Ответчика. 5. Признак необходимости сквозной передачи подписи Инициатора Ответчику (по умолчанию true). 6. Признак необходимости сохранять данные запросов и ответов (по умолчанию false). Примечание: может быть изменено по запросу в службу эксплуатации СМЭВ4. 7. Признак необходимости обеспечения юридической значимости обмена (по умолчанию false). **Правила разработки спецификаций OpenAPI, используемых для описания и регистрации REST-сервисов Ответчиков в СМЭВ4:** 1. Следует руководствоваться форматом проектирования спецификаций OpenAPI версии 3.0 (в том числе минорных версий 3.0.1, 3.0.2 и т.д.). 2. В спецификациях OpenAPI могут быть использованы все типы HTTP-методов (POST, GET, PUT и DELETE), выполняющих CRUD-операции (Create/Read/Update/Delete). 3. Допустимые форматы: YAML или JSON. 4. Максимальный размер: 1 Мб. 5. Если требуется передача мнемоники Инициатора до Ответчика, то в Спецификации OpenAPI REST-сервиса Ответчика должен присутствовать заголовок X-PODD-CLIENT-SYSTEM-MNEMONIC. При его наличии в СМЭВ4 осуществляется проверка соответствия мнемоники ИС, с которой пришёл запрос, и мнемоники ИС, указанной в заголовке. Примеры спецификаций OpenAPI, используемых в работе с REST-сервисами в СМЭВ4: 1. Спецификация OpenAPI, описывающая REST-сервис с функцией возврата запрошенных данных от ИС Ответчика .. code-block:: yaml { "openapi": "3.0.1", "info": { "title": "Letters content | Содержимое писем", "version": "1.0" }, "servers": [ { "url": "/" } ], "tags": [ { "name": "Letters content | Содержимое писем" } ], "paths": { "/api/v1.0/letters/{mailId}/{date}/pdf": { "get": { "tags": [ "Letters content | Содержимое писем" ], "summary": "Получение содержимого письма в формате PDF", "operationId": "getLetterPdf", "parameters": [ { "name": "Authorization", "in": "header", "description": "Authorization header", "required": true, "schema": { "type": "string" } }, { "name": "mailId", "in": "path", "description": "ШПИ", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "path", "description": "Дата", "required": true, "schema": { "type": "string" } }, { "name": "accessCode", "in": "query", "description": "Код доступа", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ОК", "content": {} }, "400": { "description": "Некорректный запрос", "content": {} }, "401": { "description": "Некорректный идентификатор клиента и/или токен", "content": {} }, "403": { "description": "Доступ запрещен", "content": {} }, "404": { "description": "Запрашиваемый ресурс не найден", "content": {} }, "500": { "description": "Внутренняя ошибка сервиса", "content": {} } } } }, "/api/v1.0/letters/{mailId}/{date}/content": { "get": { "tags": [ "Letters content | Содержимое писем" ], "summary": "Получение содержимого письма в формате ZIP", "operationId": "getLetterContent", "parameters": [ { "name": "Authorization", "in": "header", "description": "Authorization header", "required": true, "schema": { "type": "string" } }, { "name": "mailId", "in": "path", "description": "ШПИ", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "path", "description": "Дата", "required": true, "schema": { "type": "string" } }, { "name": "accessCode", "in": "query", "description": "Код доступа", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ОК", "content": {} }, "400": { "description": "Некорректный запрос", "content": {} }, "401": { "description": "Некорректный идентификатор клиента и/или токен", "content": {} }, "403": { "description": "Доступ запрещен", "content": {} }, "404": { "description": "Запрашиваемый ресурс не найден", "content": {} }, "500": { "description": "Внутренняя ошибка сервиса", "content": {} } } } } }, "components": {} } 2. Спецификация OpenAPI, описывающая REST-сервис с функцией модификации данных ИС Ответчика: .. code-block:: yaml { "openapi": "3.0.2", "info": { "description": "Спецификация OpenAPI 3.0 для сервиса записи на приём к врачу", "version": "1.0", "title": "Запись на приём к врачу – OpenAPI 3.0" }, "paths": { "/booking/book": { "post": { "summary": "Бронирование слота", "description": "Бронирование слота", "operationId": "book", "requestBody": { "description": "Запрос", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookRequest" } } }, "required": true }, "responses": { "200": { "description": "Успешная операция", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookResponse" } } } }, "400": { "description": "Неверные параметры" }, "500": { "description": "Внутренняя ошибка" } } } }, "/booking/cancel": { "post": { "summary": "Отмена брони", "description": "Отмена брони", "operationId": "cancel", "requestBody": { "description": "Запрос", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } }, "required": true }, "responses": { "200": { "description": "Успешная операция", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookResponse" } } } }, "400": { "description": "Неверные параметры" }, "500": { "description": "Внутренняя ошибка" } } } } }, "components": { "schemas": { "BookRequest": { "type": "object", "properties": { "bookId": { "type": "string" }, "slotId": { "type": "string" }, "patient_id": { "type": "string" }, "booking_type": { "type": "string" }, "caseNumber": { "type": "string" }, "preliminaryReservation": { "type": "boolean" }, "referral_id": { "type": "string" }, "cards_id": { "type": "string" }, "email": { "type": "string" }, "mobilePhone": { "type": "string" } }, "required": [ "bookId", "slotId", "patient_id" ] }, "BookResponse": { "oneOf": [ { "$ref": "#/components/schemas/BookResponseSuccess" }, { "$ref": "#/components/schemas/BookResponseError" } ] }, "BookResponseSuccess": { "type": "object", "properties": { "bookExtId": { "type": "string" }, "slotId": { "type": "string" }, "visitTime": { "type": "string" }, "duration": { "type": "string" }, "serviceId": { "type": "string" }, "organizationId": { "type": "string" }, "areaId": { "type": "string" }, "queueNumber": { "type": "string" }, "pincode": { "type": "string" }, "window": { "type": "string" }, "status": { "$ref": "#/components/schemas/Status" } }, "required": [ "bookExtId", "slotId", "visitTime", "status" ] }, "BookResponseError": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/Status" } }, "required": [ "status" ] }, "CancelRequest": { "type": "object", "properties": { "bookExtId": { "type": "string" }, "patient_id": { "type": "string" } }, "required": [ "bookExtId", "patient_id" ] }, "Status": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" } }, "required": [ "statusCode" ] } } } } .. _consumer_data_authority: Права доступа Потребителя данных СМЭВ4 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Потребителю данных могут быть предоставлены следующие типы прав: - право доступа на выполнение произвольных SQL-запросов; - право доступа на выполнение Регламентированных SQL-запросов; - право доступа на выполнение запросов к REST-сервису ИС Ответчика; - право доступа на Рассылку; - право доступа на получение данных запросов и ответов, сохраненных по результатам выполнения запросов к REST-сервису ИС Ответчика. .. _random_request_authority: Право доступа на выполнение произвольных SQL-запросов ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Предоставляется автоматически и только владельцам Витрин данных на их собственные Витрины. .. _regulated_request_authority: Право доступа на выполнение Регламентированных SQL-запросов ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Для предоставления Потребителю данных возможности выполнения Регламентированного SQL-запроса к данным Витрины Поставщика данных необходимо предоставить право доступа на его выполнение. Право доступа предоставляется на Регламентированный SQL-запрос целиком: - права на атрибуты Регламентированного SQL-запроса не выдаются; - право доступа распространяется на все версии Регламентированного SQL-запроса (включая будущие). Выдача прав доступа в СМЭВ4 осуществляется с использованием ЛК УВ в соответствии с инструкцией в документе «Руководство пользователя ЛК УВ». Поставщику данных доступна возможность выдать дополнительное разрешение (полномочие) на выполнение Регламентированного SQL-запроса с использованием Сервиса проверки полномочий, развернутого с Агентом СМЭВ4. Данный сервис обеспечивает возможность подтвердить или временно заблокировать право доступа на выполнение версии Регламентированного SQL-запроса, не изменяя загруженные в СМЭВ4 права доступа. .. _respondent_request_authority: Право доступа на выполнение запросов к REST-сервису ИС Ответчика ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Право доступа на выполнение запросов к REST-сервису ИС Ответчика (Регламентированный запрос типа «REST-сервис») предоставляется на все запросы, указанные в загруженной в СМЭВ4 спецификации OpenAPI для соответствующего REST-сервиса ИС Ответчика. Права на использование отдельных методов и запросов REST-сервиса не выдаются. Управление правами доступа осуществляется с использованием ЛК УВ в соответствии с инструкцией в документе «Руководство пользователя ЛК УВ». Поставщику данных доступна возможность выдать дополнительное разрешение (полномочие) на выполнение запросов к REST-сервису ИС Ответчика с использованием Сервиса проверки полномочий, развернутого с Агентом СМЭВ4. Данный сервис обеспечивает возможность подтвердить или временно заблокировать право доступа на выполнение запроса к REST-сервису ИС Ответчика, не изменяя загруженные в СМЭВ4 права доступа. .. _ditribution_authority: Право доступа на Рассылку ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Право доступа на доступ к Регламентированному запросу типа «Рассылка (для Компонента «Витрина данных» версии 1.x)» предоставляются исключительно органам исполнительной власти. Использование Регламентированных запросов типа «Рассылка (для Компонента «Витрина данных» версии 1.x)» кредитными организациями и в коммерческих целях запрещено. Управление правами доступа осуществляется с использованием ЛК УВ в соответствии с инструкцией в документе «Руководство пользователя ЛК УВ». .. _virtual_cluster: Виртуальный кластер ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Описания виртуальных кластеров загружаются в Ядро СМЭВ4 из ФГИС «ЕИП НСУД» в соответствии с инструкцией по работе с ФГИС «ЕИП НСУД». Возможны следующие операции: 1. Получение перечня виртуальных кластеров и всех их версий. 2. Создание новой версии виртуального кластера. 3. Обновление версии виртуального кластера. 4. Удаление версии виртуального кластера (при удалении кластера удаляются его связи с витринами). 5. Добавление связи версии виртуального кластера и версии витрины. Нельзя добавлять в один виртуальный кластер разные версии одной и той же витрины. 6. Удаление связи версии виртуального кластера и версии витрины. 7. Добавление разрешения на выполнение подзапроса к витрине кластера. 8. Удаление разрешения на выполнение подзапроса к витрине кластера. Мета-описание виртуального кластера включает следующие атрибуты: .. table:: Атрибуты виртуального кластера +-------+------------------+-----------------------------------------------------------------------------+ | **№** | **Атрибут** | **Описание** | +=======+==================+=============================================================================+ | 1 | mnemonic | Уникальная, текстовая мнемоника кластера. Неизменяема после создания. | | | | | | | | Используется для обращения к кластеру в SQL-запросах. | +-------+------------------+-----------------------------------------------------------------------------+ | 2 | version | Номер новой версии кластера. Формат "major.minor" (например, "1.0", "2.1"). | +-------+------------------+-----------------------------------------------------------------------------+ | 3 | description | Человекочитаемое описание назначения версии кластера | +-------+------------------+-----------------------------------------------------------------------------+ | 4 | datamartClasses | Описание единой схемы данных, которой должны соответствовать все витрины, | | | | входящие в эту версию кластера. | | | | | | | | Включает описание таблиц, полей, их типов. | | | | | | | | Структура аналогична той, которая применяется при создании витрины. | +-------+------------------+-----------------------------------------------------------------------------+ Мета-описание объекта связи витрины и виртуального кластера (для добавления витрины в кластер): .. table:: Атрибуты объекта связи витрины и виртуального кластера +-------+----------------------+-----------------------------------------------------------------------------+ | **№** | **Атрибут** | **Описание** | +=======+======================+=============================================================================+ | 1 | dtm_cluster_mnemonic | Уникальная, текстовая мнемоника кластера. Неизменяема после создания. | | | | | | | | Используется для обращения к кластеру в SQL-запроса. | +-------+----------------------+-----------------------------------------------------------------------------+ | 2 | version | Номер новой версии кластера. Формат "major.minor" (например, "1.0", "2.1") | +-------+----------------------+-----------------------------------------------------------------------------+ | 3 | dtm_mnemonic | Мнемоника витрины данных, входящая в кластер | +-------+----------------------+-----------------------------------------------------------------------------+ | 4 | datamart_version | Версия витрины данных | +-------+----------------------+-----------------------------------------------------------------------------+ | 5 | rq_mnemonics | Опциональный список (массив) мнемоник SQL-РЗ: | | | | | | | | - Если массив заполнен, связь активна только при вызове одного из | | | | перечисленных в нем SQL-РЗ; | | | | | | | | - Если массив не заполнен, связь не активна при вызове любого SQL-РЗ. | +-------+----------------------+-----------------------------------------------------------------------------+ **Правила и ограничения использования:** 1. Мнемоника виртуального кластера должна быть уникальна как среди виртуальных кластеров, так и среди мнемоник витрин данных. 2. В рамках одного кластера не допускается наличие нескольких версий витрины с одинаковой мнемоникой. 3. Схема данных виртуального кластера и витрин входящих в кластер должны совпадать (у витрины может быть больше атрибутов и таблиц, чем в кластере, но не меньше и типы данных пересекающихся атрибутов должны соответствовать). .. _smev_data_types: Типы данных СМЭВ4 ------------------------- Поддерживаемые СМЭВ4 типы данных и соответствующие им физические и логические типы данных avro приведены в :numref:`tab_smev_data_types`. Типы данных приведены к используемым в системе Prostore (каноническое avro). .. _tab_smev_data_types: .. table:: Соответствие типов данных СМЭВ4 и типов данных avro +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+ | № | Описание типа | Размерность | Имя типа СМЭВ4| Возможные значения | Физический тип avro | Логический тип avro | Особенности соответствия типов | +====+================+=============+===============+========================================+=====================+==========================+================================+ | 1 | Строка | | STRING | не ограничено | string | | | +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+ | 2 | Целое число | 8 байт | LONG | от −9223372036854775808 | long | | | | | | | | до 9223372036854775807 | | | | +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+ | 3 | Целое число | 2 байта | SHORT | от −32768 до 32767 | int | | | +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+ | 4 | Целое число | 4 байта | INTEGER | от -2147483648 до 2147483647 | int | | | +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+ | 5 | Дата | 4 байта | DATE | от -2147483648 до 2147483647 | int | date | unix epoch в днях, от -5 883 | | | | | | | | | 516 года до 5 883 515 года | +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+ | 6 | Время | 8 байт | TIME | от −9223372036854775808 | long | time-micros | | | | | | | до 9223372036854775807 | | | | +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+ | 7 | Числовые | 4 байта | FLOAT | от – (2-2\ :sup:`-23`) * 2\ :sup:`127` | float | | | | | данные с | | | до (2-2\ :sup:`-23`) * 2\ :sup:`127` | | | | | | плавающей | | | | | | | | | запятой | | | | | | | +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+ | 8 | Числовые | 8 байт | DOUBLE | от -1.7 * 10\ :sup:`308` | double | | | | | данные с | | | до 1.7 * 10\ :sup:`308` | | | | | | плавающей | | | | | | | | | запятой | | | | | | | +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+ | 9 | Большие | | BIG_DECIMAL | не ограничено | string | BigDecimalLogicalType | | | | числовые | | | | | | | | | данные с | | | | | | | | | плавающей | | | | | | | | | запятой | | | | | | | +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+ | 10 | Временная | 8 байт | TIMESTAMP | от −9223372036854775808 | long | timestamp-micros или | unix epoch в микросекундах, от | | | метка | | | | | LocalDateTimeLogicalType | – 292277 года до 292277 года | +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+ | 11 | Двоичные | | BINARY | не ограничено | bytes или record | | | | | данные | | | | | | | +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+ | 12 | Булевый тип | 1 байт | BOOLEAN | true, false | boolean | | | +----+----------------+-------------+---------------+----------------------------------------+---------------------+--------------------------+--------------------------------+