.. _connection_description: Описание подключения к СМЭВ4 ================================== .. _participants_connect: Подключение участников взаимодействия с использованием СМЭВ4 ---------------------------------------------------------------- Основным способом направления обращений является использование Личного кабинета СЦ https://sc.digital.gov.ru/. Электронная почта `sd@sc.digital.gov.ru `_ является резервным способом направления обращений, который используется в случае недоступности Личного кабинета СЦ. Более подробная информация о порядке подключения к СМЭВ4 приведена в документе «Регламент Правила и процедуры работы в СМЭВ4». .. _provider_protocol: Протокол взаимодействия Агента СМЭВ4 и Витрины Поставщика данных ----------------------------------------------------------------------- Агент Поставщика данных может взаимодействовать с несколькими Витринами. Протокол коммуникации Агента СМЭВ4 и Витрин реализован в виде обмена сообщениями с использованием зарезервированных топиков брокера сообщений Apache Kafka. .. _provider_kafka_topics: Перечень топиков брокера сообщений Apache Kafka ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Конфигурация Агента СМЭВ4 содержит перечень Витрин, с которыми он взаимодействует. Каждой Витрине в зависимости от настроек конфигурации, заданных в соответствии с документом «Руководство администратора Агента СМЭВ4» соответствует один из наборов топиков: 1. Набор топиков, создаваемый по умолчанию. Полное название топиков формируются по шаблону ``<префикс для динамически подключаемых Витрин>.<название топика>``. По умолчанию префикс отсутствует. 2. Дополнительный набор топиков. Полное название топиков формируются по следующему шаблону ``<префикс для статически подключаемых Витрин>.<название топика>``. По умолчанию создаются отдельные группы топиков для каждой схемы Витрины с префиксом, соответствующим мнемонике Витрины. Названия топиков брокера сообщений [4]_ приведены в :numref:`tab_broker_topics_name`. .. _tab_broker_topics_name: .. table:: Названия топиков брокера сообщений 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>. | Агент | Агент | Сообщения от Витрины для передачи в СМЭВ4 | | | <мнемоника агента>.undelivered. | | | | | | message | | | | +----+---------------------------------+-------------+------------------+----------------------------------------------------+ .. [4] Далее в :numref:`consumer_protocol` префикс <префикс> в названии топиков может быть опущен. .. _consumer_protocol: Протокол взаимодействия Агента СМЭВ4 и ИС Потребителя данных ----------------------------------------------------------------------- Для обеспечения доступности данных Агент СМЭВ4 предоставляет: - REST-интерфейс для выполнения запросов к Витринам Поставщиков данных (:numref:`consumer_sql_rest_interface` данного документа); - JDBC-интерфейс для выполнения запросов к Витринам Поставщиков данных (:numref:`jdbc_interface` данного документа). - REST-интерфейс для выполнения запросов к REST-сервису ИС Ответчика (:numref:`respondent_rest_interface` документа); .. _consumer_sql_rest_interface: REST-интерфейс Агента СМЭВ4 для SQL-запросов к Витринам данных ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ В Агенте СМЭВ4 реализована поддержка REST-интерфейса для выполнения запросов к Витринам Поставщиков данных, спецификация которого приведена во вложенном файле: :download:`sql_query_openapi.json ` URL-адрес для выполнения обращений к REST-интерфейсу имеет следующий формат: ``http://<адрес>:<порт>/``, где: - ``<адрес>`` – IP-адрес Агента Потребителя СМЭВ4; - ``<порт>`` – порт, на котором развернут REST-интерфейс Агента СМЭВ4 в соответствии с документом «Руководство администратора Агента СМЭВ4»; - ```` - см. описание параметра "путь (Path)" далее по тексту. .. _consumer_sql_sync_request: Выполнение SQL-запросов (синхронный режим) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ В синхронном режиме получение результата осуществляется путем выполнения одного HTTP-запроса от ИС Потребителя к Агенту СМЭВ4. В рамках HTTP-запроса (метод POST) передается SQL-запрос, в ответе возвращается результат выполнения SQL-запроса. .. _sync_broker_connect: HTTP-запрос выполнения SQL-РЗ ################################## .. table:: HTTP-запрос выполнения SQL-РЗ +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | № | Параметр | Тип | Обязательность | Описание | +=====+======================+=========+===============================+==================================================+ | 1 | Тип запроса (Method) | - | Да | POST | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | 2 | Путь (Path) | - | Да | /regulated-query | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | **header** | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | 1 | Content-Type | string | Да | application/x-www-form-urlencoded; charset=utf-8 | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | 2 | Accept-version | string | Да | Основная (major) часть версии (сейчас 1) | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | 3 | ClientRequestID | string | Нет | Клиентский идентификатор | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | **query parameter** | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | 1 | format | string | Нет | Формат возвращаемых в ответе на запрос данных. | | | | | | Возможные значения: | | | | | | | | | | | | - json - по умолчанию; | | | | | | | | | | | | - avro | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | **body** | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | 1 | priority | string | Да | Приоритет запроса. Варианты: | | | | | | | | | | | | - NORMAL; | | | | | | | | | | | | - HIGH | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | 2 | timeout | string | Нет | Предельное время ожидания выполнения запроса | | | | | | (в секундах). | | | | | | | | | | | | Запросы без указания данного параметра | | | | | | использовать не рекомендуется, следует указать | | | | | | значение, равное времени ожидания ответа на ИС | | | | | | Потребителя. Максимальное значение 24 часа. | | | | | | | | | | | | В случае отсутствия параметра в запросе | | | | | | используется таймаут, заданный в конфигурации | | | | | | Агента СМЭВ4 (по умолчанию 20 секунд). | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | 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-выражении РЗ | | | | | | Если заполняется - наименование должно быть | | | | | | указано для всех параметров запроса | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ Пример запроса: .. code-block:: curl --location --request POST 'https://localhost:8192/regulated-query?format=avro' \ --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"}' .. _sync_pulsar_connect: HTTP-запрос выполнения SQL-запроса (с возможностью использования надстроек) #################################################################################################### .. note:: Использование не рекомендуется. Возможность указания надстроек (дополнительных условий фильтрации и операций над получаемыми данными, например, order by, limit, where и т.д.) при вызове регламентированного SQL-запроса ограничена. При наличии потребности использовать такие надстройки рекомендуется обратится к поставщику данных для добавления их в SQL-выражение. Данный метод останется доступным только для выполнения произвольных SQL-запросов к собственным Витринам данных для тестирования. .. table:: HTTP-запрос выполнения SQL-запроса (с возможностью использования надстроек) +-----+----------------------+---------+----------------+--------------------------------------------------+ | № | Параметр | Тип | Обязательность | Описание | +=====+======================+=========+================+==================================================+ | 1 | Тип запроса (Method) | - | Да | POST | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 2 | Путь (Path) | - | Да | /query | +-----+----------------------+---------+----------------+--------------------------------------------------+ | **header** | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 1 | Content-Type | string | Да | application/x-www-form-urlencoded; charset=utf-8 | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 2 | Accept-version | string | Да | Основная (major) часть версии (сейчас 1) | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 3 | ClientRequestID | string | Нет | Клиентский идентификатор | +-----+----------------------+---------+----------------+--------------------------------------------------+ | **query parameter** | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 1 | async | boolean | Нет | Для синхронного режима выполнения запроса | | | | | | параметр должен отсутствовать или иметь значение | | | | | | False | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 2 | format | string | Нет | Формат возвращаемых в ответе на запрос данных. | | | | | | Возможные значения: | | | | | | | | | | | | - json - по умолчанию; | | | | | | | | | | | | - avro | +-----+----------------------+---------+----------------+--------------------------------------------------+ | **body** | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 1 | priority | string | Да | Приоритет запроса. Варианты: | | | | | | | | | | | | - NORMAL; | | | | | | | | | | | | - HIGH | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 2 | timeout | string | Нет | Предельное время ожидания выполнения запроса | | | | | | (в секундах). | | | | | | | | | | | | Запросы без указания данного параметра | | | | | | использовать не рекомендуется, следует указать | | | | | | значение, равное времени ожидания ответа на ИС | | | | | | Потребителя. Максимальное значение 24 часа. | | | | | | | | | | | | В случае отсутствия параметра в запросе | | | | | | используется таймаут, заданный в конфигурации | | | | | | Агента СМЭВ4 (по умолчанию 20 секунд). | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 3 | sql | string | Да | Текст SQL-запроса к Витринам Поставщиков данных | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 4 | params | array | Нет | Параметры запроса | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 4.1 | type | string | Да | Тип параметра | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 4.2 | value | string | Да | Значение параметра | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 5 | maxRows | string | Нет | Максимальное количество возвращаемых записей | | | | | | таблицы ответа. Если не задан, возвращаются все | | | | | | записи. | +-----+----------------------+---------+----------------+--------------------------------------------------+ Пример запроса: .. code-block:: curl --location --request POST 'https://localhost:8192/query?async=false&format=avro' \ --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' .. _sync_response: Ответ на HTTP-запрос ######################## .. table:: Параметры ответа с кодом возврата 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 | Да | Тип поля | +-----+----------------------+----------+----------------+--------------------------------------------------+ Пример ответа в формате JSON с кодом возврата 200: .. code-block:: 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» ] ] } Пример ответа в формате AVRO с кодом возврата 200: .. code-block:: HTTP/1.1 200 OK Objavro.schema�{"type":"record","name":"QueryResultRow","namespace":"query.result","doc":"{\"metadata\":[{\"name\":\"EXPR__0\",\"type\":\"BIGINT\",\"size\":null,\"nullable\":true}]}","fields":[{"name":"EXPR__0","type":["null","long"],"default":null}]}avro.codeczstandard Пример ответа при возврате BLOB и ссылки на BLOB: .. code-block:: 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" ] ] } .. table:: Параметры ответа с кодом возврата, отличным от 200 +-----+----------------------+----------+----------------+--------------------------------------------------+ | № | Параметр | Тип | Обязательность | Описание | +=====+======================+==========+================+==================================================+ | 1 | responseCode | numeric | Да | Код возврата (HTTP-код) | | | | | | Перечень возможных кодов и путей их решения | | | | | | представлены в :numref:`annex_at` | +-----+----------------------+----------+----------------+--------------------------------------------------+ | **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: .. code-block:: 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})’.” } .. _consumer_sql_async_request: Выполнение SQL-запросов (асинхронный режим) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ В асинхронном режиме получение результата осуществляется путем выполнения двух HTTP-запросов от ИС Потребителя к Агенту СМЭВ4: 1. В рамках первого HTTP-запроса (метод POST) передается SQL-запрос, в ответе возвращается идентификатор запроса. 2. В рамках второго HTTP-запроса (метод GET) передается ранее полученный идентификатор запроса, в ответе возвращается результат выполнения SQL-запроса. .. note:: Получение результата по указанному идентификатору возможно неограниченное количество раз за время хранения в Ядре. При необходимости регулировать время хранения можно с помощью параметра "timeout" запроса. **Когда получать результат выполнения SQL-запроса больше не требуется, настоятельно рекомендуется выполнить запрос на удаление результата выполнения запроса (метод DELETE).** .. _consumer_async_sql_post_request: HTTP-запрос выполнения SQL-РЗ (метод POST) ############################################################## .. _async_post_broker_connect: HTTP-запрос выполнения SQL-РЗ *********************************************************** .. table:: HTTP-запрос выполнения SQL-РЗ +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | № | Параметр | Тип | Обязательность | Описание | +=====+======================+=========+===============================+==================================================+ | 1 | Тип запроса (Method) | - | Да | POST | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | 2 | Путь (Path) | - | Да | /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 часа. | | | | | | | | | | | | В случае отсутствия параметра в запросе | | | | | | используется таймаут, заданный в конфигурации | | | | | | Агента СМЭВ4 (по умолчанию 20 секунд). | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ | 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 | Нет | Наименование параметра | +-----+----------------------+---------+-------------------------------+--------------------------------------------------+ Пример запроса: .. code-block:: 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"}' .. _async_post_pulsar_connect: HTTP-запрос выполнения SQL-запроса (с возможностью использования надстроек) ************************************************************************************************ .. note:: Использование не рекомендуется. Возможность указания надстроек (дополнительных условий фильтрации и операций над получаемыми данными, например, order by, limit, where и т.д.) при вызове регламентированного SQL-запроса ограничена. При наличии потребности использовать такие надстройки рекомендуется обратиться к поставщику данных для добавления их в SQL-выражение. Данный метод останется доступным только для выполнения произвольных SQL-запросов к собственным Витринам данных для тестирования. .. table:: HTTP-запрос выполнения Регламентированного SQL-запроса (с возможностью использования надстроек) +-----+----------------------+---------+----------------+--------------------------------------------------+ | № | Параметр | Тип | Обязательность | Описание | +=====+======================+=========+================+==================================================+ | 1 | Тип запроса (Method) | - | Да | POST | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 2 | Путь (Path) | - | Да | /query | +-----+----------------------+---------+----------------+--------------------------------------------------+ | **header** | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 1 | Content-Type | string | Да | application/x-www-form-urlencoded; charset=utf-8 | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 2 | Accept-version | string | Да | Основная (major) часть версии (сейчас 1) | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 3 | ClientRequestID | string | Нет | Клиентский идентификатор | +-----+----------------------+---------+----------------+--------------------------------------------------+ | **query parameter** | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 1 | async | boolean | Нет | Для асинхронного режима выполнения запроса | | | | | | параметр должен присутствовать и иметь значение | | | | | | True | +-----+----------------------+---------+----------------+--------------------------------------------------+ | **body** | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 1 | priority | string | Да | Приоритет запроса. Варианты: | | | | | | | | | | | | - NORMAL; | | | | | | | | | | | | - HIGH | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 2 | timeout | string | Нет | Предельное время ожидания выполнения запроса | | | | | | (в секундах). | | | | | | | | | | | | Запросы без указания данного параметра | | | | | | использовать не рекомендуется, следует указать | | | | | | значение, равное времени ожидания ответа на ИС | | | | | | Потребителя. Максимальное значение 24 часа. | | | | | | | | | | | | В случае отсутствия параметра в запросе | | | | | | используется таймаут, заданный в конфигурации | | | | | | Агента СМЭВ4 (по умолчанию 20 секунд). | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 3 | sql | string | Да | Текст SQL-запроса | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 4 | params | array | Нет | Параметры запроса | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 4.1 | type | string | Да | Тип параметра | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 4.2 | value | string | Да | Значение параметра | +-----+----------------------+---------+----------------+--------------------------------------------------+ | 5 | maxRows | string | Нет | Максимальное количество возвращаемых записей | | | | | | таблицы ответа. Если не задан, возвращаются все | | | | | | записи. | +-----+----------------------+---------+----------------+--------------------------------------------------+ Пример запроса: .. code-block:: 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' .. _async_post_response: Ответ на HTTP-запрос ******************** .. table:: Параметры ответа с кодом возврата 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 | Да | Время, до которого доступен результат выполнения | | | | | | запроса. | | | | | | Определяется исходя | | | | | | из пользовательского таймаута или таймаута | | | | | | по умолчанию. | +-----+----------------------+----------+----------------+--------------------------------------------------+ Пример ответа с кодом возврата 201: .. code-block:: HTTP/1.1 201 Created { “id”: “a2f05175-d5bc-47d4-9b88-17930630683e”, «deadline»: «2021-05-13T06:33:43Z» } .. table:: Параметры ответа с кодом возврата, отличным от 201: +-----+----------------------+----------+----------------+--------------------------------------------------+ | № | Параметр | Тип | Обязательность | Описание | +=====+======================+==========+================+==================================================+ | 1 | responseCode | numeric | Да | Код возврата (HTTP-код) | | | | | | Перечень возможных кодов и путей их решения | | | | | | представлены в :numref:`annex_at` | +-----+----------------------+----------+----------------+--------------------------------------------------+ | **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 | Нет | Текст ошибки | +-----+----------------------+----------+----------------+--------------------------------------------------+ .. _consumer_async_sql_get_response: HTTP-запрос получения результата ранее переданного асинхронного SQL-запроса (метод GET) ############################################################################################################ .. _async_get_broker_connect: HTTP-запрос ************************ .. table:: HTTP-запрос +-----+----------------------+---------+----------------+----------------------------------------------------------+ | № | Параметр | Тип | Обязательность | Описание | +=====+======================+=========+================+==========================================================+ | 1 | Тип запроса (Method) | - | Да | GET | +-----+----------------------+---------+----------------+----------------------------------------------------------+ | 2 | Путь (Path) | - | Да | - /regulated-query | | | | | | - /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-запроса | +-----+----------------------+---------+----------------+----------------------------------------------------------+ | **query parameter** | +-----+----------------------+---------+----------------+----------------------------------------------------------+ | 1 | format | string | Нет | Формат возвращаемых в ответе на запрос данных. | | | | | | Возможные значения: | | | | | | | | | | | | - json - по умолчанию; | | | | | | | | | | | | - avro | +-----+----------------------+---------+----------------+----------------------------------------------------------+ Примеры запросов: .. code-block:: curl --location --request GET 'https://localhost:8192/regulated-query/3fa85f64-5717-4562-b3fc-2c963f66afa6?format=avro' \ --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?format=avro' \ --header 'Accept: application/vnd.ru.rtlabs.podd.agent+json; charset=utf-8' \ --header 'Accept-Version: 1' \ --header 'ClientRequestID: afd36c80-957e-11ed-87cd-0800200c9a66' .. _async_get_response: Ответ на HTTP-запрос ************************ .. table:: Параметры ответа с кодом возврата 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 | Да | Тип поля | +-----+----------------------+----------+----------------+--------------------------------------------------+ Пример ответа в формате JSON с кодом возврата 200: .. code-block:: 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» ] ] } Пример ответа в формате AVRO с кодом возврата 200: .. code-block:: HTTP/1.1 200 OK Objavro.schema�{"type":"record","name":"QueryResultRow","namespace":"query.result","doc":"{\"metadata\":[{\"name\":\"EXPR__0\",\"type\":\"BIGINT\",\"size\":null,\"nullable\":true}]}","fields":[{"name":"EXPR__0","type":["null","long"],"default":null}]}avro.codeczstandard .. table:: Параметры ответа с кодом возврата, отличным от 200: +----+----------------------+----------+----------------+--------------------------------------------------+ | № | Параметр | Тип | Обязательность | Описание | +====+======================+==========+================+==================================================+ | 1 | responseCode | numeric | Да | Код возврата (HTTP-код) | | | | | | Перечень возможных кодов и путей их решения | | | | | | представлены в :numref:`annex_at` | +----+----------------------+----------+----------------+--------------------------------------------------+ | **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 | Нет | Текст ошибки | +----+----------------------+----------+----------------+--------------------------------------------------+ .. _consumer_async_sql_delete_response: HTTP-запрос на удаление результата выполнения ранее переданного асинхронного SQL-запроса (метод DELETE) ###################################################################################################################### .. _async_delete: HTTP-запрос *************************************************************************************** .. table:: HTTP-запрос +-----+----------------------+---------+----------------+----------------------------------------------------------+ | № | Параметр | Тип | Обязательность | Описание | +=====+======================+=========+================+==========================================================+ | 1 | Тип запроса (Method) | - | Да | DELETE | +-----+----------------------+---------+----------------+----------------------------------------------------------+ | 2 | Путь (Path) | - | Да | - /regulated-query | | | | | | | | | | | | - /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-запроса | +-----+----------------------+---------+----------------+----------------------------------------------------------+ Пример запроса: .. code-block:: 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' .. _async_delete_response: Ответ на HTTP-запрос ************************ .. table:: Параметры ответа с кодом возврата 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: .. code-block:: HTTP/1.1 200 OK { "query_id": "c005a0e7-0d26-4ce0-a1fa-10c8bdf4dfc5", "success": "Результат удален" } .. table:: Параметры ответа с кодом возврата, отличным от 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 | Нет | Текст ошибки | +----+----------------------+----------+----------------+--------------------------------------------------+ .. _consumer_tp_request: Выполнение SQL-РЗ с табличным параметром ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Может быть выполнен как в синхронном, так и в асинхронном режиме. Ответ соответствует способу вызова. .. _tp_broker_connect: HTTP-запрос выполнения SQL-РЗ с табличным параметром #################################################################### .. table:: HTTP-запрос выполнения SQL-запроса с табличным параметром +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | № | Параметр | Тип | Обязательность | Описание | +=======+======================+=========+===============================+==================================================+ | 1 | Тип запроса (Method) | - | Да | POST | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 2 | Путь (Path) | - | Да | /regulated-query – для синхронного | | | | | | вызова | | | | | | | | | | | | /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 | Нет | Клиентский идентификатор | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | **query parameter** | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 1 | format | string | Нет | Формат возвращаемых в ответе на запрос данных. | | | | | | Возможные значения: | | | | | | | | | | | | - json - по умолчанию; | | | | | | | | | | | | - avro | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | **body** | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 1 | priority | string | Да | Приоритет запроса. Варианты: | | | | | | | | | | | | - NORMAL; | | | | | | | | | | | | - HIGH | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 2 | timeout | string | Нет | Предельное время ожидания выполнения запроса | | | | | | (в секундах). | | | | | | | | | | | | Запросы без указания данного параметра | | | | | | использовать не рекомендуется, следует указать | | | | | | значение, равное времени ожидания ответа на ИС | | | | | | Потребителя. Максимальное значение 24 часа. | | | | | | | | | | | | В случае отсутствия параметра в запросе | | | | | | используется таймаут, заданный в конфигурации | | | | | | Агента СМЭВ4 (по умолчанию 20 секунд). | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 3 | datamart | string | Да | Витрина Поставщика данных, к которой | | | | | | производится обращение | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 4 | mnemonic | string | Да | Мнемоника РЗ, к которому производится обращение | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 5 | majorVersion | int | Нет | Версия РЗ, к которому производится обращение | | | | | | | | | | | Обязательное указание вместе | | | | | | с minorVersion. Если не | | | | | | указана, обращение к | | | | | | актуальной версии | | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 6 | minorVersion | int | Нет | Версия РЗ, к которому производится обращение | | | | | | | | | | | Обязательное указание вместе | | | | | | с majorVersion. Если не | | | | | | указана, обращение к | | | | | | актуальной версии | | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 7 | tableParams | array | Да | Описание передаваемого файла с данными для | | | | | | табличного параметра | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 7.1 | name | string | Да | Наименование табличного параметра, | | | | | | соответствующее указанному в SQL-выражении | | | | | | в формате ``@`` | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 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 | | | Да | Файл с данными для табличного параметра. Имя | | | | | | параметра соответствует наименованию табличного | | | | | | параметра | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | **file** | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 9.1 | - | файл в | Да | Файл в формате CSV (поддерживаемый формат), | | | | формате | | передаваемый в параметре запроса | | | | CSV | | | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | **boundary** | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 1 | Content-Disposition | string | Да | form-data; name=”table1”; filename=”table1.csv” | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ .. _tp_pulsar_connect: HTTP-запрос выполнения SQL-запроса с табличным параметром (с возможностью использования надстроек) ######################################################################################################## .. note:: Использование не рекомендуется. Возможность указания надстроек (дополнительных условий фильтрации и операций над получаемыми данными, например, order by, limit, where и т.д.) при вызове регламентированного SQL-запроса ограничена. При наличии потребности использовать такие надстройки рекомендуется обратиться к поставщику данных для добавления их в SQL-выражение. Данный метод останется доступным только для выполнения произвольных SQL-запросов к собственным Витринам данных для тестирования. .. table:: HTTP-запрос выполнения SQL-запроса с табличным параметром (с возможностью использования надстроек) +-------+----------------------+----------+----------------+----------------------------------------------------------+ | № | Параметр | Тип | Обязательность | Описание | +=======+======================+==========+================+==========================================================+ | 1 | Тип запроса (Method) | - | Да | POST | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | 2 | Путь (Path) | - | Да | /query | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | **query parameter** | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | 1 | async | boolean | Нет | Для синхронного режима выполнения запроса параметр | | | | | | должен отсутствовать или иметь значение False | | | | | | | | | | | | Для асинхронного режима выполнения запроса параметр | | | | | | должен иметь значение True | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | 2 | format | string | Нет | Формат возвращаемых в ответе на запрос данных. | | | | | | Возможные значения: | | | | | | | | | | | | - json - по умолчанию; | | | | | | | | | | | | - avro | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | **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 | Нет | Предельное время ожидания выполнения запроса | | | | | | (в секундах). | | | | | | | | | | | | Запросы без указания данного параметра | | | | | | использовать не рекомендуется, следует указать | | | | | | значение, равное времени ожидания ответа на ИС | | | | | | Потребителя. Максимальное значение 24 часа. | | | | | | | | | | | | В случае отсутствия параметра в запросе | | | | | | используется таймаут, заданный в конфигурации | | | | | | Агента СМЭВ4 (по умолчанию 20 секунд). | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | 3 | sql | string | Да | Текст SQL-запроса | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | 4 | tableParams | array | Да | Описание передаваемого файла с данными для табличного | | | | | | параметра | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | 4.1 | name | string | Да | Наименование табличного параметра, соответствующее | | | | | | указанному в SQL-выражении в формате ``@`` | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | 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 | | | Да | Файл с данными для табличного параметра. Имя параметра | | | | | | соответствует наименованию табличного параметра | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | **file** | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | 6.1 | - | файл в | Да | Файл в формате CSV (поддерживаемый формат), передаваемый | | | | формате | | в параметре запроса | | | | CSV | | | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | **boundary** | +-------+----------------------+----------+----------------+----------------------------------------------------------+ | 1 | Content-Disposition | string | Да | form-data; name=”table1”; filename=”table1.csv” | +-------+----------------------+----------+----------------+----------------------------------------------------------+ Пример запроса приведен в :numref:`rest_interface_request` настоящего документа. .. _blob_sql_request: Выполнение запроса на получение BLOB по ссылке ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Время исполнения запросов на получение BLOB по ссылке ограничено. Таймаут по умолчанию 1 час. .. _blob_broker_connect: HTTP-запрос (вариант 1) ##################################### .. table:: HTTP-запрос (вариант 1) +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | № | Параметр | Тип | Обязательность | Значение / описание | +=======+======================+=========+===============================+==================================================+ | 1 | Тип запроса (Method) | - | Да | GET | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 2 | Путь (Path) | - | Да | /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 по | | | | | | ссылке указать тот же сквозной идентификатор, | | | | | | что и при исходном запросе. | | | | | | | | | | | | Ответственность за соответствие идентификаторов | | | | | | лежит на Потребителе. | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ Пример запроса: .. code-block:: 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' .. _blob_request_onnect: HTTP-запрос (вариант 2) ############################### .. table:: HTTP-запрос (вариант 2) +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | № | Параметр | Тип | Обязательность | Значение / описание | +=======+======================+=========+===============================+==================================================+ | 1 | Тип запроса (Method) | - | Да | GET | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ | 2 | Путь (Path) | - | Да | /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 по | | | | | | ссылке указать тот же сквозной идентификатор, | | | | | | что и при исходном запросе. | | | | | | | | | | | | Ответственность за соответствие идентификаторов | | | | | | лежит на Потребителе. | +-------+----------------------+---------+-------------------------------+--------------------------------------------------+ Пример запроса: .. code-block:: 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' .. _blob_response: Ответ на HTTP-запрос ######################## .. table:: Параметры ответа с кодом возврата 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: .. code-block:: HTTP/1.1 200 OK <Содержимое полученного по ссылке файла (в виде массива байт)> .. table:: Параметры ответа с кодом возврата, отличным от 200: +----+----------------------+----------+----------------+--------------------------------------------------+ | № | Параметр | Тип | Обязательность | Описание | +====+======================+==========+================+==================================================+ | 1 | responseCode | numeric | Да | Код возврата (HTTP-код) | | | | | | Перечень возможных кодов и путей их решения | | | | | | представлены в :numref:`annex_at` | +----+----------------------+----------+----------------+--------------------------------------------------+ | **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: .. code-block:: 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, код причины блокировки=<>, подробности: ‘Превышен лимит по количеству скачиваний по ссылке... ” } .. _jdbc_interface: JDBC-интерфейс Агента СМЭВ4 для SQL-запросов к Витринам данных ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Агент СМЭВ4 поддерживает специализированный протокол для исполнения запросов к Витринам Поставщиков данных, эталонная реализация которого представлена JDBC-драйвером. Настройка JDBC-драйвера осуществляется с помощью передачи специализированной адресной строки: ``protocol://hostname:port/``, где: - ``protocol`` – протокол взаимодействия – значение всегда будет «podd»; - ``hostname`` – имя сервера или его IP-адрес; - ``port`` – порт, на котором Агент Потребителя данных предоставляет интерфейс для работы протокола взаимодействия в соответствии с «Руководством администратора Агента СМЭВ4». Клиентский идентификатор опционально передаётся в тексте SQL запроса первой строкой – комментарий с атрибутом ClientRequestID (тип string). .. code-block:: -- ClientRequestID: <клиентский идентификатор> CALL <мнемоника регламентированного SQL-запроса>(); .. _jdbc_driver: Пример использования JDBC-драйвера в «Kotlin» ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Для прикладного разработчика работа с JDBC драйвером СМЭВ4 ничем не отличается от работы с обычным JDBC драйвером. Особенность только в URL, которым инициализируется драйвер. .. code-block:: 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> { 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> { 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") } } } } } } } .. _jdbc_response_codes: Коды возврата ^^^^^^^^^^^^^^^^^ Коды возврата при ошибках выполнения запроса пути их решения представлены в :numref:`annex_at`. .. _respondent_rest_interface: REST-интерфейс Агента СМЭВ4 для запросов к REST-сервису ИС Ответчика ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _respondent_request: HTTP-запрос ^^^^^^^^^^^^ Все запросы выполняются в синхронном режиме в соответствии с загруженной в СМЭВ4 спецификацией OpenApi REST-сервиса ИС Ответчика. Примеры спецификаций OpenAPI REST-сервисов ИС Ответчиков приведены в :numref:`respondent_rest_services`. При выполнении запроса могут быть использованы все типы HTTP-методов (POST, GET, PUT и DELETE), выполняющих CRUD-операции (Create/Read/Update/Delete), которые используются в спецификациях OpenAPI, описывающих REST-сервисы ИС Ответчиков. Информация о формировании запроса приведена в :numref:`rest_service_output`. .. _respondent_response: Ответ на HTTP-запрос ^^^^^^^^^^^^^^^^^^^^^^^ Ответ на запрос включает код возврата (статус выполнения операции) и, в зависимости от запрошенного метода, тело ответа, содержащее запрошенные данные и/или дополнительную информацию о результате выполнения операции, в соответствии с загруженной в СМЭВ4 спецификацией OpenAPI REST-сервиса ИС Ответчика. Коды возврата СМЭВ4 при ошибках и пути их решения представлены в :numref:`annex_at`. .. _distribution_consumer_protocol: Протокол взаимодействия Агента СМЭВ4 и Витрины Потребителя данных --------------------------------------------------------------------------------------------- Протокол коммуникации Агента СМЭВ4 и Витрины данных, расположенных в контуре Потребителя данных, устроен в виде обмена сообщениями с использованием зарезервированных топиков брокера сообщений Apache Kafka. Всё взаимодействие между Витриной данных и Агентом СМЭВ4 происходит исключительно с использованием брокера сообщений. .. _consumer_kafka_topics: Перечень топиков брокера сообщений Apache Kafka ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :numref:`tab_consumer_kafka_topics` содержит названия топиков брокера сообщений. .. _tab_consumer_kafka_topics: .. table:: Названия топиков брокера сообщений 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 | Витрина | Агент | События Витрины для дальнейшей передачи в | | | | | | СЦЛ | +----+-------------------------------------+-------------------+----------------+--------------------------------------------+ .. _respondent_protocol: Протокол взаимодействия Агента СМЭВ4 и ИС Ответчика ----------------------------------------------------------- Взаимодействие Агента СМЭВ4 и REST-сервиса на стороне ИС Ответчика осуществляется в соответствии со спецификацией OpenAPI, описывающей REST-сервис ИС Ответчика и загруженной в СМЭВ4. Для использования запросов к REST-сервису ИС Ответчика через СМЭВ4 необходимо произвести настройки, указанные в документе «Руководство администратора Агента СМЭВ4».