3. Использование СМЭВ4

3.1. SQL-синтаксис

Регламентированные SQL-запросы, регистрируемые в СМЭВ4, должны соответствовать следующему синтаксису.

Таблица 3.2 SQL-синтаксис

№

Описание

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

Минимальная версия ПО

Агент СМЭВ4

Витрина данных

1

Числовые типы данных

1.1

Типы данных INTEGER и SMALLINT

SELECT CAST(1 AS INT)

3.0.0

1.12.0

1.2

Типы данных REAL, DOUBLE PRECISION и FLOAT

SELECT CAST(1 AS FLOAT)

1.3

Типы данных DECIMAL и NUMERIC

SELECT CAST(1 AS NUMERIC)

1.4

Арифметические операторы

SELECT 10+1, 9-2, 8*3, 7/2

1.5

Числовые сравнения

SELECT 1 WHERE 1 < 2

1.6

Неявные преобразования между числовыми типами данных

SELECT int_column FROM t WHERE int_column = 1.00

2

Символьные типы данных

2.1

Тип данных CHARACTER

Длина по умолчанию 30

SELECT CAST(‘1111111111111111111111111111111111111111111’ AS CHAR)

3.0.0

1.12.0

2.2

Тип данных CHARACTER VARYING

Длина по умолчанию 30

SELECT CAST(‘1111111111111111111111111111111111111111111’ AS VARCHAR)

2.3

Символьные строки

SELECT ''

2.4

Функция CHARACTER_LENGTH

убирает завершающие пробелы из значений CHARACTER перед подсчётом символов

SELECT character_length(char_column) FROM t

2.5

Функция OCTET_LENGTH

SELECT octet_length(char_column) FROM t

2.6

Функция SUBSTRING

SELECT substring(char_column FROM 1 FOR 1) FROM t

2.7

Конкатенация символьных строк

SELECT ‘a’ || ‘b’ FROM t

2.8

Функции UPPER и LOWER

SELECT upper(‘a’),lower(‘B’) FROM t

SELECT int_column FROM t WHERE int_column > (SELECT DISTINCT (int_column) FROM t)

2.9

Функция TRIM

SELECT trim(‘a ‘) FROM t

2.10

Неявные преобразования между типами символьных строк

SELECT char_column FROM t WHERE char_column > varchar_column

2.11

Функция POSITION

SELECT position(‘A’ IN char_column) FROM t

2.12

Сравнения символов

SELECT char_column FROM t WHERE char_column > ‘a’

2.13

Функция LISTAGG для объединения значений из нескольких строк в одну строку

SELECT department_id, LISTAGG(employee_name, ', ') WITHIN GROUP (ORDER BY employee_name) AS employees_list FROM employees GROUP BY department_id;

3.18.0

1.12.0

3

Идентификаторы

3.1

Идентификаторы с разделителями

SELECT 1 AS «t47»

3.0.0

1.12.0

3.2

Идентификаторы в нижнем регистре

SELECT 1 AS t48

3.3

Завершающее подчёркивание

SELECT 1 AS t49_

4

Базовое определение запросов

4.1

SELECT DISTINCT

SELECT DISTINCT int_column FROM t

3.0.0

1.12.0

4.2

Предложение GROUP BY

SELECT DISTINCT int_column FROM t GROUP BY int_column

4.3

GROUP BY может содержать колонки не из <списка выборки>

SELECT DISTINCT char_column FROM t GROUP BY lower(char_column)

4.4

Элементы списка выборки могут переименовываться

SELECT int_column AS K FROM t ORDER BY K

4.5

Предложение HAVING

SELECT count(*) FROM t HAVING count(*) > 0

4.6

Корреляционные имена в предложении FROM

SELECT K.column FROM t AS K

4.7

Переименование колонок в предложении FROM

SELECT column FROM t AS x(q, c)

5

Базовые предикаты и условия поиска

5.1

Предикат сравнения

SELECT column FROM t WHERE 0 = 0

3.0.0

1.12.0

5.2

Предикат BETWEEN

SELECT column FROM t WHERE ‘ ‘ BETWEEN ‘’ AND ‘’

5.3

Предикат IN со списком значений

SELECT column FROM t WHERE char_column IN (‘a’, upper(‘a’))

5.4

Предикат LIKE

SELECT column FROM t WHERE char_column LIKE ‘_’

5.5

Предложение ESCAPE в предикате LIKE

SELECT column FROM t WHERE ‘abc’ LIKE ‘abcX_’ ESCAPE ‘X’

5.6

Предикат NULL

SELECT column FROM t WHERE char_column IS NOT NULL

5.7

Предикаты количественного сравнения

SELECT column FROM t WHERE char_column = ANY (SELECT char_column FROM t)

5.8

Предикат EXISTS

SELECT column FROM t WHERE NOT EXISTS (SELECT char_column FROM t)

5.9

Подзапросы в предикате сравнения

SELECT column FROM t WHERE int_column > (SELECT max (int_column) FROM t)

5.10

Подзапросы в предикате IN

SELECT column FROM t WHERE char_column IN (SELECT char_column FROM t)

5.11

Подзапросы в предикате количественного сравнения

SELECT column FROM t WHERE char_column >= ALL(SELECT char_column FROM t)

5.12

Коррелирующие подзапросы

SELECT column FROM t WHERE int_column = (SELECT int_column FROM t2 WHERE t2.char_ column = t.char_column)

5.13

Условие поиска

SELECT column FROM t WHERE 0 <> 0 OR ‘a’ < ‘b’ AND int_column IS NOT NULL

6

Простые выражения с запросами

6.1

Табличный оператор UNION DISTINCT

SELECT column FROM t UNION DISTINCT SELECT column1 FROM t

3.0.0

1.12.0

6.2

Табличный оператор UNION ALL

SELECT column FROM t UNION ALL SELECT column1 FROM t

6.3

Табличный оператор EXCEPT DISTINCT

SELECT column FROM t EXCEPT DISTINCT SELECT column1 FROM t

6.4

Табличный оператор INTERSECT

SELECT column FROM t INTERSECT SELECT column1 FROM t

6.5

Колонки, объединяемые табличными операторами, могут иметь разные типы данных

SELECT char_column FROM t UNION SELECT 5

6.6

Табличные операторы в подзапросах

SELECT column FROM t WHERE ‘a’ IN (SELECT char_column FROM t UNION SELECT char_column FROM t)

6.7

C использованием обобщенных табличных выражений

with cte as (SELECT shortname, regioncode, oktmo from fias.addrobj WHERE formalname = ‘Москва’) SELECT * FROM cte

7

Функции множеств

7.1

AVG

SELECT avg(int_column) FROM t

3.0.0

1.12.0

7.2

COUNT

SELECT count(int_column) FROM t

7.3

MAX

SELECT max(int_column) FROM t

7.4

MIN

SELECT min(int_column) FROM t

7.5

SUM

SELECT sum(int_column) FROM t

7.6

Дополнение ALL

SELECT sum(ALL int_column) FROM t

7.7

Дополнение DISTINCT

SELECT sum(DISTINCT int_column) FROM t

7.8

Оператор SELECT, возвращающий одну строку

SELECT count(*) FROM t

8

Базовая поддержка курсоров

8.1

Колонки ORDER BY, отсутствующие в списке выборки

SELECT int_column FROM t ORDER BY char_column

3.0.0

1.12.0

8.2

Выражения значений в предложении ORDER BY

SELECT int_column FROM t ORDER BY -int_column

8.3

Поддержка NULL (NULL вместо значений)

SELECT int_column FROM t WHERE int_column IS NULL

9

Базовое соединение таблиц

9.1

Внутреннее соединение (но не обязательно с ключевым словом INNER)

SELECT a.int_column FROM t a JOIN t b ON a.int_column = b.int_column

3.0.0

1.12.0

9.2

Ключевое слово INNER

SELECT a.int_column FROM t a INNER JOIN t b ON a.int_column = b.int_column

9.3

LEFT OUTER JOIN

SELECT a.int_column, b.int_column FROM t a LEFT OUTER JOIN t b ON a.int_column = b.int_column

9.4

RIGHT OUTER JOIN

SELECT a.int_column, b.int_column FROM t a RIGHT OUTER JOIN t b ON a.int_column = b.int_column

9.5

Внешние соединения могут быть вложенными

SELECT a.int_column FROM t a LEFT OUTER JOIN t b ON a.int_column = b.int_column LEFT OUTER JOIN t2 c ON a.int_column = c.int_column

9.6

Внутренняя таблица с левой или правой стороны внешнего соединения может также участвовать во внутреннем соединении

SELECT t2.int_column FROM (t2 LEFT OUTER JOIN t ON t.int_column = t2.int_column) j INNER JOIN t2 ON j.int_column = t2.int_column

9.7

Поддерживаются все операторы сравнения (а не только =)

SELECT column FROM t WHERE 0 = 1 OR 0 > 1 OR 0 < 1 OR 0 <> 1

10

Базовая поддержка даты и времени

10.1

Тип данных DATE (включая поддержку строк DATE)

SELECT ‘2012-07-12’ AS "DATE"

3.0.0

1.12.0

10.2

Тип данных TIME (включая поддержку строк TIME) с точностью до секунд как минимум с 0 знаков после запятой

SELECT ‘1:2:3’ AS "TIME"

10.3

Тип данных TIMESTAMP (включая поддержку строк TIMESTAMP)

с точностью до секунд как минимум с 0 и 6 знаками после запятой

SELECT ‘2012-07-12’ AS "TIMESTAMP"

10.4

Предикаты сравнения с типами данных DATE, TIME и TIMESTAMP

SELECT column FROM t3 WHERE date_column = date_column AND time_column = time_column AND timestamp_column = timestamp_column

10.5

Явное приведение (CAST) между типами даты/времени и типами символьных строк

SELECT cast(date_column AS VARCHAR(10)) FROM t3

10.6

CURRENT_DATE

SELECT current_date FROM t

10.7

LOCALTIME

SELECT localtime FROM t

10.8

LOCALTIMESTAMP

SELECT localtimestamp FROM t

11

Расширенная поддержка даты и времени

11.1

Вычисление интервала (c указанием единиц времени: YEAR, MONTH, DAY, HOUR, MINUTE, SECOND)

select ('YYYY-MM-DD hh:mm:ss' - 'YYYY-MM-DD hh:mm:ss') MONTH

3.0.0

1.12.0

11.2

FOR SYSTEM_TIME AS OF TIMESTAMP (запрос данных, актуальных на указанную дату и время) Указание «TIMESTAMP» опционально

SELECT column FROM t FOR SYSTEM_TIME AS OF 'YYYY-MM-DD hh:mm:ss'

SELECT column FROM t FOR SYSTEM_TIME AS OF TIMESTAMP 'YYYY-MM-DD hh:mm:ss'

11.3

FOR SYSTEM_TIME AS OF DELTA_NUM (запрос данных, актуальных на указанную дельту)

SELECT column FROM t FOR SYSTEM_TIME AS OF DELTA_NUM <delta_num>

3.18.0

1.12.0

11.4

FOR SYSTEM_TIME FINISHED IN (запрос данных, удаленных в диапазоне дельт)

SELECT column FROM t FOR SYSTEM_TIME FINISHED IN (<delta_num1>, <delta_num2>)

11.5

FOR SYSTEM_TIME FINISHED TS (запрос данных, удаленных в период времени)

SELECT column FROM t FOR SYSTEM_TIME FINISHED TS (<datetime1>, <datetime2>)

11.6

FOR SYSTEM_TIME STARTED IN (запрос данных, добавленных и/или измененных в диапазоне дельт)

SELECT column FROM t FOR SYSTEM_TIME STARTED IN (<delta_num1>, <delta_num2>)

11.7

FOR SYSTEM_TIME STARTED TS (запрос данных, добавленных и/или измененных в период времени)

SELECT column FROM t FOR SYSTEM_TIME STARTED TS (<datetime1>, <datetime2>)

11.8

FOR SYSTEM_TIME AS OF CN (запрос данных, актуальных на указанный номер операции записи)

SELECT column FROM t FOR SYSTEM_TIME AS OF CN <sys_cn>

3.18.0

2.0.0

11.9

FOR SYSTEM_TIME STARTED CN (запрос данных, добавленных и/или измененных в диапазоне операций)

SELECT column FROM t FOR SYSTEM_TIME STARTED CN (<sys_cn1>, <sys_cn2>)

11.10

FOR SYSTEM_TIME FINISHED CN (запрос данных, удаленных в диапазоне операций)

SELECT column FROM t FOR SYSTEM_TIME FINISHED CN (<sys_cn1>, <sys_cn2>)

11.11

FOR SYSTEM_TIME AS OF LATEST_UNCOMMITTED_DELTA (запрос актуальных данных, включая изменения открытой дельты)

SELECT column FROM t FOR SYSTEM_TIME AS OF LATEST_UNCOMMITTED_DELTA

11.12

FOR SYSTEM_TIME RAW (запрос данных, содержащиеся в физических таблицах логической сущности)

SELECT column FROM t FOR SYSTEM_TIME RAW

3.23.0

2.0.0

12

Функция CAST

SELECT cast(int_column AS INT) FROM t

3.0.0

1.12.0

13

Выражение CASE

13.1

Простой оператор CASE

SELECT CASE WHEN 1 = 0 THEN 5 ELSE 7 END FROM t

3.0.0

1.12.0

13.2

Оператор CASE с условиями

SELECT CASE 1 WHEN 0 THEN 5 ELSE 7 END FROM t

13.3

NULLIF

SELECT nullif(int_column, 7) FROM t

13.4

COALESCE

SELECT coalesce(int_column,7) FROM t

13.5

Длинные идентификаторы

SELECT 1 AS A12345678901234567890123456789

13.6

Спецсимволы Unicode в идентификаторах

SELECT 1 AS Я12345678901234567890123456789

13.7

Спецсимволы Unicode в текстовых строках

SELECT U&'\6553'

13.8

Национальные символы

SELECT 'Я'

13.9

Скалярные значения подзапросов

SELECT int_column  FROM t WHERE int_column = (SELECT count(*) FROM t)

13.10

Расширенный предикат NULL

SELECT column FROM t WHERE row(int_column, int_column) IS NOT NULL

14

Функции по управлению текстовым поиском

14.1

Функция TO_TSVECTOR подготовки текстовых значения, выбранных запросом

SELECT TO_TSVECTOR('russian', 'иванов иван')

3.16.0

1.16.0

14.2

Функция PLAINTO_TSQUERY подготовки неформатированного текста без сохранения порядка слов

SELECT PLAINTO_TSQUERY('russian', 'иванов иван')

14.3

Функция TO_TSQUERY подготовки слов разделенных операторами & (AND), | (OR), ! (NOT), и (или) <-> (FOLLOWED BY)

SELECT TO_TSQUERY('russian', 'иванов & иван');

14.4

Функция PHRASETO_TSQUERY подготовки неформатированного текста с сохранением порядка слов

SELECT PHRASETO_TSQUERY('russian', 'иванов иван')

14.5

Функция WEBSEARCH_TO_TSQUERY подготовки неформатированного текста с сохранением порядка слов или без него. Поддерживает операторы OR и - (NOT)

SELECT WEBSEARCH_TO_TSQUERY('russian', 'иванов иван OR петр')

14.6

Оператор @@ сравнения текстового вектора с подготовленным или неподготовленным текстом

SELECT column FROM t WHERE (TO_TSVECTOR('russian', lastname) @@ PLAINTO_TSQUERY('russian', 'иванов иван'))

SELECT column FROM t WHERE (PLAINTO_TSQUERY('russian', 'иванов иван' @@ TO_TSVECTOR('russian', lastname)))

SELECT column FROM t WHERE (lastname @@ PLAINTO_TSQUERY('russian', 'иванов иван'))

3.2. Выполнение регламентированных SQL-запросов

3.2.1. Правила выполнения

Вызов Регламентированного SQL-запроса может быть выполнен с использованием:

Возможность указания надстроек при вызове регламентированного SQL-запроса ограничена. Поэтому рекомендуется сразу использовать методы упрощенного вызова:

  • через REST-интерфейс в соответствии c Раздел 2.3.1.1.1;

  • через JDBC-интерфейс:

CALL <мнемоника Витрины>.<версия Регламентированного SQL-запроса>.<мнемоника Регламентированного SQL-запроса>(<параметры>)

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

При необходимости использования методов с возможностью использования надстроек необходимо составить SQL выражение, указав мнемонику Регламентированного SQL-запроса вместо таблицы. Формат Регламентированного SQL-запроса имеет вид:

select * from <мнемоника Витрины>.<версия Регламентированного SQL-запроса>.<мнемоника Регламентированного SQL-запроса>(<параметры>) <надстройки (опционально)>

где:

  • <мнемоника Витрины> – для простых запросов (к одной Витрине) задается мнемоника соответствующей Витрины. Для распределенного запроса вместо мнемоники Витрины указывается префикс «podd»;

  • <версия Регламентированного SQL-запроса> – задается в формате «major.minor»;

  • <мнемоника Регламентированного SQL-запроса> – мнемоника вызываемого Регламентированного SQL-запроса;

  • <параметры> – указываются в скобках через запятую для Регламентированного SQL-запроса с параметрами, заданными в определении.

    Если выполняемый запрос не требует указания параметров, то скобки должны быть указаны пустыми. Если параметры не указаны в исходном запросе, но их значения по умолчанию присутствуют в загруженном определении, то они будут подставлены автоматически.

  • <надстройки (опционально)> – дополнительные условия фильтрации и операций над получаемыми данными (например, order by, limit, where, перечисление полей вместо * и любые другие запросы отличные от select * from <мнемоника Витрины>. <версия Регламентированного SQL-запроса (опционально)>.<мнемоника Регламентированного SQL-запроса>(<параметры>))

Внимание

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

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

  1. Если параметры заданы в SQL-выражении Регламентированного SQL-запроса в виде «?», то при вызове они должны быть указаны в порядке, соответствующем определению Регламентированного SQL-запроса. Количество параметров при вызове должно соответствовать количеству параметров в определении Регламентированного SQL-запроса.

  2. Для запроса, в SQL-выражении которого параметры заданы как именованные, доступны:

    1. Вызов с использованием мнемоники именованного параметра.

      Для этого необходимо задать значения всех именованных параметров, для которых не задано значение по умолчанию, в виде «<мнемоника параметра>=><значение параметра>» (Раздел 3.2.2). при вызове РЗ через /regulated-query также возможна передача параметров с мнемоникой: params={"name": "param1","type": "STRING", "value": ""}

      Мнемоника именованного параметра при вызове запроса должна соответствовать мнемонике именованного параметра в определении Регламентированного SQL-запроса.

      Использование именованных параметров позволяет при вызове задавать значения параметров в любом порядке и только один раз, независимо от количества мест, где этот параметр используется в определении Регламентированного SQL-запроса.

    2. Вызов без использования мнемоники именованного параметра.

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

  3. Совместное использование именованных и неименованных параметров не допускается.

3.2.2. Примеры вызова и преобразования исходного запроса

  1. Регламентированный SQL-запрос с параметрами без имени:

// Исходный запрос от Потребителя данных СМЭВ4:
select * from oktmo.1.0.oktmo_view(‘Московская область’,7)

// Определение Регламентированного SQL-запроса
select id, whenadd, name, regionname, settlementtypename FROM oktmo.1.0.oktmo where regionname = ? AND settlementtypeid = ?

// Пример преобразования исходного запроса в соответствии с загруженным определением Регламентированного SQL-запроса:
select id, whenadd, name, regionname, settlementtypename FROM oktmo.1.0.oktmo where regionname = ‘Московская область’ AND settlementtypeid = 7

  1. Регламентированный SQL-запрос с именованными параметрами:

// Исходный запрос от Потребителя данных СМЭВ4 (вызов через мнемонику параметра)
select * from <мнемоника Витрины>.<версия Регламентированного SQL-запроса>.<мнемоника Регламентированного SQL-запроса>(param=>'000', lim=>20)

// Исходный запрос от Потребителя данных СМЭВ4
select * from <мнемоника Витрины>.<версия Регламентированного SQL-запроса>.<мнемоника Регламентированного SQL-запроса>('000',20)

// Определение Регламентированного SQL-запроса
SELECT name, code FROM datamart.1.0.regions WHERE code=:param and id in (select id from :param) limit :lim

// Пример преобразования исходного запроса в соответствии с загруженным определением Регламентированного SQL-запроса:
SELECT name, code FROM datamart.1.0.regions WHERE code='000' and id in (select id from '000') limit 20

  1. Регламентированный SQL-запрос с параметром типа TIMESTAMP:

// Исходный запрос от Потребителя данных СМЭВ4
select * from fias.1.0.addrobj_view('001', '000', TIMESTAMP '1970-01-01 00:00:00')

// Исходный запрос от Потребителя данных СМЭВ4
CALL fias.1.0.addrobj_view('001', '000', TIMESTAMP '1970-01-01 00:00:00')

// Исходный запрос от Потребителя данных СМЭВ4 с отдельным блоком параметров
datamart: fias
mnemonic: addrobj_view
majorVersion: 1
minorVersion: 0
params:{ “type”: “STRING”, “value”:”001”},{ “type”: “STRING”, “value”:“002”},{ “type”: “TIMESTAMP”, “value”:“2007-12-03Т10:00:00.000Z”}

// Определение РЗ
SELECT oktmo, formalname, startdate, enddate FROM datamart.9.1.addrobj WHERE areacode=? and citycode=? and startdate<=?

  1. Регламентированный SQL-запрос с параметром типа DATE:

// Исходный запрос от Потребителя данных СМЭВ4
select * from fias.1.0.addrobj_view('001', '000', '1970-01-01')

// Исходный запрос от Потребителя данных СМЭВ4
CALL fias.1.0.addrobj_view('001', '000', '1970-01-01')

// Исходный запрос от Потребителя данных СМЭВ4 с отдельным блоком параметров
datamart: fias
mnemonic: addrobj_view
majorVersion: 1
minorVersion: 0
params:{ “type”: “STRING”, “value”:”001”},{ “type”: “STRING”, “value”:“002”},{ “type”: “DATE”, “value”:“2007-12-03”}

// Определение РЗ
SELECT oktmo, formalname, startdate, enddate FROM datamart.9.1.addrobj WHERE areacode=? and citycode=? and startdate>=?

  1. Регламентированный SQL-запрос без параметров:

// Исходный запрос от Потребителя данных СМЭВ4:
select * from egrul.1.1.legalentity_view()

// Пример преобразования исходного запроса в соответствии с загруженным определением Регламентированного SQL-запроса:
select ogrn, short_name, inn, kpp, region_code from egrul.2.legalentity

  1. Распределенный Регламентированный SQL-запрос:

// Исходный запрос от Потребителя данных СМЭВ4:
select * from podd.1.1.r_query(‘Москва’, 18)

// Пример преобразования исходного запроса в соответствии с загруженным определением Регламентированного SQL-запроса:
select ao.oktmo, o.name, o.kod from fias.1.0.addrobj ao LEFT JOIN oktmo.1.0.oktmo o on ao.oktmo = o.kod2 WHERE ao.offname= ‘Москва’ AND o.regionid = 18

3.2.3. Выполнение запроса с системным параметром

Системные параметры не описываются в определении Регламентированного SQL-запроса и могут быть заданы Потребителем для Регламентированного SQL-запроса при выполнении запроса.

Таблица 3.3 содержит поддерживаемые в СМЭВ4 параметры.

Таблица 3.3 Поддерживаемые в СМЭВ4 параметры

№

Мнемоника

Назначение

Минимальная версия Агента СМЭВ4 на стороне Потребителя данных

1

settings_for_system_time

Системный параметр для получения актуальных на заданный момент данных.

Позволяет указывать при вызове запроса момент времени, на который требуется получить актуальные данные из Витрины.

3.0.0

2

settings_for_system_time_started

Системный параметр для получения результата выполнения запроса с данными, добавленными за указанный диапазон времени.

Позволяет указывать при вызове запроса диапазон номеров дельт, за который требуется получить измененные данные

3.18.0

3

settings_for_system_time_finished

Системный параметр для получения результата выполнения запроса с данными, удаленными за указанный диапазон времени.

Позволяет указывать при вызове запроса диапазон номеров дельт, за который требуется получить удаленные данные

4

settings_for_system_time_cn

Системный параметр для получения данных на указанный номер операции

5

settings_for_system_time_started_cn

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

6

settings_for_system_time_finished_cn

Системный параметр для получения результата выполнения запроса с данными, удаленными за указанный диапазон номеров операций.

7

settings_get_cn

Системный параметр для получения номера версии данных CN на заданный момент времени. Задаётся при вызове SQL-РЗ категории «Рассылка (для Компонента «Витрина данных» версии 2.x)»

3.24.0

Вызов Регламентированного SQL-запроса с системным параметром осуществляется аналогично вызову Регламентированного SQL-запроса с заданием значения для именованного параметра, в соответствии со следующими правилами (данные, подходящие под условия РЗ, которые были и добавлены, и удалены в переданном диапазоне settings_for_system_time_started/ settings_for_system_time_finished, не попадают в результат запроса):

  1. Параметр задается в запросе только один раз в виде именованного параметра с соответствующей мнемоникой.

  2. Значение параметра settings_for_system_time должно соответствовать формату YYYY-MM-DD hh:mm:ss.

  3. Значение параметров settings_for_system_time_started и settings_for_system_time_finished должно соответствовать формату:

    3.1. При передаче диапазона дельт - (int1, int2). Значение int1 должно быть меньше, чем int2.

    3.2. При передаче диапазона timestamp – (YYYY-MM-DD hh:mm:ss, YYYY-MM-DD hh:mm:ss)/. Значение1 в переданном диапазоне должно быть меньше значения2

  4. Задание параметра недоступно при вызове Регламентированного SQL-запроса без SQL-выражения.

  5. Для Витрин, к которым обращается Регламентированный SQL-запрос с данным параметром, должна быть задана настройка поддержки обработки данного параметра в соответствии с Раздел 1.5.3.

  6. В подзапросе в блоке FROM должна отсутствовать конструкция «FOR SYSTEM_TIME».

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

// вызываемый SQL-запрос (вариант 1)
select * from fias.1.0.addrobj_func(p1=>'000', p2=>'001', settings_for_system_time=>'YYYY-MM-DD hh:mm:ss')

// вызываемый SQL-запрос (вариант 2)
select * from fias.1.0.addrobj_func(settings_for_system_time=>?, p1=>?, p2=>?)
params: {"type": "TIMESTAMP", "value": "YYYY-MM-DD hh:mm:ss"},{"type": "STRING", "value": "001"},{"type": "STRING", "value": "002"}

// SQL-выражение Регламентированного SQL-запроса
SELECT <атрибуты> FROM <витрина>.<таблица> WHERE id=:p1 AND region=:p2

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

// вызываемый SQL-запрос (вариант 1)
select * from fias.1.0.addrobj_func(p1=>'000', p2=>'001', settings_for_system_time_started=>'122,124')
select * from fias.1.0.addrobj_func(p1=>'000', p2=>'001', settings_for_system_time_finished=>'122,124')

// вызываемый SQL-запрос без настроек через JDBC-интерфейс
call fias.1.0.addrobj_func(p1=>'000', p2=>'001', settings_for_system_time_started=>'122,124')

// вызываемый SQL-запрос с параметрами, передаваемыми отдельным блоком
select * from fias.1.0.addrobj_func(settings_for_system_time_finished=>?, p1=>?, p2=>?)
params: {"type": "STRING", "value": "122,124"},{"type": "STRING", "value": "001"},{"type": "STRING", "value": "002"}

// SQL-выражение РЗ
SELECT <атрибуты> FROM <витрина>.<таблица> WHERE id=:p1 AND region=:p2

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

curl --location 'http://10.81.7.90:29152/regulated-query' \
--header 'Accept-Version: 1' \
--header 'Content-Type: application/x-www-form-urlencoded; encoding=utf-8' \
--data-urlencode 'datamart=demo_view_repl' \
--data-urlencode 'mnemonic=sub_demo' \
--data-urlencode 'priority=NORMAL' \
--data-urlencode 'majorVersion=1' \
--data-urlencode 'minorVersion=0' \
--data-urlencode 'params={"name": "settings_get_cn","type": "LONG", "value": "1761032149726000"}'

// вызываемый SQL-запрос с параметром, передаваемым отдельным блоком
SELECT id, col1, col2, 0 as sys_op FROM fias.addr_obj FOR SYSTEM_TIME STARTED CN (:fias_addr_obj_cn1, :fias_addr_obj_cn2) as obj_add_alias
UNION ALL
SELECT id, null, null, 1 as sys_op FROM fias.addr_obj FOR SYSTEM_TIME FINISHED CN (:fias_addr_obj_cn1, :fias_addr_obj_cn2) as obj_del_alias

params: "name": "settings_get_cn","type": "LONG", "value": "1734072685055000"}

3.2.4. Выполнение запросов с использованием табличных параметров, передаваемых Потребителем данных для обогащения

Выполнение запроса, включающего табличный параметр, осуществляется аналогично выполнению любого запроса к Витрине Поставщика данных. Описание синтаксиса выполнения запроса приведено в Раздел 3.1.

Для выполнения запроса с табличным параметром необходимо:

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

  2. Указать запрос, содержащий табличный параметр.

  3. Указать источник данных для табличного параметра.

Эти операции могут быть выполнены с использованием REST или JDBC-интерфейса.

Данная функциональность доступна при выполнении следующих условий:

  • на стороне Потребителя установлен Агент СМЭВ4 версии не ниже 3.0.0

  • на стороне Поставщика:

    • установлена Витрина версии 1.12.0-1.17.0 и Агент не ниже 3.0.0

    • установлена Витрина версии не ниже 2.0.0 и Агент не ниже 3.20.0

3.2.4.1. Запрос с использованием REST-интерфейса

При использовании REST-интерфейса данные собираются в CSV файл, который прикрепляется к запросу, содержащему информацию о структуре таблицы и SQL-выражение. Формат запроса приведен в Раздел 2.3.1.2.

В теле запроса передаются следующие параметры:

sql:SELECT el.inn, er.region_name FROM @inns el LEFT JOIN egrul.2.region_codes er ON SUBSTRING(el.inn,1,2) = er.region_code
priority:NORMAL
tableParams:{“name”: “inns”, “columns”:[{“name”: “id”, “type”: “INTEGER”},{“name”: “inn”, “type”: “STRING”}]}
inns:<l.csv>

где:

  1. sql – текст для вызова Регламентированного SQL-запроса, содержащего табличные параметры;

  2. tableParams – описание передаваемого файла с данными для табличного параметра, где:

    • name – табличный параметр;

    • columns – перечень названий столбцов и их типов, содержащихся в файле с данными для табличного параметра.

  3. inns – файл с данными для табличного параметра, где:

    • inns – табличный параметр (выступает в качестве названия параметра запроса);

    • <1.csv> – файл в формате CSV (поддерживаемый формат), передаваемый в параметре запроса.

Пример CSV файла (разделитель – запятая):

1, 4345310593
2, 4311003795
3, 4345336320

3.2.4.2. Запрос с использованием JDBC-интерфейса

При использовании JDBC-интерфейса для описания передаваемой в качестве параметра таблицы и добавления данных расширяются функции драйвера JDBC. Для доступа к данным формируется итератор.

После передачи данных выполняется запрос, включающий табличный параметр в формате @имя_параметра.

Пример использования представлен в Раздел 2.3.2.1.

3.2.5. Получение двоичных объектов в результатах запроса

СМЭВ4 предоставляет возможность получения в качестве результата выполнения Регламентированных SQL-запросов:

  • скалярных параметров (значение которых представляет собой число, строку или дату);

  • двоичных объектов (соответствующих файлам, размещенным на Витринах Потребителей данных).

Для получения в качестве ответа двоичных объектов необходимо выполнение следующих условий:

  • Витрина Поставщика данных поддерживает тип данных «двоичный объект»;

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

Описание процесса выполнения такого SQL-запроса приведено далее.

  1. ИС Потребителя передаёт SQL-запрос в Агент СМЭВ4.

  2. Далее приём, обработка и передача запроса:

    Агент Потребителя данных → Ядро СМЭВ4 → Агент Поставщика данных → Витрина Поставщика данных осуществляется аналогично обычному информационному обмену с использованием Регламентированных SQL-запросов (Раздел 1.4.1).

  3. Витрина данных осуществляет обработку запроса и возвращает ответ.

    В случае выполнения запроса, результат которого содержит атрибуты с типом данных «двоичный объект», в составе результата запроса атрибут может принимать одно из следующих возможных значений:

    • непосредственно сам двоичный объект;

    • уникальная ссылка на получение двоичного объекта с Витрины Поставщика данных (см. шаги Рисунок - 3.1).

    Решение о том, какое значение будет передано, (объект или ссылка на него) принимается Витриной данных.

  4. Далее ответ доставляется до ИС Потребителя аналогично обычному обмену (Раздел 1.4.1).

    Пример возврата двоичного объекта и ссылки на двоичный объект приведен в Раздел 2.3.1.1.3.

  5. Если в результате выполнения запроса передана ссылка, то для получения двоичного объекта ИС Потребителя направляет запрос на получение вложения по ссылке, которую получил в ответе.

    Запрос двоичного объекта по ссылке считается отдельным обменом, идентификатор обмена (requestId) запроса по ссылке уникальный (в случае нескольких ссылок - уникальный для каждой из ссылок).

    Описание запроса на получение двоичного объекта по ссылке:

    • через REST-интерфейс приведено в Раздел 2.3.1.3;

    • через JDBC-интерфейс приведено далее.

    Примечание

    Ссылки для получения двоичного объекта имеют время жизни, которое определяется таймаутом запроса на получение ссылок (см. пункт 1) плюс значением настройки времени жизни Ядра СМЭВ4 (10 минут).

  6. Далее приём, обработка и передача запроса Агент Потребителя данных → Ядро СМЭВ4 → Агент Поставщика данных → Витрина Поставщика данных осуществляется аналогично обычному обмену (Раздел 1.4.1). Для передачи запроса двоичного объекта на Витрину Поставщика используется специальный топик blob.rq.

  7. В случае если в теле запроса содержится ссылка на двоичный объект:

    • Адаптер PODD Витрины данных отправляет запрос в BLOB-адаптер на получение этого файла.

    • BLOB-адаптер считывает ссылку на двоичный объект и обращается в Хранилище BLOB-объектов на стороне Ведомства.

    • После получения двоичного объекта возвращает его в СМЭВ4.

    Для передачи ответа на запрос двоичного объекта от Витрины Поставщика данных используются специальные топики blob.rs и blob.err.

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

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

Пример программного кода для JDBC-драйвера, реализующего получение двоичного объекта:

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 `ожидается успешное получение бинарных данных `() {
        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))
        }
    }
}
Информационный обмен при выполнении запроса с использованием СМЭВ4

Рисунок - 3.1 Информационный обмен при выполнении запроса с использованием СМЭВ4

3.2.6. Получение печатной формы в результатах запроса

Запросы для получения печатной формы в результатах запроса не содержат SQL-выражения в определении Регламентированного SQL-запроса и являются процедурами, выполняемыми на стороне Витрины.

В запросе обязательно передается параметр с указанием типа или нескольких типов формируемых документов:

  • xml – формируется файл, содержащий отчет и присоединенную подпись;

  • pdf – формируется файл, содержащий отчет без подписи;

  • xml_detached_sig – формируется файл xml-отчета и файл с открепленной подписью;

  • pdf_sig - формируется файл pdf -отчета и файл с открепленной подписью.

Примечание

Перечень поддерживаемых типов документов зависит от настроек Сервиса Формирования документов типового ПО Витрина данных, выполненных Поставщиком.

Приём, обработка и передача запроса по пути Агент Потребителя данных → Ядро СМЭВ4 → Агент Поставщика данных осуществляется аналогично обычному информационному обмену с использованием Регламентированных SQL-запросов (Раздел 1.4.1).

Пример вызова запроса печатной формы:

select * from <мнемоника Витрины>.<версия SQL-РЗ>.<мнемоника SQL-РЗ>('pdf_sig, xml', '<значение опционального параметра>')

3.2.7. Выполнение запроса с текстовым поиском

Функция текстового поиска позволяет искать данные внутри текстовых полей таблиц по ключевым словам или фразам. Поиск выполняется на уровне Витрины данных.

Описание поддерживаемых функций и операторов приведено в Раздел 3.1. Подробное описание данного функционала приведено в Информационно-методическом справочнике ядра типового ПО витрин данных НСУД — Prostore.

Для Витрин c версией компонента query-execution (Prostore) ниже 7.1, к которым обращается Регламентированный SQL-запрос, должна быть задана настройка subQueryParamSupport=NOT_SUPPORTED в соответствии с Раздел 1.5.3.

Функция текстового поиска доступна для любых Регламентированных запросов типа «SQL-запрос».

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

// Исходный запрос от Потребителя данных СМЭВ4:
select * from demo_view_test.5.0.passenger(‘Иван’)

// Пример преобразования исходного запроса в соответствии с загруженным определением Регламентированного SQL-запроса:
select code, id, lastname, firstname, middlename, birthday from demo_view_test.5.0.passenger where (to_tsvector('russian', lastname) @@ plainto_tsquery('russian', 'Иван'))

3.2.8. Выполнение запроса к виртуальному кластеру

Виртуальный кластер может быть указан в блоке FROM так же, как и обычная таблица или витрина. Ядро СМЭВ4 при построении плана исполнения запроса заменяет виртуальный кластер на витрины и отправляет к ним параллельно подзапросы.

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

// исходный запрос
select * from virtualCluster.1.0.students

// Пример преобразования исходного запроса в подзапросы к витринам, входящим в кластер:
select * from dtm01.1.0.students
select * from dtm02.1.0.students
select * from dtm03.1.0.students

При обработке SQL-запроса, содержащего виртуальный кластер, система анализирует его структуру и применяет одну из двух стратегий исполнения:

  • План А: активируется при наличии JOIN с диспетчерской витриной (витриной маппинга). Этот план срабатывает только если запрос содержит операцию JOIN, в которой участвует специальная диспетчерская витрина (витрина ЦП), содержащая атрибут linkingRecord. Диспетчерская витрина — это служебная витрина, которая хранит связи (маппинг) между разными идентификаторами одной сущности из различных источников (например, внутренний федеральный ID и региональные ID). В её метаданных отмечен атрибут linkingRecord, указывающий на столбец с именами (мнемониками) витрин-источников. Система автоматически добавляет в каждый подзапрос к витрине кластера условие фильтрации (AND source_mnemonic = „мнемоника_витрины“). Это гарантирует, что каждая витрина кластера соединится только со «своими» записями маппинга, предотвращая некорректное перекрёстное соединение.

  • План Б: используется во всех остальных случаях. Этот план применяется по умолчанию, если в запросе нет JOIN с диспетчерской витриной, помеченной linkingRecord. Сценарии использования:

    • Простой запрос данных из всего кластера.

    • Запрос с фильтрацией (WHERE).

    • JOIN кластера с обычными справочными витринами.

Система реализует параллельный опрос всех источников в кластере и корректное объединение результатов согласно выбранной стратегии.

3.3. Выполнение запросов к REST-сервису ИС Ответчика

Для выполнения запроса к REST-сервису ИС Ответчика необходимо:

  1. Определить доступные REST-сервисы.

  2. Добавить к запросу опциональные заголовки:

    • клиентский идентификатор, передаётся в опциональном заголовке ClientRequestID (тип string), см. Раздел 3.4 данного документа;

    • для передачи мнемоники Инициатора в REST-сервис ответчика в спецификации OpenAPI REST-сервиса Ответчика должен присутствовать обязательный заголовок X-PODD-CLIENT-SYSTEM-MNEMONIC;

    • пользовательский таймаут (предельное время ожидания выполнения запроса), передается в опциональном заголовке Request-Timeout. Значение указывается в секундах, максимальное значение 24 часа. В случае отсутствия параметра в запросе используется таймаут, заданный в конфигурации Агента СМЭВ4 (по умолчанию 20 секунд).

  3. Составить URI запроса в соответствии со спецификацией OpenAPI зарегистрированного REST-сервиса ИС Ответчика, загруженной в СМЭВ4.

URI запроса формируется путём конкатенации мнемоники Агента Ответчика, префикса в URL (basePath) соответствующего REST-сервиса ИС Ответчика и path операции. Сформированный запрос должен совпадать с запросом из спецификации OpenAPI.

Формат запроса для обмена с использованием REST-сервиса ИС Ответчика имеет вид:

<HTTP-метод> <адрес>:<порт>/<systemMnemonic><basePath><path>

где:

  • HTTP-метод – метод из поддерживаемых REST-сервисом;

  • <адрес> – IP-адрес Агента Инициатора;

  • <порт> – порт для обращения Агента Инициатора к Ядру СМЭВ4 в соответствии с «Руководством администратора СМЭВ4»;

  • systemMnemonic – мнемоника Агента Ответчика, на стороне которого развернут REST-сервис;

  • basePath – префикс в URL соответствующего REST-сервиса ИС Ответчика;

  • path – путь операции, указанный в спецификации OpenAPI соответствующего REST-сервиса ИС Ответчика.

Пример URI запроса соответствует примеру спецификации OpenAPI, приведенному в Раздел 1.5.6 данного документа:

GET 10.81.4.30:29164/agent-oktmo/region-service/api/v1.0/letters/{mailId}/{date}/pdf

Выполнение запросов осуществляется через REST-интерфейс Агента СМЭВ4 (см. Раздел 2.3.3 данного документа).

3.4. Сквозная идентификация запросов

Для диагностики проблем, возникающих в ходе информационных обменов через СМЭВ4 в части отслеживания всей цепочки сообщений, возникающих в ходе информационного обмена, обеспечена сквозная идентификация запросов.

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

Сквозная идентификация в СМЭВ4 основывается на идентификаторах, приведённых в Таблица 3.4.

На Рисунок - 3.2, Рисунок - 3.3 и Рисунок - 3.4 приведён порядок возникновения этих идентификаторов.

Таблица 3.4 Виды идентификаторов СМЭВ4

№

Вид

Код

Источник идентификатора

1

Клиентский идентификатор

(идентификатор клиента)

clientRequestId

Инициатор обмена

2

Идентификатор обмена

(идентификатор процесса)

requestId

СМЭВ4 при получении запроса на:

  • информационный обмен (например, выполнение регламентированного SQL-запроса)

  • процесс (например, регистрации подписки)

Витрина данных:

  • если является инициатором обмена (например, уведомление о наличии новой дельты)

  • если происходит манипуляции данными без участия СМЭВ4 (например, загрузка в таблицу)

3

Идентификатор подзапроса СМЭВ4 – Витрина

subRequestId

СМЭВ4

4

Идентификатор подзапроса Адаптер – Prostore

dataRequestId

Адаптер Витрины
Сквозная идентификация запросов для информационного обмена с использованием регламентированных SQL-запросов

Рисунок - 3.2 Сквозная идентификация запросов для информационного обмена с использованием регламентированных SQL-запросов

Сквозная идентификация запросов для информационного обмена с использованием запросов к REST-сервису ИС Ответчика

Рисунок - 3.3 Сквозная идентификация запросов для информационного обмена с использованием запросов к REST-сервису ИС Ответчика

Сквозная идентификация запросов для информационного обмена с использованием Рассылок

Рисунок - 3.4 Сквозная идентификация запросов для информационного обмена с использованием Рассылок

Правила использования клиентского идентификатора

  1. Клиентский идентификатор опционален.

    Исключение из правила – УВ явно добавил обязательное поле ClientRequestID в спецификацию OpenAPI для информационного обмена с использованием Регламентированных REST-запросов. В данном случае валидация осуществляется в соответствии со спецификацией.

  2. Клиентский идентификатор должен соответствовать стандарту UUID.

  3. Ответственность за используемый формат несёт инициатор обмена. СМЭВ4 не осуществляет проверку по формату и версиям UUID.

    Исключение из правила – УВ явно добавил поле ClientRequestID в спецификацию OpenAPI для информационного обмена с использованием Регламентированных REST-запросов. В данном случае, валидация осуществляется в соответствии со спецификацией.

  4. Допустимо использовать один клиентский идентификатор для связывания нескольких запросов. СМЭВ4 не осуществляет проверку на уникальность.

  5. Способ передачи клиентского идентификатора приведён в Раздел 2.3.

3.5. Лимитирование регламентированных запросов Потребителя к информационным ресурсам Поставщика

3.5.1. Лимиты

Для защиты Поставщиков от избыточных запросов Потребителей обеспечена возможность лимитирования запросов к Поставщику данных от конкретного Потребителя данных для информационных обменов с использованием регламентированных запросов.

Данная функциональность доступна для Поставщиков, на стороне которых установлен Агент СМЭВ4 версии не ниже 3.10.0.

Лимит может быть установлен на следующие информационные ресурсы Поставщика:

  • на конкретный Регламентированный SQL-запрос;

  • на все Регламентированные SQL-запросы к конкретной Витрине;

  • на конкретный Регламентированный REST-запрос (спецификацию OpenAPI ИС Поставщика);

  • общий на все Регламентированные SQL и REST-запросы от ИС Потребителя к ИС Поставщика.

Лимит может быть следующих типов:

  • на Количество запросов;

  • на Размер запросов;

  • на Размер ответов.

При создании лимита указывается его значение (количество или размер) и период (у которого два назначения – период контроля соблюдения значения и период блокировки).

3.5.2. Условия для добавления лимитов

  1. В СМЭВ4 должны быть зарегистрированы ИС Поставщика и ИС Потребителя;

  2. Если лимит задаётся на Витрину в СМЭВ4 должны быть выполнены условия:

    • зарегистрирована Витрина;

    • Витрина связана с ИС Поставщика;

  3. Если лимит задаётся на конкретный Регламентированный SQL-запрос, в СМЭВ4 должны быть:

    • зарегистрирована Витрина;

    • Витрина связана с ИС Поставщика;

    • выданы права ИС Потребителя на Регламентированный SQL-запрос.

  4. Если лимит задаётся на конкретную спецификацию OpenAPI в СМЭВ4 должны быть:

    • зарегистрирована спецификация OpenAPI;

    • выданы права ИС Инициатора на спецификацию OpenAPI.

  5. При выставлении лимитов недопустимо совмещение:

    • общего на все Регламентированные SQL и REST-запросы ИС Потребителя к ИС Поставщика лимита и лимита на другие ресурсы;

    • лимита на Витрину и лимита на Регламентированный SQL-запрос к этой Витрине.

  6. Лимит на конкретный Регламентированный SQL-запрос ограничивает запросы Потребителя по всем версиям этого запроса.

  7. Лимит на все Регламентированные SQL-запросы к конкретной Витрине ограничивает запросы Потребителя по всем версиям модели этой Витрины.

  8. При установке лимита на Витрину и ИС также могут учитываться произвольные SQL-запросы. Реализация исключения таких запросов из процесса лимитирования не предусмотрена, так как права доступа на выполнение произвольных SQL-запросов предоставляются автоматически и только владельцам Витрин на их собственные Витрины.

  9. Период наблюдения любого лимита должен быть 10 или более секунд.

3.5.3. Блокировки

В случае превышения лимитов, заданных Поставщиком, СМЭВ4 блокирует Потребителю доступ к соответствующему информационному ресурсу. Например, если для ИС Потребителя указано два лимита к двум Регламентированным SQL-запросам и заблокирован доступ к одному из них, она может продолжить пользоваться другим доступным запросом. При получении запроса от заблокированного Потребителя СМЭВ4 возвращает ответ с соответствующей ошибкой. Блокировка снимается:

  • при истечении времени блокировки;

  • при удалении соответствующего лимита;

  • при редактировании соответствующего лимита (любых атрибутов, кроме наименования);

  • при получении запроса на принудительное снятие блокировки.

3.5.4. Управление лимитами и блокировками

Управление лимитами и блокировками доступно из ЛК УВ.

3.5.5. Алгоритм лимитирования

Лимитирование осуществляется в соответствии со следующим алгоритмом (Рисунок - 3.5):

  1. СМЭВ4 формирует окна наблюдения от 1 января 1970 года 00:00:00.000 в соответствии с указанным значением периода лимита.

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

  3. СМЭВ4 вычисляет счётчик, инкрементируя значение при каждом полученном запросе.

  4. СМЭВ4 принимает решение о блокировке на основании имеющихся счётчиков:

    • Если значения предыдущего окна наблюдения нет, то берётся значение инкрементированного счётчика текущего окна.

    • Если полученное значение меньше значения лимита, то запрос будет обработан.

    • Если значение предыдущего окна наблюдения есть, то СМЭВ4 вычисляет коэффициенты наложения окна наблюдения на интервалы по формуле:

K = N + M * R
где:
- N - количество запросов в текущем интервале (с учетом полученного),
- M - количество запросов на предыдущем интервале,
- R - коэффициент наложения на предыдущий интервал (0...1).

  • Если полученное значение меньше значения лимита, то запрос будет обработан.

Пример:

Установлен лимит: 4 запроса в минуту
С 0 до 0:59 - пришло 5 запросов,
В 1:30 - пришёл ещё один запрос

результат вычисления:
- N = 1,
- M = 5,
- R = (90 - 60) / 60 = 0.5

K = 1 + 5 * 0.5 = 3.5 меньше предельного, запрос будет обработан.
Алгоритм лимитирования запросов

Рисунок - 3.5 Алгоритм лимитирования запросов

3.6. Подтверждение неизменности данных, передаваемых при обменах по регламентированным запросам

Функционал «подтверждения неизменности данных» включает в себя:

  • формирование Агентами СМЭВ4 комплексной электронной подписи данных для запросов и ответов, состоящих из нескольких сегментов (далее – комплексная ЭП сегментированных данных) (дробление на сегменты выполняется автоматически исходя из размера передаваемых данных);

  • сохранение в хранилище на стороне участника обмена данных, для возможности подтверждения неизменности данных запроса и ответа (тел запросов и ответов, их электронных подписей и идентифицирующих атрибутов обмена).

Возможность подтверждения неизменности может быть обеспечена для данных, передаваемых:

  • при обменах с использованием Регламентированных SQL-запросов (в том числе при запросе двоичного объекта по ссылке, полученной в результате SQL-РЗ, для которого обеспечивается подтверждение неизменности данных);

  • при обменах с использованием Рассылок для Компонента «Витрина данных» версии 2.x (при SELECT-запросе данных определенной версии (с заданным диапазоном CN));

  • при обменах с использованием запросов к REST-сервису ИС Ответчика.

3.6.1. Настройка подтверждения неизменности данных для регламентированных запросов

По умолчанию возможность подтверждения неизменности данных не обеспечивается, но может быть включена одним или каждым участником обмена для конкретного SQL-РЗ или REST-РЗ.

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

Для включения функционала подтверждения неизменности данных участнику обмена необходимо выполнить настройки для регламентированного запроса, в соответствии с описанием Раздел 3.6.1.1 или Раздел 3.6.1.2.

3.6.1.1. Настройка подтверждения неизменности данных на стороне Потребителя

Участник с ролью Потребителя/ Инициатора выполняет настройку подтверждения неизменности данных для обменов по SQL-РЗ и REST-РЗ в конфигурационном файле Агента СМЭВ4.

Для этого задается перечень SQL-РЗ и REST-РЗ, по которым требуется подтверждение неизменности данных (подробнее описание настроек для функционала подтверждения неизменности данных приведено в «Руководстве администратора Агента СМЭВ4»).

Значения в перечне SQL-РЗ могут задаваться в формате:

  • <мнемоника Витрины>.<majorVersion>.<minorVersion>.<мнемоника SQL-РЗ>;

  • <мнемоника Витрины>.<majorVersion>.<мнемоника SQL-РЗ>;

  • <мнемоника Витрины>.<мнемоника SQL-РЗ>.

При указании в перечне SQL-РЗ с версией, подтверждение неизменности данных будет обеспечено, только если при вызове SQL-РЗ передана та же версия в том же формате.

Указание в перечне SQL-РЗ без версии (<мнемоника Витрины>.<мнемоника SQL-РЗ>) приведет к сохранению в хранилище Потребителя данных обменов по всем вызываемым версиям SQL-РЗ.

Значения в перечне REST-РЗ должны задаваться в формате:

  • /<мнемоника ИС Поставщика>/<basePath>/<path>

Указание <path> опционально, но стоит учитывать, что чем детальнее указан путь в перечне REST-РЗ (чем больше сегментов пути), тем меньше вероятность случайных совпадений с запросами, для которых подтверждение неизменности данных не требуется.

3.6.1.2. Настройка подтверждения неизменности данных на стороне Поставщика

Участник с ролью Поставщик определяет необходимость подтверждения неизменности данных для обменов по SQL-РЗ путем указания соответствующего признака при регистрации или изменении версии Регламентированного SQL-запроса через ЕИП НСУД в соответствии с инструкцией по работе с ФГИС «ЕИП НСУД».

Участник с ролью Ответчик определяет необходимость подтверждения неизменности данных для обменов по REST-РЗ путем указания соответствующего признака при регистрации REST-сервиса через ЛК УВ в соответствии с инструкцией в документе «Руководство пользователя ЛК УВ».

Если Поставщиком / Ответчиком задан признак необходимости подтверждения неизменности данных для регламентированного запроса, то в его хранилище будут сохранены данные обменов со всеми Потребителями /Инициаторами, обращающимися к регламентированному запросу.

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

Возможность подтверждения неизменности данных обеспечивается при следующих условиях:

  • на стороне участников обмена установлен Агент СМЭВ4 версии «3.25.0» и выше;

  • (для ответов на SQL-РЗ) на стороне Поставщика данных установлен компонент «Витрина данных» версии «2.0» и выше;

  • на стороне участника обмена развернуто хранилище данных (БД СУБД ClickHouse или сертифицированное S3-хранилище);

  • выполнены настройки Агента СМЭВ4 по подключению к хранилищу (описание настроек для подтверждения неизменности данных приведено в «Руководстве администратора Агента СМЭВ4»).

Если Поставщик/Ответчик не может обеспечить формирование комплексной ЭП сегментированных данных, то:

  • обмены по регламентированному запросу не прерываются;

  • в хранилище участника, инициировавшего подтверждение неизменности данных, сохраняются данные ответа без ЭП (только тело и идентифицирующие атрибуты).

Если Потребитель/Инициатор не может обеспечить формирование комплексной ЭП сегментированных данных, то обмены по регламентированному запросу не выполняются, в ответ на запрос возвращается ошибка.

Если данные запроса и ответа состоят из одного сегмента, то формирование комплексной ЭП не требуется, для подтверждения неизменности данных используется ЭП единственного сегмента.

Примечание

Если при сохранении данных для подтверждения неизменности данных возникла ошибка, обмен по регламентированному запросу не прерывается.

3.6.3. Состав данных, сохраняемых в хранилище участника обмена

При включении функционала подтверждения неизменности данных для регламентированного запроса и при соблюдении условий, приведенных в Раздел 3.6.2, в хранилище участника сохраняются следующие данные:

  • ЭП данных запроса и ответа (в том числе комплексные ЭП для сегментированных данных)

  • Тела запроса и ответа (в машиночитаемом формате для возможности проверки ЭП)

  • Сертификат, которым были подписаны данные запроса и ответа (для возможности проверки ЭП)

  • Идентифицирующие атрибуты обмена:

    • Идентификатор обмена;

    • Идентификатор подзапроса по SQL-РЗ (при наличии);

    • Клиентский идентификатор (при наличии);

    • Идентификатор табличного параметра (при наличии);

    • Идентификатор запроса двоичного объекта по ссылке (при наличии);

    • Тип сообщения (запрос/ответ);

    • Мнемоника ИС Потребителя / Инициатора;

    • Мнемоника регламентированного запроса (при наличии);

    • Мнемоника ИС Поставщика / Ответчика (при наличии).

3.6.4. Выгрузка данных из хранилища участника обмена

Выгрузка данных из локального хранилища участника может быть выполнена напрямую с использованием SQL-клиентов для Clickhouse и S3-клиентов для S3-хранилища.

Для получения данных из удаленного хранилища участника возможно использование специального запроса на выгрузку к REST-сервису Агента в контуре Ядра СМЭВ4, с префиксом в URL «/legal_evidence (далее – «технический REST-РЗ»). Права доступа к техническому REST-РЗ выдаются ИС по запросу к службе эксплуатации СМЭВ4.

3.6.4.1. Выполнение запроса на выгрузку из удаленного хранилища

Выполнение запроса на выгрузку данных из удаленного хранилища участника

Рисунок - 3.6 Выполнение запроса на выгрузку данных из удаленного хранилища участника

Выгрузка данных через технический REST-РЗ доступна только ИС – владельцу хранилища.

Для выполнения технического REST-РЗ необходимо использовать экземпляр Агента СМЭВ4, в конфигурации которого отключено сохранение данных в хранилище (описание настроек для функционала подтверждения неизменности данных приведено в «Руководстве администратора Агента СМЭВ4»).

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

GET <адрес >:<порт>/<systemMnemonic>/legal_evidence/api/v1/inf-system /<infSystemMnemonic>/exchange/<id>?includeDecodedData=true&includeBase64Data=true
X-PODD-CLIENT-SYSTEM-MNEMONIC: <infSystemMnemonic>
X-PODD-CLIENT-USER-ID: <userName>

где:

  • <адрес>:<порт> – IP-адрес и порт Агента ИС Инициатора;

  • <systemMnemonic> – мнемоника Агента в контуре Ядра СМЭВ4 (Ответчика по техническому REST-РЗ);

  • <infSystemMnemonic> – мнемоника ИС – владельца хранилища, из которого запрашиваются данные;

  • <id> – идентификатор обмена, по которому необходимо выгрузить данные;

  • includeDecodedData – опциональный параметр запроса с признаком необходимости включения в ответ тел запроса/ответа, форматированных в человекочитаемый вид;

  • includeBase64Data – опциональный параметр запроса с признаком необходимости включения в ответ данных в формате Base64;

  • X-PODD-CLIENT-SYSTEM-MNEMONIC – обязательный заголовок с мнемоникой ИС, инициировавшей запрос (совпадает с ИС владельца хранилища);

  • X-PODD-CLIENT-USER-ID – обязательный заголовок с ФИО пользователя, инициировавшего запрос.

3.6.4.2. Состав данных в результате выгрузки из удаленного хранилища

В результате выполнения технического REST-РЗ возвращается ответ, содержащий бинарные данные zip-файла, содержащего следующую структуру данных.

Каталог <requestId> с вложенными каталогами:

  • sqlRequest-<requestId> – информация для подтверждения неизменности данных запроса по SQL-РЗ;

  • sqlResponse-<requestId> – информация для подтверждения неизменности данных ответа по SQL-РЗ;

  • sqlSubRequest-<subRequestId> – информация для подтверждения неизменности данных подзапроса;

  • sqlSubResponse-<subRequestId> – информация для подтверждения неизменности данных ответа на подзапрос;

  • tableParam-<tableParamId> – информация для подтверждения неизменности данных табличного параметра;

  • blobRequest-<blobRequestId> – информация для подтверждения неизменности данных запроса blob по ссылке;

  • blobResponse-<blobRequestId> – информация для подтверждения неизменности данных ответа на запрос blob по ссылке;

  • apiGwRequestMeta-<requestId> – информация для подтверждения неизменности метаданных запроса по REST-РЗ;

  • apiGwResponseMeta-<requestId> – информация для подтверждения неизменности метаданных ответа на REST-РЗ;

  • apiGwRequestPayload-<requestId> – информация для подтверждения неизменности данных запроса по REST-РЗ;

  • apiGwResponsePayload-<requestId> – информация для подтверждения неизменности данных ответа на REST-РЗ.

Каждый из вышеперечисленных каталогов содержит подкаталоги LegalEvidence, RawData и DecodedData (опционально, если в запросе был передан includeDecodedData: true).

Каталог LegalEvidence содержит файлы:

  • systemSign.bin –ЭП (бинарные данные)

  • systemSign.base64 – ЭП (данные в Base64 – опционально, если в запросе был передан includeBase64Data: true)

  • certificate.bin – сертификат, используемый для подписания ЭП (бинарные данные)

  • certificate.base64 – сертификат, используемый для подписания ЭП (данные в Base64 - опционально, если в запросе был передан includeBase64Data: true)

  • attributes.json – идентифицирующие атрибуты запроса/ответа:

    • timestamp – дата и время формирования события;

    • requestId – идентификатор обмена;

    • subRequestId – идентификатор подзапроса (при наличии);

    • clientRequestId – клиентский идентификатор (при наличии);

    • tableParamId – идентификатор табличного параметра (при наличии);

    • blobRequestId – идентификатор запроса blob по ссылке (при наличии);

    • messageType – тип события (request/response);

    • queryType – тип запроса (apiGw/sql/blob);

    • queryMnemonic – мнемоника РЗ (при наличии);

    • customerId – мнемоника ИС Потребителя;

    • producerId – мнемоника ИС Поставщика (при наличии).

Каталог RawData содержит файлы:

  • raw_data.bin – бинарные данные запроса / табличного параметра / ответа;

  • raw_data.base64 – данные запроса / табличного параметра / ответа в Base64 (опционально, если в запросе был передан includeBase64Data: true).

Каталог DecodedData содержит файл:

  • decoded_data – данные в человекочитаемом виде.

Примечание

Если тела запроса / табличного параметра / ответа были сохранены в хранилище не полностью, то при выгрузке: - не формируется файл decoded_data; - не формируется файл raw_data; - формируется файл «README» с информацией о неполной выгрузке.

3.6.5. Проверка неизменности данных, сохраненных в хранилище участника

Подтверждение неизменности сохраненных данных осуществляется путем проверки электронной подписи данных.

Существует возможность проверки ЭП с использованием внутреннего интерфейса Агента СМЭВ4 или компонента Notarius, если используются средства криптографии, предоставляемые компонентом (описание настроек подключения к сервису криптографии приведено в «Руководстве администратора Агента СМЭВ4»).

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

curl --location '<адрес>:<порт>/VERIFY' \
--header 'Content-Type: application/json' \
--data '{
"data":"<base64>",
"signature":"<base64>",
"certificate":"<base64>"
}'

где:

  • <адрес>:<порт> – IP-адрес и порт Агента СМЭВ4 (или компонента Notarius);

  • data – обязательный параметр тела запроса, содержащий проверяемые данные в формате base64;

  • signature – обязательный параметр тела запроса, содержащий ЭП в формате base64;

  • certificate – обязательный параметр тела запроса, содержащий сертификат, используемый для подписания, в формате base64;

  • «Content-Type: application/json» – обязательный заголовок для использования json-формата.

Пример ответа:

{
  "success": {
    "verified": true
  },
  "failure": null
}