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

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

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

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

Более подробная информация о порядке подключения к СМЭВ4 приведена в документе «Регламент Правила и процедуры работы в СМЭВ 4».

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

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

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

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

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

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

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

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

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

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

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

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

sql_query_openapi.json

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

<адрес> – IP-адрес Агента Потребителя СМЭВ4;
<порт> – порт, на котором развернут REST-интерфейс Агента СМЭВ4 в соответствии с «Руководством администратора Агента СМЭВ4» [3];
<path> - см. описание параметра «путь (Path)» далее по тексту.

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	minorVersion	int	Нет Если не указана majorVersion и minorVersion, обращение к актуальной версии Если не указана minorVersion и указана majorVersion, обращение к последней версии в рамках majorVersion	Версия РЗ, к которому производится обращение
7	params	array	Нет	Параметры запроса
7.1	type	string	Да	Тип параметра
7.2	value	string	Да	Значение параметра
7.3	name	string	Нет	Наименование именованного параметра. Всегда заполняется для системного параметра, для именованных параметров - опционально Если не заполняется - параметры подставляются в порядке задания в SQL-выражении РЗ Если заполняется - наименование должно быть указано для всех параметров запроса

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

curl --location --request POST 'https://localhost:8192/regulated-query' \
  --header 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
  --header 'Accept-Version: 1' \
  --header 'ClientRequestID: afd36c80-957e-11ed-87cd-0800200c9a66' \
  --data-urlencode 'priority=NORMAL' \
  --data-urlencode 'timeout=60' \
  --data-urlencode 'datamart=fias' \
  --data-urlencode 'mnemonic=addrobj_view' \
  --data-urlencode 'majorVersion=1' \
  --data-urlencode 'minorVersion=0' \
  --data-urlencode 'params={"type": "STRING", "value": "Москва", "name": "pname1"},{"type": "INTEGER", "value": "18", "name": "pname2"}'

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

Примечание

Использование не рекомендуется. Возможность указания надстроек (дополнительных условий фильтрации и операций над получаемыми данными, например, order by, limit, where и т.д.) при вызове регламентированного SQL-запроса ограничена. При наличии потребности использовать такие надстройки рекомендуется обратится к поставщику данных для добавления их в 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	Нет	Максимальное количество возвращаемых записей таблицы ответа. Если не задан, возвращаются все записи.

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

curl --location --request POST 'https://localhost:8192/query?async=false' \
  --header 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
  --header 'Accept-Version: 1' \
  --header 'ClientRequestID: afd36c80-957e-11ed-87cd-0800200c9a66' \
  --data-urlencode 'priority=NORMAL' \
  --data-urlencode 'timeout=60' \
  --data-urlencode 'sql=SELECT * from fias.addrobj_view (?, ?) \
  --data-urlencode 'params={"type": "STRING", "value": "Москва"},{"type": "INTEGER", "value": "18"}' \
  --data-urlencode 'maxRows=10'

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

Таблица 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-код) Перечень возможных кодов и путей их решения представлены в Раздел 4
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: Запросы к Ядру СМЭВ4 временно заблокированы до 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-запроса.

Примечание

При подключении Агента СМЭВ4 к Ядру СМЭВ4 через Pulsar получение результата по указанному идентификатору возможно только один раз. При использовании Rsocket - неограниченное количество раз за время хранения в Ядре. При необходимости регулировать время хранения можно с помощью параметра «timeout» запроса.

При подключении через Rsocket, когда получать результат выполнения SQL-запроса больше не требуется, настоятельно рекомендуется выполнить запрос на удаление результата выполнения запроса (метод DELETE).

2.3.1.2.1. HTTP-запрос выполнения SQL-запроса (метод 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	minorVersion	int	Нет Если не указана majorVersion и minorVersion, обращение к актуальной версии Если не указана minorVersion и указана majorVersion, обращение к последней версии в рамках majorVersion	Версия РЗ, к которому производится обращение
7	params	array	Нет	Параметры запроса
7.1	type	string	Да	Тип параметра
7.2	value	string	Да	Значение параметра
7.3	name	string	Нет	Наименование параметра

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

curl --location --request POST 'https://localhost:8192/regulated-query/async' \
  --header 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
  --header 'Accept-Version: 1' \
  --header 'ClientRequestID: afd36c80-957e-11ed-87cd-0800200c9a66' \
  --data-urlencode 'priority=NORMAL' \
  --data-urlencode 'timeout=60' \
  --data-urlencode 'datamart=fias' \
  --data-urlencode 'mnemonic=addrobj_view' \
  --data-urlencode 'majorVersion=1' \
  --data-urlencode 'minorVersion=0' \
  --data-urlencode 'params={"type": "STRING", "value": "Москва", "name": "pname1"},{"type": "INTEGER", "value": "18", "name": "pname2"}'

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	Нет	Максимальное количество возвращаемых записей таблицы ответа. Если не задан, возвращаются все записи.

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

curl --location --request POST 'https://localhost:8192/query?async=true' \
  --header 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
  --header 'Accept-Version: 1' \
  --header 'ClientRequestID: afd36c80-957e-11ed-87cd-0800200c9a66' \
  --data-urlencode 'priority=NORMAL' \
  --data-urlencode 'timeout=60' \
  --data-urlencode 'sql=SELECT * from fias.addrobj_view (?, ?) \
  --data-urlencode 'params={"type": "STRING", "value": "Москва"},{"type": "INTEGER", "value": "18"}' \
  --data-urlencode 'maxRows=10'

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

Таблица 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	Да	Время, до которого доступен результат выполнения запроса. При подключении через Rsocket определяется исходя из пользовательского таймаута или таймаута по умолчанию. При подключении через Pulsar составляет 24 часа

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

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

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

2.3.1.2.2. HTTP-запрос получения результата ранее переданного асинхронного SQL-запроса (метод GET)

2.3.1.2.2.1. HTTP-запрос

Таблица 2.14 HTTP-запрос
№	Параметр	Тип	Обязательность	Описание
1	Тип запроса (Method)		Да	GET
2	Путь (Path)		Да	<IP:port>/regulated-query <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	Нет	Клиентский идентификатор
Path Parameter
1	query_id	string	Да	Уникальный идентификатор SQL-запроса

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

curl --location --request GET 'https://localhost:8192/regulated-query/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  --header 'Accept: application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8' \
  --header 'Accept-Version: 1' \
  --header 'ClientRequestID: afd36c80-957e-11ed-87cd-0800200c9a66'

curl --location --request GET 'https://localhost:8192/query/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  --header 'Accept: application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8' \
  --header 'Accept-Version: 1' \
  --header 'ClientRequestID: afd36c80-957e-11ed-87cd-0800200c9a66'

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

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

2.3.1.2.3. HTTP-запрос на удаление результата выполнения ранее переданного асинхронного SQL-запроса (метод DELETE)

2.3.1.2.3.1. HTTP-запрос

Таблица 2.17 HTTP-запрос
№	Параметр	Тип	Обязательность	Описание
1	Тип запроса (Method)		Да	DELETE
2	Путь (Path)		Да	<IP:port>/regulated-query <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	Нет	Клиентский идентификатор
Path Parameter
1	query_id	string	Да	Уникальный идентификатор SQL-запроса

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

curl --location --request DELETE 'https://localhost:8192/regulated-query/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  --header 'Accept: application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8' \
  --header 'Accept-Version: 1'

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

Таблица 2.18 Параметры ответа с кодом возврата 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	query_id	string	Да	Идентификатор запроса
2	success	string	Да	При удалении через /query отображается строка с константным значением «Запрос отменен» При удалении через /regulated-query отображается строка с константным значением «Результат удален»

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

HTTP/1.1 200 OK
{
  "query_id": "c005a0e7-0d26-4ce0-a1fa-10c8bdf4dfc5",
  "success": "Результат удален"
}

Таблица 2.19 Параметры ответа с кодом возврата, отличным от 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	Нет	Клиентский идентификатор
3	Version	string	Да	Версия протокола (на текущий момент 1.0)
body
1	query_id	string	Нет	Идентификатор запроса
2	created_at	dateTime	Нет	Время формирования ответа
3	error	string	Нет	Текст ошибки

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

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

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

Таблица 2.20 HTTP-запрос выполнения SQL-запроса с табличным параметром
№	Параметр	Тип	Обязательность	Описание
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	minorVersion	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	params	array	Нет	Параметры запроса
8.1	type	string	Да	Тип параметра
8.2	value	string	Да	Значение параметра
8.3	name	string	Нет	Наименование именованного параметра. Всегда заполняется для системного параметра, для именованных параметров - опционально Если не заполняется - параметры подставляются в порядке задания в SQL-выражении РЗ Если заполняется - наименование должно быть указано для всех параметров запроса
9	<name>		Да	Файл с данными для табличного параметра. Имя параметра соответствует наименованию табличного параметра
file
9.1		файл в формате CSV	Да	Файл в формате CSV (поддерживаемый формат), передаваемый в параметре запроса
boundary
1	Content-Disposition	string	Да	form-data; name=”table1”; filename=”table1.csv”

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

Примечание

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

Таблица 2.21 HTTP-запрос выполнения SQL-запроса с табличным параметром (с возможностью использования надстроек)
№	Параметр	Тип	Обязательность	Описание
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)
body
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	type	string	Да	Тип столбца
5	params	array	Нет	Параметры запроса
5.1	type	string	Да	Тип параметра
5.2	value	string	Да	Значение параметра
5.3	name	string	Нет	Наименование именованного параметра. Всегда заполняется для системного параметра, для именованных параметров - опционально Если не заполняется - параметры подставляются в порядке задания в SQL-выражении РЗ Если заполняется - наименование должно быть указано для всех параметров запроса
6	<name>		Да	Файл с данными для табличного параметра. Имя параметра соответствует наименованию табличного параметра
file
6.1		файл в формате CSV	Да	Файл в формате CSV (поддерживаемый формат), передаваемый в параметре запроса
boundary
1	Content-Disposition	string	Да	form-data; name=”table1”; filename=”table1.csv”

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

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

Время исполнения запросов на получение BLOB по ссылке ограничено. Таймаут по умолчанию - 24 часа.

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

Таблица 2.22 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 по ссылке указать тот же сквозной идентификатор, что и при исходном запросе. Ответственность за соответствие идентификаторов лежит на Потребителе.

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

curl --location --request GET 'https://localhost:8192/regulated-query/blob/c005a0e7-0d26-4ce0-a1fa-10c8bdf4dfc5' \
  -header 'Accept: application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8' \
  -header 'Accept-Version: 1'

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

Таблица 2.23 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 по ссылке указать тот же сквозной идентификатор, что и при исходном запросе. Ответственность за соответствие идентификаторов лежит на Потребителе.

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

curl --location --request GET 'https://localhost:8192/query/blob/c005a0e7-0d26-4ce0-a1fa-10c8bdf4dfc5' \
  -header 'Accept: application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8' \
  -header 'Accept-Version: 1'

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

Таблица 2.24 Параметры ответа с кодом возврата 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.25 Параметры ответа с кодом возврата, отличным от 200:
№	Параметр	Тип	Обязательность	Описание
1	responseCode	numeric	Да	Код возврата (HTTP-код) Перечень возможных кодов и путей их решения представлены в Раздел 4
header
1	Content-Type	string	Да	application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8
2	Version	string	Да	Версия протокола (на текущий момент 1.0)
3	ClientRequestID	string	Нет	Клиентский идентификатор
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: Запросы к Ядру СМЭВ4 временно заблокированы до September 10, 2021 3:24:35 PM UTC, код причины блокировки=<>, подробности: ‘Превышен лимит по количеству скачиваний по ссылке... ”
}

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

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

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

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

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

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

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

Для прикладного разработчика работа с JDBC драйвером СМЭВ4 ничем не отличается от работы с обычным 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.2.2. Коды возврата

Коды возврата при ошибках выполнения запроса пути их решения представлены в Раздел 4.

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

2.3.3.1. HTTP-запрос

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

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

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

Время исполнения запросов к REST-сервису ИС Ответчика ограничено. Таймаут по умолчанию - 24 часа.

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

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

Коды возврата СМЭВ4 при ошибках и пути их решения представлены в Раздел 4.

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-сервис ИС Ответчика и загруженной в СМЭВ4.

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