2. Описание подключения к ПОДД СМЭВ

2.1. Подключение участников взаимодействия с использованием ПОДД СМЭВ

Основным способом направления обращений является использование Личного кабинета СЦ https://sc.minsvyaz.ru.

Электронная почта sd@sc.minsvyaz.ru является резервным способом направления обращений, который используется в случае недоступности Личного кабинета СЦ.

Более подробная информация о порядке подключения к СМЭВ 4 приведена в документе «Правила и процедуры работы в подсистеме обеспечения доступа к данным федеральной государственной информационной системы «Единая система межведомственного электронного взаимодействия» по Методическим рекомендациям версии 4.XX» [20].

2.2. Протокол взаимодействия Агента СМЭВ4 и Витрины Поставщика данных

Агент Поставщика данных может взаимодействовать с несколькими Витринами. Протокол коммуникации Агента СМЭВ4 и Витрин реализован в виде обмена сообщениями с использованием зарезервированных топиков брокера сообщений Apache Kafka.

2.2.1. Перечень топиков брокера сообщений Apache Kafka

Конфигурация Агента СМЭВ4 содержит перечень Витрин, с которыми он взаимодействует. Каждой Витрине в зависимости от настроек конфигурации, заданных в соответствии с «Руководством администратора Агента СМЭВ4»[21] соответствует один из наборов топиков:

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

Названия топиков брокера сообщений [22] приведены в Таблица 2.3.

Таблица 2.3 Названия топиков брокера сообщений Apache Kafka
№	Топик	Публикатор	Подписчик	Передаваемый объект
Топики регистрации и настройки Витрин
1	datamart.signal	Витрина	Агент	Сообщение с регистрационными данными Витрины
2	<префикс>.profile.rq	Агент	Витрина	Запрос профиля Витрины
3	<префикс>.profile.rs	Витрина	Агент	Профиль Витрины
4	<префикс>.profile.err	Витрина	Агент	Ошибка при выполнении запроса профиля Витрины
5	<префикс>.signal	Агент	Витрина	Сообщение с итогами выполнения регистрации Витрины
Топики для обеспечения информационного обмена с использованием SQL-запросов
6	<префикс>.query.rq	Агент	Витрина	Подзапрос
7	<префикс>.procedure.query.rq	Агент	Витрина	Регламентированный запрос на исполнение
8	<префикс>.query.tp	Агент	Витрина	Подзапрос с использованием табличного параметра
9	<префикс>.query.tp.bin	Агент	Витрина	Подзапрос с использованием табличного параметра (при бинарном разбиении на чанки)
10	<префикс>.query.rs	Витрина	Агент	Результата подзапроса
11	<префикс>.query.estimation.rs	Витрина	Агент	Оценка (статистика) по исполнению подзапросов
12	<префикс>.query.err	Витрина	Агент	Ошибка при выполнении подзапроса
13	<префикс>.blob.rq	Агент	Витрина	Запрос двоичных данных по ссылке
14	<префикс>.blob.rs	Витрина	Агент	Результат запроса двоичных данных по ссылке
15	<префикс>.blob.err	Витрина	Агент	Ошибка при выполнении запроса двоичных данных по ссылке
16	<префикс>.cancel.rq	Агент	Витрина	Идентификатора запроса, выполнение которого в Витрине нужно отменить
17	<префикс>.cancel.rs	Витрина	Агент	Результат успешной отмены запроса
18	<префикс>.cancel.err	Витрина	Агент	Ошибка при выполнении отмены запроса
Топики для обеспечения информационного обмена с использованием Рассылок
19	<префикс>.replication.rq	Агент	Витрина	Информация о подписке
20	<префикс>.replication.rs	Витрина	Агент	Структура данных для хранения данных по подписке
21	<префикс>.replication.err	Витрина	Агент	Ошибка при обработке подписки
22	<префикс>.delta.rq	Агент	Витрина	Запрос пакета дельт по подписке
23	<префикс>.delta.tp	Агент	Витрина	Запрос на пересечение ключей и дельт по пересечённым ключам
24	<префикс>.delta.rs	Витрина	Агент	Дельта по подписке
25	<префикс>.delta.err	Витрина	Агент	Ошибка при формировании Витриной дельты по подписке
26	<префикс>.replication.cancel.rq	Агент	Витрина	Идентификатора отменяемой подписки
27	<префикс>.replication.cancel.rs	Витрина	Агент	Результат (успешный или ошибка) отмены подписки
28	<префикс>.delta.notification	Витрина	Агент	Уведомление о наличии дельты по подписке в Витрине Поставщика
Топики для получения статистики по Витринам
29	<префикс>.statistic.rq	Агент	Витрина	Запрос статистики таблиц
30	<префикс>.statistic.rs	Витрина	Агент	Статистика таблиц
31	<префикс>.statistic.err	Витрина	Агент	Ошибка формировании статистики таблиц
Топики для получения событий Витрины
32	<префикс>.scl.signal	Витрина	Агент	События Витрины для дальнейшей передачи в СЦЛ
Топики для временного хранения сообщений при недоступности ПОДД СМЭВ
33	<идентификатор ядра ПОДД>. <мнемоника агента>.undelivered. message	Агент	Агент	Сообщения от Витрины для передачи в ПОДД

2.2.2. Настройка Агента СМЭВ4 для работы Витринами данных

В ПОДД предусмотрено два способа регистрации Витрин:

на основе сообщений от Витрин;
на основе конфигурационного файла.

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

2.2.2.1. Регистрация на основе конфигурационного файла

Поддерживается на стороне Потребителя и Поставщика. Таблица 2.4 содержит описание процесса регистрации Витрины.

Таблица 2.4 Процесс регистрации Витрины данных
Процесс	Шаг	Описание
Инициация регистрации	1	При запуске Агент СМЭВ4 вычитывает локальный конфигурационный файл [23] с настройками регистрации Витрин. Витрина может быть зарегистрирована: статически (при явном указании в конфигурационном файле) динамически (автоматическая регистрация Витрины при обращению к/от Витрины, без необходимости указания в конфигурационном файле) и создает согласно настройкам в конфигурационном файле: группу топиков по умолчанию (для динамически регистрируемых Витрин) одну или несколько дополнительных групп топиков (для статически регистрируемых Витрин)
	2	Если одному из Агентов приходит сообщение из Ядра ПОДД СМЭВ для незарегистрированной Витрины, Агент регистрирует её динамически (и при необходимости создает группу топиков по умолчанию).
	3	Если инициатором сообщения будет Витрина или ИС Потребителя, они будут зарегистрированы динамически, если при старте Агента создана группа топиков по умолчанию.
Регистрация	4	Агент загружает профиль Витрины. Способ загрузки определяется значением registrationFlow в конфигурационном файле: DEFINED_PROFILE – загрузка по указанному в конфигурации пути (по умолчанию); DATAMART_REQUEST – запрос к Витрине через топик <префикс>.profile.rq
	5	Витрина данных передаёт: либо профиль Витрины через топик <префикс>.profile.rs либо сообщение об ошибке в топик <префикс>.profile.err
	6	Агент, получивший запрос от Витрины: уведомляет Ядро ПОДД СМЭВ о регистрации профиля новой Витрины, передаёт в Ядро ПОДД СМЭВ профиль Витрины ожидает подтверждения регистрации от Ядра ПОДД СМЭВ
	7	Ядро ПОДДСМЭВ : осуществляет регистрацию
	8	Направляет в Агент подтверждение регистрации Витрины. При успешном выполнении всех регистрационных операций, либо если данная Витрина уже зарегистрирована возвращается статус «успех», в противном случае «не успех».
Действия после успешной Регистрации	9	Агент (при запуске) вычитывает метаданные Витрин из Ядра ПОДД СМЭВ через специальный топик. Чтение метаданных не препятствует запуску, то есть в процессе чтения Агент уже может принимать запросы. Обновление метаданных производится при каждом перезапуске Агента
Действия после не успешной Регистрации	10	Агент завершает работу с ошибкой

2.2.2.2. Регистрация на основе сообщений Витрин

Только для Поставщика.

Таблица 2.5 содержит описание процесса регистрации Витрины, схема регистрации на основе сообщения от Витрины приведена на Рисунок - 2.1.

Таблица 2.5 Процесс регистрации Витрины
Процесс	Шаг	Описание
Инициация регистрации	1	Витрина данных направляет в Агент СМЭВ4 сообщение с регистрационными данными в общий топик Kafka `datamart.signal` предназначенный для получения запросов на регистрацию от всех Витрин. При отправке запроса на регистрацию Витрина должна обеспечить подписку на топик `signal`
Регистрация	2	Агент создаёт необходимые для работы с новой Витриной данных топики в соответствии с Таблица 2.3.
	3	Агент запрашивает у Витрины профиль через топик `profile.rq`.
	4	Агент получает: либо профиль Витрины через топик `profile.rs` либо сообщение об ошибке в топик `profile.err`
	5	Агент: уведомляет Ядро ПОДД СМЭВ о регистрации профиля новой Витрины, передаёт в Ядро ПОДД СМЭВ профиль Витрины, ожидает подтверждения регистрации от Ядра ПОДД.
	6	Агент получает подтверждение регистрации профиля Витрины от Ядра ПОДД СМЭВ. При успешном выполнении всех регистрационных операций, либо если данная Витрина уже зарегистрирована возвращается статус «успех», в противном случае «не успех».
	7	Агент направляет Витрине сообщение о статусе регистрации.
	8	В случае неуспешной регистрации Агент удаляет созданные на шаге 2 топики в Kafka.
Действия после успешной Регистрации	9	Агент выполняет запрос к Ядру ПОДД СМЭВ за актуальной информацией о зарегистрированных Витринах (метаданные Витрины и иные данные, необходимые для корректной работы) [24] и обновляет по полученным данным хранимую локально сводную информацию. Агент завершает процедуру запуска только после получения актуальных данных.
Действия после неуспешной Регистрации	10	В случае ошибок, таймаутов и сбоев, инициация повторной регистрации обеспечивается Витриной.

Рисунок - 2.1 Процесс регистрации Витрины данных на основе сообщения от Витрины данных

2.3. Протокол взаимодействия Агента СМЭВ4 и ИС Потребителя данных

Для обеспечения доступности данных Агент СМЭВ4 предоставляет:

REST-интерфейс для выполнения запросов к Витринам Поставщиков данных (Раздел 2.3.1 данного документа);
REST-интерфейс для выполнения запросов к REST-сервису ИС Ответчика (Раздел 2.3.2 документа);
JDBC-интерфейс для выполнения запросов к Витринам Поставщиков данных (Раздел 2.3.3 данного документа).

2.3.1. REST-интерфейс Агента СМЭВ4 для SQL-запросов

В Агенте СМЭВ4 реализована поддержка REST-интерфейса для выполнения запросов к Витринам Поставщиков данных.

URL-адрес для выполнения обращений к REST-интерфейсу имеет следующий формат: http://<адрес>:<порт>/query, где:

<адрес> – IP-адрес Агента СМЭВ4;
<порт> – порт, на котором развернут REST-интерфейс в соответствии с «Руководством администратора Агента СМЭВ4» [25].

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

Результат выполнения SQL-запроса передается в теле HTTP-ответа в виде JSON-строки. Файлы, передаваемые в составе результата выполнения SQL-запроса, включаются в JSON как строковые атрибуты, кодирующие содержимое передаваемого файла с использованием Base64.

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

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

в синхронном режиме (см. Раздел 2.3.1.1);
в асинхронном режиме (см. Раздел 2.3.1.2);
на получение BLOB по ссылке (см. Раздел 2.3.1.3).

2.3.1.1. Выполнение SQL-запросов (синхронный режим)

В синхронном режиме получение результата осуществляется путем выполнения одного HTTP-запроса от ИС Потребителя к Агенту СМЭВ4.

В рамках HTTP-запроса (метод POST) передается SQL-запрос, в ответе возвращается результат выполнения SQL-запроса.

2.3.1.1.1. HTTP-запрос на вызов Регламентированного SQL-запроса

Таблица 2.6 HTTP-запрос на вызов Регламентированного SQL-запроса
№	Параметр	Тип	Обязательность	Описание
1	Тип запроса (Method)		Да	POST
2	Путь (Path)		Да	<IP:port>/regulated-query
header
1	Content-Type	string	Да	application/x-www-form-urlencoded; charset=utf-8
2	Accept-version	string	Да	Основная (major) часть версии (сейчас 1)
3	ClientRequestID	string	Нет	Клиентский идентификатор
body
1	priority	string	Да	Приоритет запроса. Варианты: NORMAL; HIGH
2	timeout	string	Нет	Предельное время ожидания выполнения запроса. Запросы без указания данного параметра использовать не рекомендуется, следует указать значение, равное времени ожидания ответа на ИС Потребителя. Максимальное значение 24 часа В случае отсутствия параметра в запросе таймаут имеет значение по умолчанию 1 час
3	datamart	string	Нет	Витрина Поставщика данных, к которой производится обращение
4	mnemonic	string	Нет	Мнемоника РЗ, к которому производится обращение
5	majorVersion	int	Нет Если не указана majorVersion и minorVersion, обращение к актуальной версии	Версия РЗ, к которому производится обращение
6	majorVersion	int	Нет Если не указана majorVersion и minorVersion, обращение к актуальной версии Если не указана minorVersion и указанана majorVersion, обращение к последней версии в рамках majorVersion	Версия РЗ, к которому производится обращение
7	params	array	Нет	Параметры запроса
7.1	type	string	Да	Тип параметра
7.2	value	string	Да	Значение параметра

Пример запроса:

POST «https://10.81.4.30:29354/regulated-query»
Accept-Version:1
Content-Type:application/x-www-form-urlencoded; encoding=utf-8

priority:NORMAL
timeout:60
datamart: fias
mnemonic: addrobj_view
majorVersion: 1
minorVersion: 0

2.3.1.1.2. HTTP-запрос на вызов Регламентированного SQL-запроса (с возможностью использования надстроек)

Примечание

Использование не рекомендуется. Возможность указания надстроек (дополнительных условий фильтрации и операций над получаемыми данными, например, order by, limit, where и т.д.) при вызове регламентированного SQL-запроса ограничена и в будущем будет отключена. Данный метод останется доступным только для выполнения произвольных SQL-запросов к собственным Витринам данных для тестирования.

Таблица 2.7 HTTP-запрос на вызов Регламентированного SQL-запроса (с возможностью использования надстроек)
№	Параметр	Тип	Обязательность	Описание
1	Тип запроса (Method)		Да	POST
2	Путь (Path)		Да	<IP:port>/query
header
1	Content-Type	string	Да	application/x-www-form-urlencoded; charset=utf-8
2	Accept-version	string	Да	Основная (major) часть версии (сейчас 1)
3	ClientRequestID	string	Нет	Клиентский идентификатор
query
1	async	boolean	Нет	Для синхронного режима выполнения запроса параметр должен отсутствовать или иметь значение False
body
1	priority	string	Да	Приоритет запроса. Варианты: NORMAL; HIGH
2	timeout	string	Нет	Предельное время ожидания выполнения запроса. Запросы без указания данного параметра использовать не рекомендуется, следует указать значение, равное времени ожидания ответа на ИС Потребителя. Максимальное значение 24 часа В случае отсутствия параметра в запросе таймаут имеет значение по умолчанию 1 час
3	sql	string	Да	Текст SQL-запроса к Витринам Поставщиков данных
4	params	array	Нет	Параметры запроса
4.1	type	string	Да	Тип параметра
4.2	value	string	Да	Значение параметра
5	maxRows	string	Нет	Максимальное количество возвращаемых записей таблицы ответа. Если не задан, возвращаются все записи.

Пример запроса:

POST «https://10.81.4.30:29354/query?async=false»

Accept-Version:1
Content-Type:application/x-www-form-urlencoded; encoding=utf-8

priority:NORMAL
timeout:60
sql:SELECT ao.oktmo, o.name, o.kod from fias.addrobj ao LEFT JOIN oktmo.oktmo o on ao.oktmo = o.kod2 WHERE ao.offname= ? AND o.regionid = ?
params:{ “type”: “STRING”, “value”:”Москва”},{ “type”: “INTEGER”, “value”: “18”}

2.3.1.1.3. Ответ на HTTP-запрос

Допустимые коды возврата:

200 – ок;
400 – ошибка в запросе, информация об ошибке содержится в параметре «error»;
403 – нет полномочий на выполнение запроса, в том числе при блокировке полномочий на стороне Поставщика (с отображением соответствующего текста ошибки);
406 – неподдерживаемая версия протокола (после внедрения поддержки обратной совместимости возвращается только для несуществующих версий);
429 – ИС УВ временно заблокирована в связи с превышением лимитов;
500 – системная ошибка (в связи в принятыми ограничениями по доступности код 500 предполагается только при сбое Агента СМЭВ4);
503 – система временно недоступна, возможно повторить запрос через 50 мс.

Таблица 2.8 Параметры ответа с кодом возврата 200
№	Параметр	Тип	Обязательность	Описание
1	responseCode	numeric	Да	Код возврата (HTTP-код)
header
1	Content-Type	string	Да	application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8
2	ClientRequestID	string	Нет	Клиентский идентификатор
3	Version	string	Да	Версия протокола (на текущий момент 1.0)
body
1	created_at	dateTime	Да	Время формирования ответа
2	query_id	string	Да	Идентификатор запроса
3	rows	array	Нет	Массив записей таблицы ответа (в случае если результат выполнения запроса в виде таблицы). При задании параметра «maxRows» ограничивается его значением
3.1		array	Да	Массив значений. Возможным значением может быть содержимое файла, закодированное в формате BASE64
4	meta	array	Да	Список полей результата
4.1	name	string	Да	Имя поля
4.2	type	string	Да	Тип поля

Пример ответа с кодом возврата 200:

HTTP/1.1 200 OK
{
“created_at”: “2017-12-15T07:36:-03Z”,
“query_id”: “c005a0e7-0d26-4ce0-a1fa-10c8bdf4dfc5”,
    “meta”: [
    {
        “name”: “count”,
        “type”: “INTEGER”
    }
],
«rows»: [
        [
            «4994»
        ]
]
}

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

HTTP/1.1 200 OK
{
    "created_at": "2023-02-21T14:15:46Z",
    "query_id": "1edb1f23-90c1-6b75-bd1a-914f21e14802",
    "meta": [
        {
            "name": "id",
            "type": "INTEGER"
        },
        {
            "name": "name",
            "type": "STRING"
        },
        {
            "name": "logo_thumb",
            "type": "BINARY"
        }
    ],
    "rows": [
При возврате BLOB:
        [
            "2",
            "scala",
            "R0lGODlhIAAPAPUAADcNCTgNCW0ZEW8aEnMbEnYcE3wdFH0dFIAeFIEeFIMfFYUfFZAiF5IiF5MiF5okGKEmGaYnGqsoG7YrHbgrHb0sHsUuH8cvH8gvINExIdIxIdcyItozItszItszI940I980I+A0I+A1I+E1I+E1JAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACH5BAEAACUAIf8LSW1hZ2VNYWdpY2sNZ2FtbWE9MC40NTQ1NQAsAAAAACAADwAABoDAknBILBqPSOInyTR+ntBlc1r6gECi0WcjDASoyI0GQ4EoCt3SN7k+MggCwiJySQ+9X7y66yV6MhocICQjfHlGendEISOEHxkVRImGfWqVQhYTEQ0GAwclAJR8lnmHQw8ICQ4SFx2Gr3h6sUMhVyMjIFJgSVFPu02+v8LDxMUlQQA7"
        ],
При возврате ссылки на BLOB:
        [
            "17",
            "test",
            "link://c005a0e7-0d26-4ce0-a1fa-10c8bdf4dfc5"
        ]
    ]

}

Таблица 2.9 Параметры ответа с кодом возврата, отличным от 200
№	Параметр	Тип	Обязательность	Описание
1	responseCode	numeric	Да	Код возврата (HTTP-код)
header
1	Content-Type	string	Да	application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8
2	ClientRequestID	string	Нет	Клиентский идентификатор
3	Version	string	Да	Версия протокола (на текущий момент 1.0)
body
1	created_at	dateTime	Да	Время формирования ответа
2	query_id	string	Да	Идентификатор запроса
3	error	string	Нет	Текст ошибки

Пример ответа с кодом возврата, отличным от 200:

HTTP/1.1 429 Too Many Requests

{
    “created_at”: “2021-09-10T15:23:36Z”,
    “query_id”: “1ec124b1-1aa6-66d6-9d40-f55438428f56”,
    “error”: “RuntimeException: Ошибка во входящем потоке : CustomRSocketException: LIMIT_EXCEEDED: Запросы к Ядру ПОДД временно заблокированы до September 10, 2021 3:24:35 PM UTC, код причины блокировки=2, подробности: ‘Превышен лимит по количеству запросов lockId=fe462d49-3c5a-4350-8bf6-da155225c52f, userId=e92e3fd4-28d9-48e5-8079-e377b676c9b4 reqCountLimit=10, QueriesStatistic(totalSent=10, totalBytes=2870, totalRows=0, requestIds={1ec124b0-bce0-613b-9d40-c7c6585b14bc=287B, 1ec124b0-caa5-677c-9d40-ebd5d2c0409b=287B, 1ec124b0-d464-695d-9d40-bbafa86207b7=287B, 1ec124b0-dcd5-63ae-9d40-171562fc3a47=287B, 1ec124b0-e493-6a6f-9d40-174dab9e6065=287B, 1ec124b0-ec15-60a0-9d40-f300de6b4e34=287B, 1ec124b0-f6de-6451-9d40-51926f0b5d81=287B, 1ec124b0-fe95-65e2-9d40-e5e27f87babb=287B, 1ec124b1-0581-6d43-9d40-6301af351da7=287B, 1ec124b1-0c9c-6ad4-9d40-dfc04d23e0bc=287B})’.”
}

2.3.1.2. Выполнение SQL-запросов (асинхронный режим)

В асинхронном режиме получение результата осуществляется путем выполнения двух HTTP-запросов от ИС Потребителя к Агенту СМЭВ4:

В рамках первого HTTP-запроса (метод POST) передается SQL-запрос, в ответе возвращается идентификатор запроса.
В рамках второго HTTP-запроса (метод GET) передается ранее полученный идентификатор запроса, в ответе возвращается результат выполнения SQL-запроса. Получение результата по указанному идентификатору возможно только один раз.

2.3.1.2.1. HTTP-запрос передачи SQL-запроса в Агент СМЭВ4 (метод POST)

2.3.1.2.1.1. HTTP-запрос на вызов Регламентированного SQL-запроса

Таблица 2.10 HTTP-запрос на вызов Регламентированного SQL-запроса
№	Параметр	Тип	Обязательность	Описание
1	Тип запроса (Method)		Да	POST
2	Путь (Path)		Да	<IP:port>/regulated-query/async
header
1	Content-Type	string	Да	application/x-www-form-urlencoded; charset=utf-8
2	Accept-version	string	Да	Основная (major) часть версии (сейчас 1)
3	ClientRequestID	string	Нет	Клиентский идентификатор
body
1	priority	string	Да	Приоритет запроса. Варианты: NORMAL; HIGH
2	timeout	string	Нет	Предельное время ожидания выполнения запроса. Запросы без указания данного параметра использовать не рекомендуется, следует указать значение, равное времени ожидания ответа на ИС Потребителя. Максимальное значение 24 часа В случае отсутствия параметра в запросе таймаут имеет значение по умолчанию 1 час
3	datamart	string	Нет	Витрина Поставщика данных, к которой производится обращение
4	mnemonic	string	Нет	Мнемоника РЗ, к которому производится обращение
5	majorVersion	int	Нет Если не указана majorVersion и minorVersion, обращение к актуальной версии	Версия РЗ, к которому производится обращение
6	majorVersion	int	Нет Если не указана majorVersion и minorVersion, обращение к актуальной версии Если не указана minorVersion и указанана majorVersion, обращение к последней версии в рамках majorVersion	Версия РЗ, к которому производится обращение
7	params	array	Нет	Параметры запроса
7.1	type	string	Да	Тип параметра
7.2	value	string	Да	Значение параметра

Пример запроса:

POST «https://10.81.4.30:29354/regulated-query/async»
Accept-Version:1
Content-Type:application/x-www-form-urlencoded; encoding=utf-8

priority:NORMAL
timeout:60
datamart: fias
mnemonic: addrobj_view
majorVersion: 1
minorVersion: 0
params:{ “type”: “STRING”, “value”:”Москва”},{ “type”: “INTEGER”, “value”: “18”}

2.3.1.2.1.2. HTTP-запрос на вызов Регламентированного SQL-запроса (с возможностью использования надстроек)

Примечание

Использование не рекомендуется. Возможность указания надстроек (дополнительных условий фильтрации и операций над получаемыми данными, например, order by, limit, where и т.д.) при вызове регламентированного SQL-запроса ограничена и в будущем будет отключена. Данный метод останется доступным только для выполнения произвольных SQL-запросов к собственным Витринам данных для тестирования.

Таблица 2.11 HTTP-запрос на вызов Регламентированного SQL-запроса (с возможностью использования надстроек)
№	Параметр	Тип	Обязательность	Описание
1	Тип запроса (Method)		Да	POST
2	Путь (Path)		Да	<IP:port>/query
header
1	Content-Type	string	Да	application/x-www-form-urlencoded; charset=utf-8
2	Accept-version	string	Да	Основная (major) часть версии (сейчас 1)
3	ClientRequestID	string	Нет	Клиентский идентификатор
query
1	async	boolean	Да	Для асинхронного режима выполнения запроса параметр должен присутствовать и иметь значение True
body
1	priority	string	Да	Приоритет запроса. Варианты: NORMAL; HIGH
2	timeout	string	Нет	Предельное время ожидания выполнения запроса. Запросы без указания данного параметра использовать не рекомендуется, следует указать значение, равное времени ожидания ответа на ИС Потребителя. Максимальное значение 24 часа В случае отсутствия параметра в запросе таймаут имеет значение по умолчанию 1 час
3	sql	string	Да	Текст SQL-запроса
4	params	array	Нет	Параметры запроса
4.1	type	string	Да	Тип параметра
4.2	value	string	Да	Значение параметра
5	maxRows	string	Нет	Максимальное количество возвращаемых записей таблицы ответа. Если не задан, возвращаются все записи.

Пример запроса:

POST «https://10.81.4.30:29354/query?async=true»

Accept-Version:1
Content-Type:application/x-www-form-urlencoded; encoding=utf-8

priority:NORMAL
timeout:60
sql:SELECT ao.oktmo, o.name, o.kod from fias.addrobj ao LEFT JOIN oktmo.oktmo o on ao.oktmo = o.kod2 WHERE ao.offname= ? AND o.regionid = ?
params:{ “type”: “STRING”, “value”:”Москва”},{ “type”: “INTEGER”, “value”: “18”}

2.3.1.2.1.3. Ответ на HTTP-запрос

Допустимые коды возврата:

201 – запрос создан;
400 – ошибка в запросе, информация об ошибке содержится в параметре «error»;
403 – нет полномочий на выполнение запроса, в том числе при блокировке полномочий на стороне Поставщика (с отображением соответствующего текста ошибки);
429 – ИС УВ временно заблокирована в связи с превышением лимитов;
503 – система временно недоступна, возможно повторить запрос через 50 мс.

Таблица 2.12 Параметры ответа с кодом возврата 201:
№	Параметр	Тип	Обязательность	Описание
1	responseCode	numeric	Да	Код возврата (HTTP-код)
header
1	Content-Type	string	Да	application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8
2	Location	string	Да	Временная ссылка на скачивание результата выполнения запроса
3	ClientRequestID	string	Нет	Клиентский идентификатор
4	Version	string	Да	Версия протокола (на текущий момент 1.0)
body
1	id	string	Да	Уникальный идентификатор SQL-запроса
2	deadline	string	Да	Время, до которого доступен результат выполнения запроса. Время хранения результата составляет 24 часа

Пример ответа с кодом возврата 201:

HTTP/1.1 201 Created
{
    “id”: “a2f05175-d5bc-47d4-9b88-17930630683e”,
    «deadline»: «2021-05-13T06:33:43Z»
}

Таблица 2.13 Параметры ответа с кодом возврата 400:
№	Параметр	Тип	Обязательность	Описание
1	responseCode	numeric	Да	Код возврата (HTTP-код)
header
1	Content-Type	string	Да	application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8
2	Version	string	Да	Версия протокола (на текущий момент 1.0)
body
1	error	string	Нет	Текст ошибки

2.3.1.2.2. HTTP-запрос получения результата, ранее переданного в Агент СМЭВ4 асинхронного SQL-запроса (метод GET)

2.3.1.2.2.1. HTTP-запрос при вызове исходного запроса

Таблица 2.14 HTTP-запрос при вызове исходного запроса
№	Параметр	Тип	Обязательность	Описание
1	Тип запроса (Method)		Да	GET
2	Путь (Path)		Да	<IP:port>/regulated-query
query
1	query_id	string	Да	Уникальный идентификатор SQL-запроса
header
1	Accept	string	Да	application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8
2	Accept-version	string	Да	Основная (major) часть версии (сейчас 1)
3	ClientRequestID	string	Нет	Клиентский идентификатор

Пример запроса:

GET “https://10.81.4.30:29354/ regulated-query/c005a0e7-0d26-4ce0-a1fa-10c8bdf4dfc5”

2.3.1.2.2.2. HTTP-запрос при вызове исходного запроса (с возможностью использования надстроек)

Таблица 2.15 HTTP-запрос при вызове исходного запроса (с возможностью использования надстроек)
№	Параметр	Тип	Обязательность	Описание
1	Тип запроса (Method)		Да	GET
2	Путь (Path)		Да	<IP:port>/query
header
1	Accept	string	Да	application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8
2	Accept-version	string	Да	Основная (major) часть версии (сейчас 1)
3	ClientRequestID	string	Нет	Клиентский идентификатор
query
1	query_id	string	Да	Уникальный идентификатор SQL-запроса

Пример запроса:

GET “https://10.81.4.30:29354/query/c005a0e7-0d26-4ce0-a1fa-10c8bdf4dfc5”

2.3.1.2.2.3. Ответ на HTTP-запрос

Допустимые коды возврата:

200 – ок;
202 – результат по заданному идентификатору SQL-запроса еще не поступил;
400 – ошибка в запросе, информация об ошибке содержится в параметре «error»;
403 – нет полномочий на выполнение запроса, в том числе при блокировке полномочий на стороне Поставщика (с отображением соответствующего текста ошибки);
404 – Результат по заданному идентификатору SQL-запроса не найден;
406 – неподдерживаемая версия протокола (после внедрения поддержки обратной совместимости возвращается только для несуществующих версий);
429 – ИС УВ временно заблокирована в связи с превышением лимитов;
500 – системная ошибка (в связи в принятыми ограничениями по доступности код 500 предполагается только при сбое Агента СМЭВ4);
503 – система временно недоступна, возможно повторить запрос через 50 мс;

Таблица 2.16 Параметры ответа с кодом возврата 200:
№	Параметр	Тип	Обязательность	Описание
1	responseCode	numeric	Да	Код возврата (HTTP-код)
header
1	Content-Type	string	Да	application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8
2	ClientRequestID	string	Нет	Клиентский идентификатор
3	Version	string	Да	Версия протокола (на текущий момент 1.0)
body
1	created_at	dateTime	Да	Время формирования ответа. Время, с которого ответ доступен для получения по запросу
2	query_id	string	Да	Идентификатор запроса
3	rows	array	Нет	Массив записей таблицы ответа (в случае если результат выполнения запроса в виде таблицы). При задании параметра «maxRows» ограничивается его значением
3.1		array	Да	Массив значений. Возможным значением может быть содержимое файла, закодированное в формате BASE64
4	meta	array	Да	Список полей результата
4.1	name	string	Да	Имя поля
4.2	type	string	Да	Тип поля

Пример ответа с кодом возврата 200:

HTTP/1.1 200 OK
{
“created_at”: “2017-12-15T07:36:03Z”,
“query_id”: “c005a0e7-0d26-4ce0-a1fa-10c8bdf4dfc5”,
    “meta”: [
    {
        “name”: “count”,
        “type”: “INTEGER”
    }
],
«rows»: [
        [
            «4994»
        ]
]
}

Таблица 2.17 Параметры ответа с кодом возврата, отличным от 200:
№	Параметр	Тип	Обязательность	Описание
1	responseCode	numeric	Да	Код возврата (HTTP-код)
header
1	Content-Type	string	Да	application/vnd.ru.rtlabs.podd.agent+json; version=1.0; charset=utf-8
2	ClientRequestID	string	Нет	Клиентский идентификатор
body
1	query_id	string	Нет	Идентификатор запроса
2	created_at	dateTime	Нет	Время формирования ответа – время, с которого ответ доступен для получения по запросу
3	error	string	Нет	Текст ошибки

2.3.1.3. Выполнение запроса с табличным параметром

Может быть выполнен как в синхронном, так и в асинхронном режиме. Ответ соответствует способу вызова.

2.3.1.3.1. HTTP-запрос с табличным параметром на вызов запроса

Таблица 2.18 HTTP-запрос с табличным параметром на вызов запроса
№	Параметр	Тип	Обязательность	Описание
1	Тип запроса (Method)		Да	POST
2	Путь (Path)		Да	<IP:port>/regulated-query – для синхронного вызова <IP:port>/regulated-query/async – для асинхронного вызова
header
1	Content-Type	string	Да	multipart/form-data;
2	Connection	string	Да	keep-alive
3	Accept-version	string	Да	Основная (major) часть версии (сейчас 1)
4	ClientRequestID	string	Нет	Клиентский идентификатор
body
1	priority	string	Да	Приоритет запроса. Варианты: NORMAL; HIGH
2	timeout	string	Нет	Предельное время ожидания выполнения запроса. В случае отсутствия параметра в запросе таймаут не выставляется
3	datamart	string	Нет	Витрина Поставщика данных, к которой производится обращение
4	mnemonic	string	Да	Мнемоника РЗ, к которому производится обращение
5	majorVersion	int	Нет Обязательное указание вместе с minorVersion. Если не указана, обращение к актуальной версии	Версия РЗ, к которому производится обращение
6	majorVersion	int	Нет Обязательное указание вместе с majorVersion. Если не указана, обращение к актуальной версии	Версия РЗ, к которому производится обращение
7	tableParams	array	Да	Описание передаваемого файла с данными для табличного параметра
7.1	name	string	Да	Наименование табличного параметра, соответствующее указанному в SQL-выражении в формате `@<name>`
7.2	columns	array	Да	Перечень наименований столбцов и их типов, содержащихся в файле с данными для табличного параметра
7.2.1	name	string	Да	Наименование столбца
7.2.2	type	string	Да	Тип столбца
8	<name>		Да	Файл с данными для табличного параметра. Имя параметра соответствует наименованию табличного параметра
file
8.1		файл в формате CSV	Да	Файл в формате CSV (поддерживаемый формат), передаваемый в параметре запроса
boundary
1	Content-Disposition	string	Да	form-data; name=”table1”; filename=”table1.csv”

2.3.1.3.2. HTTP-запрос с табличным параметром на вызов запроса (с возможностью использования надстроек)

Примечание

Использование не рекомендуется. Возможность указания надстроек (дополнительных условий фильтрации и операций над получаемыми данными, например, order by, limit, where и т.д.) при вызове регламентированного SQL-запроса ограничена и в будущем будет отключена. Данный метод останется доступным только для выполнения произвольных SQL-запросов к собственным Витринам данных для тестирования.

Таблица 2.19 HTTP-запрос с табличным параметром на вызов запроса (с возможностью использования надстроек)
№	Параметр	Тип	Обязательность	Описание
1	Тип запроса (Method)		Да	POST
2	Путь (Path)		Да	<IP:port>/query
query
1	async	boolean	Нет	Для синхронного режима выполнения запроса параметр должен отсутствовать или иметь значение False Для асинхронного режима выполнения запроса параметр должен иметь значение True
header
1	Content-Type	string	Да	multipart/form-data;
2	Connection	string	Да	keep-alive
3	Keep-Alive:	string	Да	300
4	ClientRequestID	string	Нет	Клиентский идентификатор
boundary
1	Content-Disposition			application/json name=request
2	Content-Type	string	Да	application/json; charset=utf-8
3	Accept-version	string	Да	Основная (major) часть версии (сейчас 1)
json
1	priority	string	Да	Приоритет запроса. Варианты: NORMAL; HIGH
2	timeout	string	Нет	Предельное время ожидания выполнения запроса в секундах В случае отсутствия параметра в запросе таймаут не выставляется
3	sql	string	Да	Текст SQL-запроса
4	tableParams	array	Да	Описание передаваемого файла с данными для табличного параметра
4.1	name	string	Да	Наименование табличного параметра, соответствующее указанному в SQL-выражении в формате `@<name>`
4.2	columns	array	Да	Перечень наименований столбцов и их типов, содержащихся в файле с данными для табличного параметра
4.2.1	name	string	Да	Наименование столбца
4.2.2	type	string	Да	Тип столбца
5	<name>		Да	Файл с данными для табличного параметра. Имя параметра соответствует наименованию табличного параметра
file
5.1		файл в формате CSV	Да	Файл в формате CSV (поддерживаемый формат), передаваемый в параметре запроса
boundary
1	Content-Disposition	string	Да	form-data; name=”table1”; filename=”table1.csv”

Пример запроса приведен в Раздел 3.3.4.1 настоящего документа.

2.3.1.4. Выполнение запроса на получение BLOB по ссылке

2.3.1.4.1. HTTP-запрос (вариант 1)

Таблица 2.20 HTTP-запрос (вариант 1)
№	Параметр	Тип	Обязательность	Значение / описание
1	Тип запроса (Method)		Да	GET
2	Путь (Path)		Да	<IP:port>/regulated-query/blob
query
1	link	string	Да	Ссылка на вырузку BLOB
header
1	Accept	string	Да	application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8
2	Accept-version	string	Да	Основная (major) часть версии (сейчас 1)
3	ClientRequestID	string	Нет	Клиентский идентификатор в формате UUID. Потребителю рекомендуется в запросе BLOB по ссылке указать тот же сквозной идентификатор, что и при исходном запросе. Ответственность за соответствие идентификаторов лежит на Потребителе.

Пример запроса:

GET “https://10.81.4.30:29354/regulated-query/blob/c005a0e7-0d26-4ce0-a1fa-10c8bdf4dfc5”

2.3.1.4.2. HTTP-запрос (вариант 2)

Таблица 2.21 HTTP-запрос (вариант 2)
№	Параметр	Тип	Обязательность	Значение / описание
1	Тип запроса (Method)		Да	GET
2	Путь (Path)		Да	<IP:port>/query/blob
query
1	link	string	Да	Ссылка на вырузку BLOB
header
1	Accept	string	Да	application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8
2	Accept-version	string	Да	Основная (major) часть версии (сейчас 1)
3	ClientRequestID	string	Нет	Клиентский идентификатор в формате UUID. Потребителю рекомендуется в запросе BLOB по ссылке указать тот же сквозной идентификатор, что и при исходном запросе. Ответственность за соответствие идентификаторов лежит на Потребителе.

Пример запроса:

GET “https://10.81.4.30:29354/query/blob/c005a0e7-0d26-4ce0-a1fa-10c8bdf4dfc5”

2.3.1.4.3. Ответ на HTTP-запрос

Допустимые коды возврата:

200 – ок;
400 – ошибка в запросе, информация об ошибке содержится в параметре «error»;
403 – нет полномочий на выполнение запроса, в том числе при блокировке полномочий на стороне Поставщика (с отображением соответствующего текста ошибки);
404 – получен запрос на обращение к недоступной ссылке на BLOB (истекло время жизни);
406 – неподдерживаемая версия протокола (после внедрения поддержки обратной совместимости возвращается только для несуществующих версий);
429 – ИС УВ временно заблокирована в связи с превышением лимитов;
500 – системная ошибка (в связи в принятыми ограничениями по доступности код 500 предполагается только при сбое Агента СМЭВ4);
503 – система временно недоступна, возможно повторить запрос через 50 мс.

Параметры ответа с кодом возврата 200:

Таблица 2.22 Параметры ответа с кодом возврата 200:
№	Параметр	Тип	Обязательность	Значение / описание
1	responseCode	numeric	Да	Код возврата (HTTP-код)
header
1	Content-Type	string	Да	application/octet-stream
2	Content-Length		Да	Размер тела объекта в байтах
3	ClientRequestID	string	Нет	Клиентский идентификатор
4	Version	string	Да	Версия протокола (на текущий момент 1.0)
body
1			Да	Содержимое полученного по ссылке файла (в виде массива байт)

Пример ответа с кодом возврата 200:

HTTP/1.1 200 OK
<Содержимое полученного по ссылке файла (в виде массива байт)>

Таблица 2.23 Параметры ответа с кодом возврата, отличным от 200:
№	Параметр	Тип	Обязательность	Описание
1	responseCode	numeric	Да	Код возврата (HTTP-код)
header
1	Content-Type	string	Да	application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8
2	Version	string	Да	Версия протокола (на текущий момент 1.0)
body
1	created_at	dateTime	Нет	Время формирования ответа
2	query_id	string	Нет	Идентификатор запроса
3	error	string	Нет	Текст ошибки

Пример ответа с кодом возврата, отличным от 200:

HTTP/1.1 429 Too Many Requests
{
    “created_at”: “2021-09-10T15:23:36Z”,
    “query_id”: “1ec124b1-1aa6-66d6-9d40-f55438428f56”,
    “error”: “RuntimeException: Ошибка во входящем потоке : CustomRSocketException: LIMIT_EXCEEDED: Запросы к Ядру ПОДД временно заблокированы до September 10, 2021 3:24:35 PM UTC, код причины блокировки=<>, подробности: ‘Превышен лимит по количеству скачиваний по ссылке... ”
}

2.3.2. REST-интерфейс Агента СМЭВ4 для запросов к REST-сервису ИС Ответчика

2.3.2.1. HTTP-запрос

Все запросы выполняются в синхронном режиме в соответствии с загруженной в ПОДД СМЭВ спецификацией OpenApi REST-сервиса ИС Ответчика. Примеры спецификаций OpenAPI REST-сервисов ИС Ответчиков приведены в Раздел 1.5.5.

Получение результата осуществляется путем выполнения HTTP-запроса от ИС Инициатора к Агенту Ответчика. При выполнении запроса могут быть использованы все типы HTTP-методов (POST, GET, PUT и DELETE), выполняющих CRUD-операции (Create/Read/Update/Delete), которые используются в спецификациях OpenAPI, описывающих REST-сервисы ИС Ответчиков.

Информация о формировании запроса приведена в Раздел 3.3.6.

Клиентский идентификатор передаётся в опциональном заголовке ClientRequestID (тип string).

2.3.2.2. Ответ на HTTP-запрос

Ответ на запрос включает код возврата (статус выполнения операции) и, в зависимости от запрошенного метода, тело ответа, содержащее запрошенные данные и/или дополнительную информацию о результате выполнения операции, в соответствии с загруженной в ПОДД спецификацией OpenAPI REST-сервиса ИС Ответчика.

Таблица 2.24 содержит коды возврата ПОДД при ошибках выполнения запроса к REST-сервису ИС Ответчика.

Таблица 2.24 Коды возврата ПОДД
№	Код возврата	Пример причины ошибки
1	500 Internal Server Error	ошибка пересылки сообщений между сервисами; непредвиденная ошибка
2	401 Unauthorized	Ошибка проверки подписи
3	404 Not found	Спецификация OpenAPI REST-сервиса ИС Ответчика, к которой обращается запрос, не зарегистрирована в ПОДД
4	403 Forbidden	Нет прав на выполнение запроса к зарегистрированной в ПОДД спецификация OpenAPI REST-сервиса ИС Ответчика
5	400 Bad request	Запрос не соответствует зарегистрированной в ПОДД спецификации OpenAPI REST-сервиса ИС Ответчика
6	429 Too many requests	ИС УВ временно заблокирована в связи с превышением лимитов. Может возвращаться при использовании механизма с возможностью отправки большого запроса
7	503 Service unavailable	Oтветчик ограничил очередь запросов в клиенте. Может возвращаться при использовании механизма без возможности отправки большого запроса

2.3.3. JDBC-интерфейс Агента СМЭВ4 для SQL-запросов

Агент СМЭВ4 поддерживает специализированный протокол для исполнения запросов, эталонная реализация которого представлена JDBC-драйвером.

Настройка JDBC-драйвера осуществляется с помощью передачи специализированной адресной строки: protocol://hostname:port/, где:

protocol – протокол взаимодействия – значение всегда будет «podd»;
hostname – имя сервера или его IP-адрес;
port – порт, на котором Агент Потребителя данных предоставляет интерфейс для работы протокола взаимодействия в соответствии с «Руководством администратора Агента СМЭВ4»[26].

Клиентский идентификатор опционально передаётся в тексте SQL запроса первой строкой – комментарий с атрибутом ClientRequestID (тип string).

-- ClientRequestID: <клиентский идентификатор>
CALL <мнемоника регламентированного SQL-запроса>();

2.3.3.1. Пример использования JDBC-драйвера в «Kotlin»

Для прикладного разработчика работа с JDBC драйвером PODD ничем не отличается от работы с обычным JDBC драйвером.

Особенность только в URL, которым инициализируется драйвер.

package dev.nsud.jdbc

import org.junit.jupiter.api.Test
import java.sql.Connection
import java.sql.DriverManager
import org.junit.jupiter.api.Assertions
import java.sql.SQLException

class Features {

    private getConnectionURI() {
        val host = System.getProperty("agent.host", "localhost")
        val port = System.getProperty("agent.port", "8182")
        return "jdbc:podd://$host:$port"
    }
    @Test
    fun `ожидается успешное соединение с базой данных`() {
        Assertions.assertDoesNotThrow { DriverManager.getConnection(getConnectionURI()) }
    }

    @Test
    fun `ожидается успешное исполнение запроса вида "select 1" `() {
        Assertions.assertDoesNotThrow {
            val con = DriverManager.getConnection(getConnectionURI())
            val statement = con.createStatement()
            statement.queryTimeout = 5 // таймаут на выполнение запроса - 5 секунд
            statement.setMaxRows(100) // ограничение выборки по кол-ву возвращаемых строк
            statement.executeQuery("select 1")
            val resultSet = statement.resultSet
            Assertions.assertEquals(1, resultSet.getInt(0))
        }
    }

    @Test
    fun `ожидается ошибка при исполнении запроса "select 1" `() {
        Assertions.assertDoesNotThrow {
            val con = DriverManager.getConnection(getConnectionURI())
            val statement = con.createStatement()


            try {
                statement.executeQuery("select 1")
            } catch (e: SQLException) {
                // получение кода ошибки
                Assertions.assertEquals(17089, e.errorCode)
                Assertions.assertEquals("PODD-17089: Ошибка при обработке запроса", e.message)
            }
        }
    }

    @Test
    fun `ожидается успешное получение бинарных данных `() {
        Assertions.assertDoesNotThrow {
            val expect = getExpectedBytes()
            val con = DriverManager.getConnection(getConnectionURI())
            val statement = con.createStatement()
            statement.executeQuery("select binaryColumn from datamart.table where id=1")
            val resultSet = statement.resultSet
            Assertions.assertEquals(expect, resultSet.getBlob(0))
        }
    }


    @Test
    fun `ожидается успешное применение табличных параметров `() {
        Assertions.assertDoesNotThrow {
        DriverManager.getConnection(getConnectionURI()).use { connection ->
            connection.prepareStatement("select * from @p1, @p2, oktmo.oktmo o where @p1.a = @p2.b and o.id = @p1.a").use { ps ->
                ps.queryTimeout = 10 // таймаут на выполнение запроса - 10 секунд
                ps.setMaxRows(100) // ограничение выборки по кол-ву возвращаемых строк
                ps as PoddPreparedStatement
                ps.addTableParam(
                    "p1",
                    listOf(
                        ColumnInfo("a", ColumnType.INTEGER),
                        ColumnInfo("av", ColumnType.STRING),
                    ),
                    iterator<Array<Any?>> {
                        yield(arrayOf(1, "1_1"))
                        yield(arrayOf(2, "1_2"))
                        yield(arrayOf(3, "1_3"))
                    },
                )
                ps.addTableParam(
                    "p2",
                    listOf(
                        ColumnInfo("b", ColumnType.INTEGER),
                        ColumnInfo("bv", ColumnType.STRING),
                    ),
                    iterator<Array<Any?>> {
                        yield(arrayOf(1, "2_1"))
                        yield(arrayOf(2, "2_2"))
                        yield(arrayOf(3, "2_3"))
                    },
                )

                ps.executeQuery().use { rs ->
                    (1..rs.metaData.columnCount).forEach {
                        println("${rs.metaData.getColumnName(it)}: ${rs.metaData.getColumnTypeName(it)}")
                    }
                    rs.readFully().forEach { row ->
                        println()
                        row.forEach {
                            print("$it\t")
                        }
                    }
                }
            }
        }
        }
    }

2.3.3.2. Коды возврата

Таблица 2.25 содержит допустимые коды возврата при ошибках выполнения запроса.

Таблица 2.25 Коды возврата при ошибках выполнения запроса
№	Код возврата	Описание ошибки
1	17001	Внутренняя ошибка
2	17473	Запрос не прошел проверку корректности (соответствие синтаксису)
3	17471	ИС УВ временно заблокирована в связи с превышением лимитов
4	17800	Запрос содержит указание на неподдерживаемую Витрину
5	17472	Нет полномочий на выполнение запроса
6	17510	Запрос отменен Потребителем
7	17520	Запрос отменен по таймауту
8	17404	Выполнение запроса прекращено из-за блокировки полномочий по результатам проверки на стороне Поставщика
9	17405	Выполнение запроса прекращено из-за блокировки полномочий по результатам проверки на стороне Поставщика (заблокировано по умолчанию)
10	17406	Выполнение запроса прекращено из-за блокировки по результату проверки SQL выражения на стороне Поставщика

2.4. Протокол взаимодействия Агента СМЭВ4 и Витрины Потребителя данных

Протокол коммуникации Агента СМЭВ4 и Витрины данных, расположенных в контуре Потребителя данных, устроен в виде обмена сообщениями с использованием зарезервированных топиков брокера сообщений Apache Kafka.

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

2.4.1. Перечень топиков брокера сообщений Apache Kafka

Таблица 2.26 содержит названия топиков брокера сообщений .

Таблица 2.26 Названия топиков брокера сообщений Apache Kafka
№	Топик	Публикатор	Подписчик	Передаваемый объект
Топики для обеспечения информационного обмена с использованием Рассылок
1	<префикс>.replication.in.rq	Агент	Витрина	Структура таблиц Витрины Поставщика данных
2	<префикс>.replication.in.rs	Витрина	Агент	Уведомление об успешном создании структуры данных
3	<префикс>.replication.in.err	Витрина	Агент	Уведомление об ошибке при создании структуры данных
4	<префикс>.delta.notification.in	Агент	Витрина	Уведомление о наличии новых дельт у Поставщика
5	<префикс>.command.podd	ИС Потребителя	Агент	Служебный топик для ручного перезапроса дельт
6	<префикс>.delta.in.rq	Агент	Витрина	Запрос на прием дельты
7	<префикс>.delta.in.tp	Агент	Витрина	Запрос на прием дельт по распределённой подписке
8	<префикс>.delta.in.rs	Витрина	Агент	Уведомления об успешном применении дельт из пакета
9	<префикс>.delta.in.err	Витрина	Агент	Уведомление об ошибке при применении дельт из пакета
10	<префикс>.replication.cancel.in.rq	Агент	Витрина	Идентификатора отменяемой подписки
11	<префикс>.replication.cancel.in.rs	Витрина	Агент	Результат (успешный или ошибка) отмены подписки
Топики для получения событий Витрины
12	<префикс>.scl.signal	Витрина	Агент	События Витрины для дальнейшей передачи в СЦЛ

2.5. Протокол взаимодействия Агента СМЭВ4 и ИС Ответчика

Взаимодействие Агента СМЭВ4 и REST-сервиса на стороне ИС Ответчика осуществляется в соответствии со спецификацией OpenAPI, описывающей REST-сервис ИС Ответчика и загруженной в ПОДД СМЭВ.

Для использования запросов к REST-сервису ИС Ответчика через ПОДД СМЭВ необходимо произвести настройки, указанные в «Руководстве администратора Агента СМЭВ4» [27].