8. Приложение 1. Описание спецификации
8.1. Спецификация Модуля исполнения запросов
8.1.1. Запрос данных из Витрины
Данная спецификация описывает возможность запроса данных к Витрине, получения успешного ответа на запрос или ошибки, в случае невозможности выполнения запроса, с описанием причины ошибки.
8.1.2. query.rq
query.rq - Топик sql запросов на исполнение
Структура сообщения
datamartExecuteQueryRequestMessage:
description: Исполнение sql запроса на витрине
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор подзапроса
headers:
type: object
properties:
MESSAGE_TYPE:
description: Тип сообщения
type: string
const: DatamartExecuteQueryRequest:0.1
REQUEST_ID:
description: Идентификатор запроса
type: string
QUERY_DEADLINE:
description: Время в миллисекундах от эпохи, до которого запрос должен быть выполнен
type: string
format: int64
AGENT_CONSUMER_ID:
description: Мнемоника потребителя (мнемоника агента)
type: string
QUERY_MNEMONIC:
description: '<Полная мнемоника РЗ>.<версия РЗ>'
type: string
payload:
$ref: '#/components/schemas/datamartExecuteQueryRequest'
examples:
- name: simple
summary: Простой запрос на исполнение без параметров
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from v1_addrobj
parameters: [ ]
namedParams: [ ]
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId: aaa
customerOgrn: ""
queryMnemonic: fias.selectAllAddrobj.1.0
- name: estimation
summary: Запрос на оценку
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 403eada5-05f6-480c-bca9-03328091efeb
subRequestId: 451000b8-dff2-4a1b-ab1b-42500a70d232
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from v1_addrobj
parameters: [ ]
namedParams: [ ]
tableParams: [ ]
isForEstimation: true
rowCountThreshold: 1000
customerId:
string: agent-fias
customerOgrn:
string: "1053600591197"
queryMnemonic:
string: fias.selectAllAddrobj.1.0
- name: complex
summary: Запрос с параметрами
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 68758a92-0027-4258-bf17-aa3d24f85094
subRequestId: 96e6eb99-7ff1-4efa-abae-ef1c5744b723
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from v1_addrobj where oktmo = ? and name = @tbl.fullname
parameters:
- type: STRING
value:
string: asdasdasd
- type: LONG
value: null
namedParams: [ ]
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId:
string: agent-fias
customerOgrn:
string: "1053600591197"
queryMnemonic:
string: fias.selectAddrobjWithParams.1.0
- name: complex_named
summary: Запрос с именованными параметрами
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 12358a92-0027-4258-bf17-aa3d24f85094
subRequestId: 56e6eb99-7ff1-4efa-abae-ef1c5744b723
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from @tbl.fullname el LEFT JOIN v1_addrobj where oktmo = @p1 and kod = @p2
parameters: [ ]
namedParams:
- name: p1
type: STRING
value:
string: asdasdasd
- name: p2
type: LONG
value: null
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId:
string: agent-fias
customerOgrn:
string: "1053600591197"
queryMnemonic:
string: fias.selectAddrobjWithParams.1.0
- name: deadline
summary: Простой запрос на исполнение без параметров
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
QUERY_DEADLINE: 1629289006904
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from v1_addrobj
parameters: [ ]
namedParams: [ ]
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId: agent-fias
customerOgrn: "1053600591197"
queryMnemonic: fias.selectAllWithDeadline.1.0
Avro-схема сообщения
datamartExecuteQueryRequest:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: QueryRequest
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: subRequestId
description: Уникальный идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: replyTo
description: Служебная информация маршрутизации сообщения. Ответ, формируемый витриной, обязан содержать переданное значение без каких либо искажений
type: string
- name: datamartMnemonic
description: Мнемоника витрины, к которой выполняется запрос
type: string
- name: sql
description: SQL запрос на исполнение, либо имя хранимой процедуры для регламентированных запросов
type: string
- name: parameters
description: Параметры к SQL запросу
default: [ ]
type:
type: array
items:
type: record
name: QueryParameter
description: Описание параметра
fields:
- name: type
type: string
description: Тип параметра
enum:
- BIG_DECIMAL
- BINARY
- BOOLEAN
- DATE
- DOUBLE
- FLOAT
- INTEGER
- LONG
- SHORT
- STRING
- TIME
- TIMESTAMP
- name: value
description: Значение параметра
type:
- string
- 'null'
- name: namedParams
description: Именованные параметры запроса
default: [ ]
type:
type: array
items:
type: record
name: NamedParam
description: Описание именованного параметра
fields:
- name: name
description: Имя (мнемоника) параметра
type: string
- name: type
type: string
description: Тип параметра
enum:
- BIG_DECIMAL
- BINARY
- BOOLEAN
- DATE
- DOUBLE
- FLOAT
- INTEGER
- LONG
- SHORT
- STRING
- TIME
- TIMESTAMP
- name: value
description: Значение параметра
type:
- string
- 'null'
- name: tableParams
description: Табличные параметры запроса
default: [ ]
type:
type: array
items:
type: record
name: TableParam
fields:
- name: id
description: Уникальный идентификатор
type:
type: string
logicalType: uuid
- name: name
description: Имя параметра
type: string
- name: columns
description: Описание колонок таблицы
type:
type: array
items:
type: record
description: Описание колонки
name: TableParamColumnInfo
fields:
- name: name
type: string
description: Имя колонки
- name: type
type: string
description: Тип атрибута
enum:
- BIG_DECIMAL
- BINARY
- BOOLEAN
- DATE
- DOUBLE
- FLOAT
- INTEGER
- LONG
- SHORT
- STRING
- TIME
- TIMESTAMP
- name: isForEstimation
description: Признак необходимости вернуть статистику по запросу в качестве результата. В случае, если оценка по результату исполнения sql запроса не превышает rowCountThreshold записей, должен сразу отдаваться результат без отправки оценки в ядро
type: boolean
default: false
- name: rowCountThreshold
description: Максимальное оценочное количество строк результата, при превышении которого возвращается статистика по запросу. Если оценка по запросу не превышет данный параметр, витрина сразу возвращает ответ с результатом. Заполняется в случае isForEstimation = true
type: long
default: -1
- name: customerId
description: Мнемоника ИС Потребителя
type:
- 'null'
- string
default: null
- name: customerOgrn
description: ОГРН ИС Потребителя
type:
- 'null'
- string
default: null
- name: queryMnemonic
description: 'Мнемоника РЗ, сформированная по правилу: <мнемоника витрины>.<мнемоника РЗ>.<версия РЗ> Если запрос распределенный, то формируется по правилу: podd.<мнемоника РЗ>.<версия РЗ>'
type:
- 'null'
- string
default: null
8.1.3. query.rs
query.rs - Топик c чанками данных исполнения запросов
Структура сообщения
datamartExecuteQueryResultChunkMessage:
description: Чанк с данными по исполнению запроса
contentType: 'application/octet-stream'
bindings:
kafka:
key:
$ref: '#/components/schemas/datamartExecuteQueryResultChunk'
headers:
type: object
properties:
MESSAGE_TYPE:
description: Тип сообщения
type: string
const: DatamartExecuteQueryResultChunk:0.1
payload:
description: Бинарные данные чанка
examples:
- name: base64
headers:
MESSAGE_TYPE: DatamartExecuteQueryResultChunk:0.1
payload:
value: JEEJNodyLO7p1pgsRHG9pEiXeYGvHW4YCl4FgrgBmu5C92iVX1PV2GZdcqsb66bx8sk=
Avro-схема сообщения
datamartExecuteQueryResultChunk:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: QueryResultChunk
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: subRequestId
description: Уникальный идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: replyTo
description: Служебная информация маршрутизации сообщения. Заполняется соответсвующим значением из запроса
type: string
- name: chunkNumber
description: Номер порции по порядку
type: int
minimum: 1
- name: isLastChunk
description: Признак последнего сообщения
type: boolean
- name: streamNumber
description: Номер стрима дланных
minimum: 1
type:
- int
- "null"
- name: streamTotal
description: Общее количество стримов
minimum: 1
type:
- int
- "null"
- name: isFragmented
description: Признак присутствия в чанке неполных строк (строк, которые были разбиты на несколько чанков)
type: boolean
- name: uncompressedSize
description: Признак присутствия в чанке неполных строк (строк, которые были разбиты на несколько чанков)
type: int
minimum: 0
examples:
- requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
chunkNumber: 1
isLastChunk: true
streamNumber:
int: 1
streamTotal:
int: 1
isFragmented: false
uncompressedSize: 10
8.1.4. query.err
query.err - Топик c ошибками исполнения sql запросов на витрине
Структура сообщения
datamartExecuteQueryErrorMessage:
description: Ошибка исполнения запроса
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор подзапроса
headers:
type: object
properties:
MESSAGE_TYPE:
description: Тип сообщения
type: string
const: DatamartExecuteQueryError:0.1
payload:
$ref: '#/components/schemas/datamartExecuteQueryError'
examples:
- name: error
summary: Сообщение с ошибкой исполенния запроса на витрине без header
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
errorCode: DATAMART-001
message: Непредвиденная ошибка
- name: errorWithHeader
summary: Сообщение с ошибкой исполенния запроса на витрине
headers:
MESSAGE_TYPE: DatamartExecuteQueryError:0.1
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
errorCode: DATAMART-001
message: Непредвиденная ошибка
Avro-схема сообщения
datamartExecuteQueryError:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: QueryError
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: subRequestId
description: Уникальный идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: replyTo
description: Служебная информация маршрутизации сообщения. Заполняется соответсвующим значением из запроса
type: string
- name: errorCode
description: Код возникшей ошибки
type: string
- name: message
description: Сообщение с ошибкой исполнения
type: string
examples:
- requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
errorCode: DATAMART-001
message: Непредвиденная ошибка
8.1.5. query.estimation.rs
Топик QUERY.ESTIMATION.RS предоставляет возможность произвести предварительную оценку объема получаемых данных при выполнении запроса к Витрине данных, а также, ограничить выгрузку данных в случае, если количество получаемых данных превысит заданное количество строк (параметр rowCountThreshold). В этом случае, ответом на запрос будет предварительная оценка объема.
Например, если вам нужна информация из какой-либо таблицы контактов, то, возможно, следует предварительно узнать, какой объем данных вы можете получить на такой запрос т.к ответ может содержать несколько гигабайт информации и выполнение запроса может занять много времени. Вы сможете установить ограничение на получение данных, например, не более 10 контактов из таблицы. В этом случае, если ответом на запрос будет 5 контактов, то Витрина предоставит ответ полностью. Если ответом будет 1000 контактов, то в качестве ответа будет сформирована предварительная оценка такого ответа, а именно, что данный ответ будет содержать 1000 строк и содержать информацию, например, на 15000 байт. Используя топик query.estimation.rs можно прогнозировать объем получаемых данных, в соответствии с которыми оптимизировать запросы к Витрине.
В случае использования топика query.estimation.rs запрашивается не конечный ответ на запрос, а приблизительная оценка объема (байт) и количество строк в ответе.
Примечание
Данное требование не распространяется на механизм подписок Потребителей данных ПОДД.
Алгоритм работы query.estimation.rs
Витрина получает запрос query.rq с признаком
isForEstimationоценивает объем результата по этому запросу (в байтах и количестве строк).Витрина сравнивает результаты оценки объема запроса со значением предельного числа строк в параметре
rowCountThreshold(топик query.rq).Если значение в оценке меньше, чем предельное значение в
rowCountThreshold, то Витрина возвращает результат запроса в качестве ответа в топик query.rs.Если значение оценки превышает предельное значение, возвращает предварительную оценку объема в качестве ответа.
Структура сообщения
datamartQueryEstimationMessage:
description: Оценка по запросу
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор подзапроса
payload:
$ref: '#/components/schemas/datamartQueryEstimation'
examples:
- name: estimation
summary: Сообщение с оценкой по исполнению запроса
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
estimatedRowCount: 100
estimatedSize: 1000
estimatedTime: 50
Avro-схема сообщения
datamartQueryEstimation:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: Estimation
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: subRequestId
description: Уникальный идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: estimatedRowCount
description: Оценка количества строк результата выполнения запроса
type: long
- name: estimatedSize
description: Оценка объема результата выполнения запроса, в байтах
type: long
- name: estimatedTime
description: Оценка времени выполнения запроса в миллисекундах
type: long
examples:
- requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
estimatedRowCount: 100
estimatedSize: 1000
estimatedTime: 50
8.1.6. Отмена запроса данных
Данная спецификация описывает возможность отмены ранее отправленного запроса к Витрине, получения ответа об успешной отмене запроса или ошибки, с описанием возможной причины.
8.1.7. cancel.rq
cancel.rq - Топик с сообщениями об отмене исполнения запроса
Структура сообщения
datamartQueryCancellationRequestMessage:
description: Запрос на отмену исполнения
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор подзапроса
headers:
type: object
properties:
REQUEST_ID:
description: Идентификатор запроса
type: string
AGENT_CONSUMER_ID:
description: Идентификатор агента потребителя
type: string
payload:
$ref: '#/components/schemas/datamartQueryCancellationRequest'
examples:
- name: request
summary: Пример запроса на отмену
headers:
REQUEST_ID: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
AGENT_CONSUMER_ID: agent-fias
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
Avro-схема сообщения
datamartQueryCancellationRequest:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: AgentQueryCancellationRequest
namespace: ru.rtlabs.common.query.cancel
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
8.1.8. cancel.rs
cancel.rs - Топик с ответами на отмену запроса
Структура сообщения
datamartCancelQuerySuccessMessage:
description: Ответ об успешной отмене запроса
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор подзапроса
headers:
type: object
properties:
REQUEST_ID:
description: Идентификатор запроса
type: string
AGENT_CONSUMER_ID:
description: Идентификатор агента потребителя
type: string
payload:
$ref: '#/components/schemas/datamartCancelQuerySuccess'
examples:
- name: success
summary: Пример запроса на отмену
headers:
REQUEST_ID: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
AGENT_CONSUMER_ID: agent-fias
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
isSuccess: true
Avro-схема сообщения
datamartCancelQuerySuccess:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: DatamartCancelQuerySuccess
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: isSuccess
description: Признак успешного выполнения операции
type: boolean
8.1.9. cancel.err
cancel.err - Топик с ошибками по отмене запроса
Структура сообщения
datamartCancelQueryErrorMessage:
description: Ответ об успешной отмене запроса
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор подзапроса
headers:
type: object
properties:
REQUEST_ID:
description: Идентификатор запроса
type: string
AGENT_CONSUMER_ID:
description: Идентификатор агента потребителя
type: string
payload:
$ref: '#/components/schemas/datamartCancelQueryError'
examples:
- name: success
summary: Пример запроса на отмену
headers:
REQUEST_ID: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
AGENT_CONSUMER_ID: agent-fias
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
errorCode: DATAMART-001
message: Непредвиденная ошибка
Avro-схема сообщения
datamartCancelQueryError:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: DatamartCancelQueryError
namespace: datamart.query.cancel
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: errorCode
description: Код ошибки выполнения
type: string
- name: message
description: Сообщение об ошибке
type: string
8.1.10. Запрос оценки выполнения запроса на Витрине
Данная спецификация описывает возможность получения оценки выполнения запросов на Витрине.
8.1.11. query.rq
query.rq - Топик sql запросов на исполнение
Структура сообщения
datamartExecuteQueryRequestMessage:
description: Исполнение sql запроса на витрине
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор подзапроса
headers:
type: object
properties:
MESSAGE_TYPE:
description: Тип сообщения
type: string
const: DatamartExecuteQueryRequest:0.1
REQUEST_ID:
description: Идентификатор запроса
type: string
QUERY_DEADLINE:
description: Время в миллисекундах от эпохи, до которого запрос должен быть выполнен
type: string
format: int64
AGENT_CONSUMER_ID:
description: Мнемоника потребителя (мнемоника агента)
type: string
QUERY_MNEMONIC:
description: '<Полная мнемоника РЗ>.<версия РЗ>'
type: string
payload:
$ref: '#/components/schemas/datamartExecuteQueryRequest'
examples:
- name: simple
summary: Простой запрос на исполнение без параметров
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from v1_addrobj
parameters: [ ]
namedParams: [ ]
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId: aaa
customerOgrn: ""
queryMnemonic: fias.selectAllAddrobj.1.0
- name: estimation
summary: Запрос на оценку
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 403eada5-05f6-480c-bca9-03328091efeb
subRequestId: 451000b8-dff2-4a1b-ab1b-42500a70d232
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from v1_addrobj
parameters: [ ]
namedParams: [ ]
tableParams: [ ]
isForEstimation: true
rowCountThreshold: 1000
customerId:
string: agent-fias
customerOgrn:
string: "1053600591197"
queryMnemonic:
string: fias.selectAllAddrobj.1.0
- name: complex
summary: Запрос с параметрами
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 68758a92-0027-4258-bf17-aa3d24f85094
subRequestId: 96e6eb99-7ff1-4efa-abae-ef1c5744b723
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from v1_addrobj where oktmo = ? and name = @tbl.fullname
parameters:
- type: STRING
value:
string: asdasdasd
- type: LONG
value: null
namedParams: [ ]
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId:
string: agent-fias
customerOgrn:
string: "1053600591197"
queryMnemonic:
string: fias.selectAddrobjWithParams.1.0
- name: complex_named
summary: Запрос с именованными параметрами
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 12358a92-0027-4258-bf17-aa3d24f85094
subRequestId: 56e6eb99-7ff1-4efa-abae-ef1c5744b723
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from @tbl.fullname el LEFT JOIN v1_addrobj where oktmo = @p1 and kod = @p2
parameters: [ ]
namedParams:
- name: p1
type: STRING
value:
string: asdasdasd
- name: p2
type: LONG
value: null
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId:
string: agent-fias
customerOgrn:
string: "1053600591197"
queryMnemonic:
string: fias.selectAddrobjWithParams.1.0
- name: deadline
summary: Простой запрос на исполнение без параметров
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
QUERY_DEADLINE: 1629289006904
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from v1_addrobj
parameters: [ ]
namedParams: [ ]
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId: agent-fias
customerOgrn: "1053600591197"
queryMnemonic: fias.selectAllWithDeadline.1.0
Avro-схема сообщения
datamartExecuteQueryRequest:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: QueryRequest
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: subRequestId
description: Уникальный идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: replyTo
description: Служебная информация маршрутизации сообщения. Ответ, формируемый витриной, обязан содержать переданное значение без каких либо искажений
type: string
- name: datamartMnemonic
description: Мнемоника витрины, к которой выполняется запрос
type: string
- name: sql
description: SQL запрос на исполнение, либо имя хранимой процедуры для регламентированных запросов
type: string
- name: parameters
description: Параметры к SQL запросу
default: [ ]
type:
type: array
items:
type: record
name: QueryParameter
description: Описание параметра
fields:
- name: type
type: string
description: Тип параметра
enum:
- BIG_DECIMAL
- BINARY
- BOOLEAN
- DATE
- DOUBLE
- FLOAT
- INTEGER
- LONG
- SHORT
- STRING
- TIME
- TIMESTAMP
- name: value
description: Значение параметра
type:
- string
- 'null'
- name: namedParams
description: Именованные параметры запроса
default: [ ]
type:
type: array
items:
type: record
name: NamedParam
description: Описание именованного параметра
fields:
- name: name
description: Имя (мнемоника) параметра
type: string
- name: type
type: string
description: Тип параметра
enum:
- BIG_DECIMAL
- BINARY
- BOOLEAN
- DATE
- DOUBLE
- FLOAT
- INTEGER
- LONG
- SHORT
- STRING
- TIME
- TIMESTAMP
- name: value
description: Значение параметра
type:
- string
- 'null'
- name: tableParams
description: Табличные параметры запроса
default: [ ]
type:
type: array
items:
type: record
name: TableParam
fields:
- name: id
description: Уникальный идентификатор
type:
type: string
logicalType: uuid
- name: name
description: Имя параметра
type: string
- name: columns
description: Описание колонок таблицы
type:
type: array
items:
type: record
description: Описание колонки
name: TableParamColumnInfo
fields:
- name: name
type: string
description: Имя колонки
- name: type
type: string
description: Тип атрибута
enum:
- BIG_DECIMAL
- BINARY
- BOOLEAN
- DATE
- DOUBLE
- FLOAT
- INTEGER
- LONG
- SHORT
- STRING
- TIME
- TIMESTAMP
- name: isForEstimation
description: Признак необходимости вернуть статистику по запросу в качестве результата. В случае, если оценка по результату исполнения sql запроса не превышает rowCountThreshold записей, должен сразу отдаваться результат без отправки оценки в ядро
type: boolean
default: false
- name: rowCountThreshold
description: Максимальное оценочное количество строк результата, при превышении которого возвращается статистика по запросу. Если оценка по запросу не превышет данный параметр, витрина сразу возвращает ответ с результатом. Заполняется в случае isForEstimation = true
type: long
default: -1
- name: customerId
description: Мнемоника ИС Потребителя
type:
- 'null'
- string
default: null
- name: customerOgrn
description: ОГРН ИС Потребителя
type:
- 'null'
- string
default: null
- name: queryMnemonic
description: 'Мнемоника РЗ, сформированная по правилу: <мнемоника витрины>.<мнемоника РЗ>.<версия РЗ> Если запрос распределенный, то формируется по правилу: podd.<мнемоника РЗ>.<версия РЗ>'
type:
- 'null'
- string
default: null
8.1.12. query.estimation.rs
Топик QUERY.ESTIMATION.RS предоставляет возможность произвести предварительную оценку объема получаемых данных при выполнении запроса к Витрине данных, а также, ограничить выгрузку данных в случае, если количество получаемых данных превысит заданное количество строк (параметр rowCountThreshold). В этом случае, ответом на запрос будет предварительная оценка объема.
Например, если вам нужна информация из какой-либо таблицы контактов, то, возможно, следует предварительно узнать, какой объем данных вы можете получить на такой запрос т.к ответ может содержать несколько гигабайт информации и выполнение запроса может занять много времени. Вы сможете установить ограничение на получение данных, например, не более 10 контактов из таблицы. В этом случае, если ответом на запрос будет 5 контактов, то Витрина предоставит ответ полностью. Если ответом будет 1000 контактов, то в качестве ответа будет сформирована предварительная оценка такого ответа, а именно, что данный ответ будет содержать 1000 строк и содержать информацию, например, на 15000 байт. Используя топик query.estimation.rs можно прогнозировать объем получаемых данных, в соответствии с которыми оптимизировать запросы к Витрине.
В случае использования топика query.estimation.rs запрашивается не конечный ответ на запрос, а приблизительная оценка объема (байт) и количество строк в ответе.
Примечание
Данное требование не распространяется на механизм подписок Потребителей данных ПОДД.
Алгоритм работы query.estimation.rs
Витрина получает запрос query.rq с признаком
isForEstimationоценивает объем результата по этому запросу (в байтах и количестве строк).Витрина сравнивает результаты оценки объема запроса со значением предельного числа строк в параметре
rowCountThreshold(топик query.rq).Если значение в оценке меньше, чем предельное значение в
rowCountThreshold, то Витрина возвращает результат запроса в качестве ответа в топик query.rs.Если значение оценки превышает предельное значение, возвращает предварительную оценку объема в качестве ответа.
Структура сообщения
datamartQueryEstimationMessage:
description: Оценка по запросу
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор подзапроса
payload:
$ref: '#/components/schemas/datamartQueryEstimation'
examples:
- name: estimation
summary: Сообщение с оценкой по исполнению запроса
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
estimatedRowCount: 100
estimatedSize: 1000
estimatedTime: 50
Avro-схема сообщения
datamartQueryEstimation:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: Estimation
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: subRequestId
description: Уникальный идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: estimatedRowCount
description: Оценка количества строк результата выполнения запроса
type: long
- name: estimatedSize
description: Оценка объема результата выполнения запроса, в байтах
type: long
- name: estimatedTime
description: Оценка времени выполнения запроса в миллисекундах
type: long
examples:
- requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
estimatedRowCount: 100
estimatedSize: 1000
estimatedTime: 50
8.1.13. Запрос статистики
Данная спецификация описывает возможность запроса статистики Витрины.
8.1.14. statistics.rq
statistics.rq - Топик запросов статистики витрины
Структура сообщения
datamartStatisticRequestMessage:
description: Запрос статистики витрины
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
$ref: '#/components/schemas/datamartStatisticRequestKey'
headers:
type: object
properties:
REQUEST_ID:
description: Идентификатор запроса
type: string
payload:
$ref: '#/components/schemas/datamartStatisticRequest'
examples:
- name: simple
headers:
REQUEST_ID: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
payload:
protocol: read.statistic.protocol.v.1
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
datamart:
mnemonic: fias
version:
major: 1
minor: 0
Avro-схема сообщения
datamartStatisticRequest:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: DatamartStatisticRequest
namespace: ru.rtlabs.common.statistic
fields:
- name: protocol
description: Версия протокола. Указывается константа read.statistic.protocol.v.1
type: string
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: datamart
description: Витрина
type:
type: record
name: DatamartInfo
fields:
- name: mnemonic
description: Мнемоника витрины
type: string
- name: version
description: Версия
type:
type: record
name: SemanticVersion
namespace: ru.rtlabs.common.model.metadata
fields:
- name: major
type: int
minimum: 1
- name: minor
type: int
minimum: 0
8.1.15. statistics.rs
statistics.rs - Топик со статистикой витрины
Структура сообщения
datamartStatisticResponseMessage:
description: Статистика витрины
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор запроса
headers:
type: object
properties:
REQUEST_ID:
description: Идентификатор запроса
type: string
payload:
$ref: '#/components/schemas/datamartStatisticResponse'
examples:
- name: simple
headers:
REQUEST_ID: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
payload:
protocol: read.statistic.protocol.v.1
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
datamart:
mnemonic: fias
version:
major: 1
minor: 0
tables:
- mnemonic: addrobj
columns:
- mnemonic: oktmo
notGreater10: 10.0
inRange11And100: 50.0
inRange101And1000: 30.0
moreThan1000: 10.0
Avro-схема сообщения
datamartStatisticResponse:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: DatamartStatisticResponse
namespace: ru.rtlabs.common.datamart.profile
fields:
- name: protocol
description: Версия протокола. Указывается константа read.statistic.protocol.v.1
type: string
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: datamart
description: Статистика по витрине
type:
type: record
name: DatamartStatistic
fields:
- name: mnemonic
description: Мнемоника витрины
type: string
- name: version
description: Версия
type:
type: record
name: SemanticVersion
namespace: ru.rtlabs.common.model.metadata
fields:
- name: major
type: int
minimum: 1
- name: minor
type: int
minimum: 0
- name: tables
type:
type: array
items:
type: record
name: TableStatistic
fields:
- name: mnemonic
description: Мнемоника витрины
type: string
- name: columns
description: Колонки
type:
type: array
items:
type: record
name: ColumnStatistic
description: Статистика по колонке
fields:
- name: mnemonic
type: string
- name: notGreater10
type: double
- name: inRange11And100
type: double
- name: inRange101And1000
type: double
- name: moreThan1000
type: double
8.1.16. statistics.err
statistics.err - Топик c ошибками получения статистики витрины
Структура сообщения
datamartStatisticErrorMessage:
description: Неуспешный результат обработки запроса на получение статистики
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор запроса
headers:
type: object
properties:
REQUEST_ID:
description: Идентификатор запроса
type: string
payload:
$ref: '#/components/schemas/datamartStatisticError'
examples:
- name: simple
headers:
REQUEST_ID: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
payload:
protocol: read.statistic.protocol.v.1
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
errorCode: DATAMART-001
message: Непредвиденная ошибка
Avro-схема сообщения
datamartStatisticError:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: DatamartStatisticError
namespace: ru.rtlabs.common.statistic
fields:
- name: protocol
type: string
description: Версия протокола. Указывается константа read.statistic.protocol.v.1
conts: read.statistic.protocol.v.1
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: errorCode
description: Код ошибки
type: string
- name: message
description: Сообщение об ошибке
type: string
8.1.17. Запрос данных по регламентированным запросам
Данная спецификация описывает возможность запроса данных по регламентированным запросам
8.1.18. procedure.query.rq
procedure.query.rq - Топик регламентированных запросов на исполнение
Структура сообщения
examples:
- name: simple
summary: Простой запрос на исполнение без параметров
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from v1_addrobj
parameters: [ ]
namedParams: [ ]
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId: aaa
customerOgrn: ""
queryMnemonic: fias.selectAllAddrobj.1.0
- name: estimation
summary: Запрос на оценку
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 403eada5-05f6-480c-bca9-03328091efeb
subRequestId: 451000b8-dff2-4a1b-ab1b-42500a70d232
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from v1_addrobj
parameters: [ ]
namedParams: [ ]
tableParams: [ ]
isForEstimation: true
rowCountThreshold: 1000
customerId:
string: agent-fias
customerOgrn:
string: "1053600591197"
queryMnemonic:
string: fias.selectAllAddrobj.1.0
- name: complex
summary: Запрос с параметрами и табличными параметрами
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 68758a92-0027-4258-bf17-aa3d24f85094
subRequestId: 96e6eb99-7ff1-4efa-abae-ef1c5744b723
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from v1_addrobj where oktmo = ? and name = @tbl.fullname
parameters:
- type: STRING
value:
string: asdasdasd
- type: LONG
value: null
namedParams: [ ]
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId:
string: agent-fias
customerOgrn:
string: "1053600591197"
queryMnemonic:
string: fias.selectAddrobjWithParams.1.0
- name: complex_named
summary: Запрос с именованными параметрами
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 12358a92-0027-4258-bf17-aa3d24f85094
subRequestId: 56e6eb99-7ff1-4efa-abae-ef1c5744b723
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from @tbl.fullname el LEFT JOIN v1_addrobj where oktmo = @p1 and kod = @p2
parameters: [ ]
namedParams:
- name: p1
type: STRING
value:
string: asdasdasd
- name: p2
type: LONG
value: null
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId:
string: agent-fias
customerOgrn:
string: "1053600591197"
queryMnemonic:
string: fias.selectAddrobjWithParams.1.0
- name: deadline
summary: Простой запрос на исполнение без параметров
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
QUERY_DEADLINE: 1629289006904
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
datamartMnemonic: fias
sql: select * from v1_addrobj
parameters: [ ]
namedParams: [ ]
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId: agent-fias
customerOgrn: "1053600591197"
queryMnemonic: fias.selectAllWithDeadline.1.0
Avro-схема сообщения
datamartExecuteQueryRequest:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: QueryRequest
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: subRequestId
description: Уникальный идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: replyTo
description: Служебная информация маршрутизации сообщения. Ответ, формируемый витриной, обязан содержать переданное значение без каких либо искажений
type: string
- name: datamartMnemonic
description: Мнемоника витрины, к которой выполняется запрос
type: string
- name: sql
description: SQL запрос на исполнение, либо имя хранимой процедуры для регламентированных запросов
type: string
- name: parameters
description: Параметры к SQL запросу
default: [ ]
type:
type: array
items:
type: record
name: QueryParameter
description: Описание параметра
fields:
- name: type
type: string
description: Тип параметра
enum:
- BIG_DECIMAL
- BINARY
- BOOLEAN
- DATE
- DOUBLE
- FLOAT
- INTEGER
- LONG
- SHORT
- STRING
- TIME
- TIMESTAMP
- name: value
description: Значение параметра
type:
- string
- 'null'
- name: namedParams
description: Именованные параметры запроса
default: [ ]
type:
type: array
items:
type: record
name: NamedParam
description: Описание именованного параметра
fields:
- name: name
description: Имя (мнемоника) параметра
type: string
- name: type
type: string
description: Тип параметра
enum:
- BIG_DECIMAL
- BINARY
- BOOLEAN
- DATE
- DOUBLE
- FLOAT
- INTEGER
- LONG
- SHORT
- STRING
- TIME
- TIMESTAMP
- name: value
description: Значение параметра
type:
- string
- 'null'
- name: tableParams
description: \use only Datamart\ Табличные параметры запроса
default: [ ]
type:
type: array
items:
type: record
name: TableParam
fields:
- name: id
description: Уникальный идентификатор
type:
type: string
logicalType: uuid
- name: name
description: Имя параметра
type: string
- name: columns
description: Описание колонок таблицы
type:
type: array
items:
type: record
description: Описание колонки
name: TableParamColumnInfo
fields:
- name: name
type: string
description: Имя колонки
- name: type
type: string
description: Тип атрибута
enum:
- BIG_DECIMAL
- BINARY
- BOOLEAN
- DATE
- DOUBLE
- FLOAT
- INTEGER
- LONG
- SHORT
- STRING
- TIME
- TIMESTAMP
- name: isForEstimation
description: Признак необходимости вернуть статистику по запросу в качестве результата. В случае, если оценка по результату исполнения sql запроса не превышает rowCountThreshold записей, должен сразу отдаваться результат без отправки оценки в ядро
type: boolean
default: false
- name: rowCountThreshold
description: Максимальное оценочное количество строк результата, при превышении которого возвращается статистика по запросу. Если оценка по запросу не превышет данный параметр, витрина сразу возвращает ответ с результатом. Заполняется в случае isForEstimation = true
type: long
default: -1
- name: customerId
description: Мнемоника ИС Потребителя
type:
- 'null'
- string
default: null
- name: customerOgrn
description: ОГРН ИС Потребителя
type:
- 'null'
- string
default: null
- name: queryMnemonic
description: 'Мнемоника РЗ, сформированная по правилу: <мнемоника витрины>.<мнемоника РЗ>.<версия РЗ> Если запрос распределенный, то формируется по правилу: podd.<мнемоника РЗ>.<версия РЗ>'
type:
- 'null'
- string
default: null
8.1.19. procedure.query.rs
procedure.query.rs - Топик c чанками данных исполнения запросов
Структура сообщения
datamartExecuteQueryResultChunk:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: QueryResultChunk
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: subRequestId
description: Уникальный идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: replyTo
description: Служебная информация маршрутизации сообщения. Заполняется соответсвующим значением из запроса
type: string
- name: chunkNumber
description: Номер порции по порядку
type: int
minimum: 1
- name: isLastChunk
description: Признак последнего сообщения
type: boolean
- name: streamNumber
description: Номер стрима данных
minimum: 1
type:
- int
- "null"
- name: streamTotal
description: Общее количество стримов
minimum: 1
type:
- int
- "null"
- name: isFragmented
description: Признак присутствия в чанке неполных строк (строк, которые были разбиты на несколько чанков)
type: boolean
- name: uncompressedSize
description: Оригинальный размер чанка в байтах
type: int
minimum: 0
Пример key query.rs
examples:
- requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
chunkNumber: 1
isLastChunk: true
streamNumber:
int: 1
streamTotal:
int: 1
isFragmented: false
uncompressedSize: 10
8.1.20. procedure.query.err
procedure.query.err - Топик c ошибками исполнения sql запросов на витрине
Структура сообщения
datamartExecuteQueryError:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: QueryError
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: subRequestId
description: Уникальный идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: replyTo
description: Служебная информация маршрутизации сообщения. Заполняется соответсвующим значением из запроса
type: string
- name: errorCode
description: Код возникшей ошибки
type: string
- name: message
description: Сообщение с ошибкой исполнения
type: string
Пример query.err
examples:
- name: error
summary: Сообщение с ошибкой исполнения запроса на витрине без header
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
errorCode: DATAMART-001
message: Непредвиденная ошибка
- name: errorWithHeader
summary: Сообщение с ошибкой исполнения запроса на витрине
headers:
MESSAGE_TYPE: DatamartExecuteQueryError:0.1
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
errorCode: DATAMART-001
message: Непредвиденная ошибка
8.1.21. Запрос метаданных
Данная спецификация описывает возможность запроса метаданных Витрины
8.1.22. metadata.rq
Передача Агентом ПОДД запроса метаданных в Витрину.
Формат сообщения
Header |
Не используется |
Key |
текст, содержит requestId, не используется. |
Value |
Сериализация: в json (см. схему ниже.) |
Схема
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"requestId": {
"type": "string"
},
"datamartMnemonic": {
"type": "string"
}
},
"required": [
"requestId",
"datamartMnemonic"
]
}
, где:
requestId - UUID запроса;
datamartMnemonic - мнемоника Витрины данных, к которой адресован запрос.
8.1.23. metadata.rs
Передача Агенту ПОДД ответа на запрос метаданных витрины из Витрины.
Формат сообщения
Header |
Не используется |
Key |
текст, содержит requestId |
Value |
Сериализация: в json (см. схему ниже.) |
Схема
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"requestId": {
"type": "string"
},
"metadata": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"datamart": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"mnemonic": {
"type": "string"
},
"datamartClassess": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"mnemonic": {
"type": "string"
},
"label": {
"type": "string"
},
"classAttributes": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"mnemonic": {
"type": "string"
},
"type": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"id",
"value"
]
}
},
"required": [
"id",
"mnemonic",
"type"
]
}
]
},
"primaryKey": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"mnemonic": {
"type": "string"
},
"type": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"id",
"value"
]
}
},
"required": [
"id",
"mnemonic",
"type"
]
}
]
}
},
"required": [
"id",
"mnemonic",
"label",
"classAttributes",
"primaryKey"
]
}
]
}
},
"required": [
"id",
"mnemonic",
"datamartClassess"
]
}
},
"required": [
"datamart"
]
}
]
}
},
"required": [
"requestId",
"metadata"
]
}
, где:
requestId- UUID запроса;metadata– описание структуры данных;datamart– описание витрины;id– UUID витрины (не используется);mnemonic– имя витрины;datamartClassess– список таблиц витрины;id– UUID таблицы (не используется);mnemonic– имя таблицы;label– не используется;classAttributes– список полей таблицы;id– UUID поля (не используется);mnemonic– имя поля;type– тип данных поля;id– UUID типа данных (не используется);value– название типа данных;primaryKey– список полей, составляющих PK таблицы;id– UUID поля (не используется);mnemonic– имя поля;type– тип данных поля;id– UUID типа данных (не используется);value– название типа данных.
8.1.24. metadata.err
Получение Агентом ПОДД ошибки при обработке запроса метаданных от Витрины.
Формат сообщения
Header |
Не используется |
Key |
текст, содержит requestId |
Value |
Сериализация: в json (см. схему ниже.) |
Схема
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"requestId": {
"type": "string"
},
"errorCode": {
"type": "string"
},
"msg": {
"type": "string"
}
},
"required": [
"requestId",
"errorCode",
"msg"
]
}
, где:
requestId- UUID запроса;errorCode– содержит константуINTERNAL;msg– описание ошибки.
8.2. Спецификация модуля «BLOB-адаптер»
8.2.1. Запрос на считывание BLOB
Настоящая спецификация определяет формат обмена электронными сообщениями через BLOB-адаптер. Описывает возможность запроса на считывание BLOB-объект по полученной ссылке, получения успешного ответа на чтение содержимого BLOB или ошибки, в случае невозможности считывания, с описанием причины ошибки.
Топик |
Назначение |
|---|---|
blob.rq |
Запросы на считывание BLOB’а по ссылке. |
blob.rs |
Содержимое BLOB’а (ответ на запрос). |
blob.err |
Сообщения об ошибке считывания. |
Для строковых параметров используется кодировка UTF-8.
8.2.2. blob.rq
blob.rq - Топик запросов на получение бинарных данных по полученной ранее ссылке.
Структура сообщения
datamartBlobRequestMessage:
description: Запрос бинарных данных по ссылке
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор подзапроса
headers:
type: object
properties:
REQUEST_ID:
description: Идентификатор запроса
type: string
AGENT_CONSUMER_ID:
description: Идентификатор агента потребителя
type: string
MESSAGE_TYPE:
description: Тип сообщения
type: string
const: DatamartBlobRequest:0.1
payload:
$ref: '#/components/schemas/datamartBlobRequest'
examples:
- name: getBlobDataRequest
summary: Запрос бинарных данных по ссылке
headers:
REQUEST_ID: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
AGENT_CONSUMER_ID: agent-fias
MESSAGE_TYPE: DatamartBlobRequest:0.1
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
queryRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
reference:
subRequestId: 4cbb11d6-47de-4928-953f-47dfa6c6b310
path: reference
Avro-схема сообщения
datamartBlobRequest:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: BlobRequest
namespace: datamart.blob
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: queryRequestId
description: Идентификатор исходного запроса, в рамках которого была получена ссылка
type:
type: string
logicalType: uuid
- name: reference
description: Ссылка на данные
type:
type: record
name: BinaryReference
namespace: query.result
fields:
- name: subRequestId
description: Идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: path
description: Ссылка
type: string
8.2.3. blob.rs
blob.rs - Топик с бинарными данным блобов
Структура сообщения
datamartBlobChunkMessage:
description: Чанки бинарных данных
contentType: 'application/octet-stream'
bindings:
kafka:
key:
$ref: '#/components/schemas/datamartBlobChunkInfo'
headers:
type: object
properties:
AGENT_CONSUMER_ID:
description: Идентификатор агента потребителя
type: string
MESSAGE_TYPE:
description: Тип сообщения
type: string
const: DatamartBlobChunkInfo:0.1
payload:
description: Бинарные данные
examples:
- name: base64
headers:
MESSAGE_TYPE: DatamartBlobChunkInfo:0.1
payload:
value: JEEJNodyLO7p1pgsRHG9pEiXeYGvHW4YCl4FgrgBmu5C92iVX1PV2GZdcqsb66bx8sk=
Avro-схема сообщения
datamartBlobChunkInfo:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: BlobChunk
namespace: datamart.blob
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: queryRequestId
description: Идентификатор исходного запроса, в рамках которого была получена ссылка
type:
type: string
logicalType: uuid
- name: chunkNum
description: Номер чанка
type: int
minimum: 1
- name: isLast
description: Признак последнего чанка
type: boolean
examples:
- requestId: 3546e40b-47fe-41b6-9c06-a2e915eb4181
queryRequestId: a8e9f47b-38cd-4db6-a245-0fbd6e78c195
chunkNum: 1
isLast: true
8.2.4. blob.err
blob.err - Топик c ошибками получения бинарных данных по ссылке.
Структура сообщения
datamartBlobErrorResponseMessage:
description: Ошибка получения бинарных данных по ссылке
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор подзапроса
headers:
type: object
properties:
AGENT_CONSUMER_ID:
description: Идентификатор агента потребителя
type: string
MESSAGE_TYPE:
description: Тип сообщения
type: string
const: DatamartBlobErrorResponse:0.1
payload:
$ref: '#/components/schemas/datamartBlobErrorResponse'
examples:
- name: blobError
summary: Пример ошибки получения бинарных данных по ссылке
headers:
AGENT_CONSUMER_ID: agent-fias
MESSAGE_TYPE: DatamartBlobErrorResponse:0.1
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
queryRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
errorCode: DATAMART-001
errorMessage: Непредвиденная ошибка обработки
Avro-схема сообщения
datamartBlobErrorResponse:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: BlobError
namespace: datamart.blob
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: queryRequestId
description: Идентификатор исходного запроса, в рамках которого была получена ссылка
type:
type: string
logicalType: uuid
- name: errorCode
description: Код ошибки
type: string
- name: errorMessage
description: Сообщение с ошибкой
type: string
8.3. Спецификация модуля «Сервис Формирования документов»
8.3.1. Запрос формирования документов
Данная спецификация описывает возможность запроса на генерацию формирования файлов, получения успешного ответа (сгенерированных файлов и их метаданных) или ошибки, в случае невозможности сгенерировать файлы, с описанием причины ошибки.
Топик |
Назначение |
|---|---|
Report.rq |
Запросы на генерацию файлов. |
Report.rs |
Содержимое сгенерированных файлов (ответ на запрос). |
Report.err |
Сообщения об ошибке генерации. |
8.3.2. report.rq
Внимание
Название топика может быть изменено на этапе внедрения!
Запрос на генерацию файлов. Одно сообщение - один запрос. Один запрос - один набор параметров (в наборе м.б. много параметров, в параметрах м.б. указано «сгенерируй много форматов файлов на основании одной и той же выборки данных»).
Структура сообщения
datamartExecuteQueryRequestMessage:
description: Исполнение sql запроса на витрине
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор подзапроса
headers:
type: object
properties:
MESSAGE_TYPE:
description: Тип сообщения
type: string
const: DatamartExecuteQueryRequest:0.1
REQUEST_ID:
description: Идентификатор запроса
type: string
QUERY_DEADLINE:
description: Время в миллисекундах от эпохи, до которого запрос должен быть выполнен
type: string
format: int64
AGENT_CONSUMER_ID:
description: Мнемоника потребителя (мнемоника агента)
type: string
QUERY_MNEMONIC:
description: '<Полная мнемоника РЗ>.<версия РЗ>'
type: string
payload:
$ref: '#/components/schemas/datamartExecuteQueryRequest'
examples:
- name: report
summary: Запрос к Сервису формирования документов
headers:
MESSAGE_TYPE: DatamartExecuteQueryRequest:0.1
payload:
requestId: 68758a92-0027-4258-bf17-aa3d24f85094
subRequestId: 96e6eb99-7ff1-4efa-abae-ef1c5744b723
replyTo: agent-fias
datamartMnemonic: fias
sql: v1_printable_form_address
parameters:
- type: STRING
value:
string: MIIB9wYJKoZIhvcNAQcCoIIB6DCCAeQCAQExADALBgkqhkiG9w0BBwGgggHMMIIByDCCAXOgAwIBAgIEV/dqTjAMBggqhQMHAQEDAgUAMDUxCzAJBgNVBAYTAlJVMQswCQYDVQQKEwJSVDEZMBcGA1UEAwwQYmxhc3RvZmZfY2FfdGVzdDAeFw0yMjAzMDQwNzQ5MzBaFw0zMjAzMDEwNzQ5MzBaMC0xETAPBgNVBAMMCGl0b25lZGV2MQswCQYDVQQKDAJSVDELMAk
- type: STRING
value:
string: xml
namedParams: [ ]
tableParams: [ ]
isForEstimation: false
rowCountThreshold: -1
customerId:
string: agent-fias
customerOgrn:
string: "1053600591197"
queryMnemonic:
string: fias.selectAddrobjWithParams.1.0
Avro-схема сообщения
datamartExecuteQueryRequest:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: QueryRequest
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: subRequestId
description: Уникальный идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: replyTo
description: Служебная информация маршрутизации сообщения. Ответ, формируемый витриной, обязан содержать переданное значение без каких либо искажений
type: string
- name: datamartMnemonic
description: Мнемоника витрины, к которой выполняется запрос
type: string
- name: sql
description: тип отчета
type: string
- name: parameters
description: Параметры к SQL запросу (при запросе к сервису формирования документов, первым параметром ВСЕГДА идет сертификат, а вторым формат файла (xml или pdf))
default: [ ]
type:
type: array
items:
type: record
name: QueryParameter
description: Описание параметра
fields:
- name: type
type: string
description: Тип параметра
enum:
- BIG_DECIMAL
- BINARY
- BOOLEAN
- DATE
- DOUBLE
- FLOAT
- INTEGER
- LONG
- SHORT
- STRING
- TIME
- TIMESTAMP
- name: value
description: Значение параметра
type:
- string
- 'null'
- name: namedParams
description: Именованные параметры запроса
default: [ ]
type:
type: array
items:
type: record
name: NamedParam
description: Описание именованного параметра
fields:
- name: name
description: Имя (мнемоника) параметра
type: string
- name: type
type: string
description: Тип параметра
enum:
- BIG_DECIMAL
- BINARY
- BOOLEAN
- DATE
- DOUBLE
- FLOAT
- INTEGER
- LONG
- SHORT
- STRING
- TIME
- TIMESTAMP
- name: value
description: Значение параметра
type:
- string
- 'null'
- name: tableParams
description: Табличные параметры запроса
default: [ ]
type:
type: array
items:
type: record
name: TableParam
fields:
- name: id
description: Уникальный идентификатор
type:
type: string
logicalType: uuid
- name: name
description: Имя параметра
type: string
- name: columns
description: Описание колонок таблицы
type:
type: array
items:
type: record
description: Описание колонки
name: TableParamColumnInfo
fields:
- name: name
type: string
description: Имя колонки
- name: type
type: string
description: Тип атрибута
enum:
- BIG_DECIMAL
- BINARY
- BOOLEAN
- DATE
- DOUBLE
- FLOAT
- INTEGER
- LONG
- SHORT
- STRING
- TIME
- TIMESTAMP
- name: isForEstimation
description: Признак необходимости вернуть статистику по запросу в качестве результата. В случае, если оценка по результату исполнения sql запроса не превышает rowCountThreshold записей, должен сразу отдаваться результат без отправки оценки в ядро
type: boolean
default: false
- name: rowCountThreshold
description: Максимальное оценочное количество строк результата, при превышении которого возвращается статистика по запросу. Если оценка по запросу не превышет данный параметр, витрина сразу возвращает ответ с результатом. Заполняется в случае isForEstimation = true
type: long
default: -1
- name: customerId
description: Мнемоника ИС Потребителя
type:
- 'null'
- string
default: null
- name: customerOgrn
description: ОГРН ИС Потребителя
type:
- 'null'
- string
default: null
- name: queryMnemonic
description: 'Мнемоника РЗ, сформированная по правилу: <мнемоника витрины>.<мнемоника РЗ>.<версия РЗ> Если запрос распределенный, то формируется по правилу: podd.<мнемоника РЗ>.<версия РЗ>'
type:
- 'null'
- string
default: null
8.3.3. report.rs
Внимание
Название топика может быть изменено на этапе внедрения!
Позитивный ответ на запрос - содержимое сгенерированных файлов и метаданные для них, передается только в случае успешного выполнения генерации. Один запрос - один ответ. Один ответ - несколько сообщений. Одно сообщение - один chunk.
Структура сообщения
datamartExecuteQueryResultChunkMessage:
description: Чанк с данными по исполнению запроса
contentType: 'application/octet-stream'
bindings:
kafka:
key:
$ref: '#/components/schemas/datamartExecuteQueryResultChunk'
headers:
type: object
properties:
MESSAGE_TYPE:
description: Тип сообщения
type: string
const: DatamartExecuteQueryResultChunk:0.1
payload:
description: Бинарные данные чанка
examples:
- name: base64
headers:
MESSAGE_TYPE: DatamartExecuteQueryResultChunk:0.1
payload:
value: JEEJNodyLO7p1pgsRHG9pEiXeYGvHW4YCl4FgrgBmu5C92iVX1PV2GZdcqsb66bx8sk=
Avro-схема Key сообщения
datamartExecuteQueryResultChunk:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: QueryResultChunk
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: subRequestId
description: Уникальный идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: replyTo
description: Служебная информация маршрутизации сообщения. Заполняется соответсвующим значением из запроса
type: string
- name: chunkNumber
description: Номер порции по порядку
type: int
minimum: 1
- name: isLastChunk
description: Признак последнего сообщения
type: boolean
- name: streamNumber
description: Номер стрима данных
minimum: 1
type:
- int
- "null"
- name: streamTotal
description: Общее количество стримов
minimum: 1
type:
- int
- "null"
- name: isFragmented
description: Признак присутствия в чанке неполных строк (строк, которые были разбиты на несколько чанков)
type: boolean
- name: uncompressedSize
description: Оригинальный размер чанка в байтах
type: int
minimum: 0
examples:
- requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
chunkNumber: 1
isLastChunk: true
streamNumber:
int: 1
streamTotal:
int: 1
isFragmented: false
uncompressedSize: 10
Avro-схема Value (для report.rs она универсальная)
{
"type": "record",
"name": "QueryResultRow",
"namespace": "datamart.query",
"fields": [
{
"name": "DocType",
"type": "string"
},
{
"name": "FileName",
"type": "string"
},
{
"name": "Content",
"type": "bytes"
},
{
"name": "Meta",
"type": ["string", "null"]
}
]
}
8.3.4. report.err
Внимание
Название топика может быть изменено на этапе внедрения!
Негативный ответ на запрос - описание причины ошибки, передается только в случае невозможности выполнения запроса (если для одного из форматов в запросе не настроена генерация, то возвращаются настроенные форматы и это не считается ошибкой). Один запрос - один ответ (об ошибке). Один ответ - одно сообщение.
Структура сообщения
datamartExecuteQueryErrorMessage:
description: Ошибка исполнения запроса
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
bindings:
kafka:
key:
type: string
format: uuid
description: Уникальный идентификатор подзапроса
headers:
type: object
properties:
MESSAGE_TYPE:
description: Тип сообщения
type: string
const: DatamartExecuteQueryError:0.1
payload:
$ref: '#/components/schemas/datamartExecuteQueryError'
examples:
- name: error
summary: Сообщение с ошибкой исполнения запроса на витрине без header
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
errorCode: DATAMART-001
message: Непредвиденная ошибка
- name: errorWithHeader
summary: Сообщение с ошибкой исполнения запроса на витрине
headers:
MESSAGE_TYPE: DatamartExecuteQueryError:0.1
payload:
requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
errorCode: DATAMART-001
message: Непредвиденная ошибка
Avro-схема сообщения
datamartExecuteQueryError:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
type: record
name: QueryError
namespace: datamart.query
fields:
- name: requestId
description: Уникальный идентификатор запроса
type:
type: string
logicalType: uuid
- name: subRequestId
description: Уникальный идентификатор подзапроса
type:
type: string
logicalType: uuid
- name: replyTo
description: Служебная информация маршрутизации сообщения. Заполняется соответсвующим значением из запроса
type: string
- name: errorCode
description: Код возникшей ошибки
type: string
- name: message
description: Сообщение с ошибкой исполнения
type: string
examples:
- requestId: 2e8c8ab2-44db-4dcb-8ae5-2365121b4e14
subRequestId: 608c5a5a-01d4-4439-8220-dda41a8519fe
replyTo: agent-fias
errorCode: DATAMART-001
message: Непредвиденная ошибка
9. Приложение 2. Поддержка функций SQL
9.1. Поддержка функции LISTAGG
9.1.1. LISTAGG
9.1.1.1. Описание
Функция LISTAGG объединяет значения measure_column для каждой группы на основе order_by_clause.
9.1.1.2. Поддержка в модулях
Сервис исполнения запросов;
ПОДД-адаптер – Модуль MPPR.
9.1.1.3. Синтаксис
Функция LISTAGG в модуле «ПОДД-адаптер – Модуль MPPR»
Для ПОДД-адаптер – Модуль MPPR реализована поддержка LISTAGG (expression, separator) [WITHIN GROUP (order_by_clause)].
Пример запроса:
{"requestId":"4ec61462-0cf5-4b41-84a8-70f215f4109c","subRequestId":"567fbc0a-04b9-43c8-819b-882d3414c2b1","datamartMnemonic":"demo_view","replyTo":"","sql":"SELECT LISTAGG(firstname, ', ') WITHIN GROUP (ORDER BY firstname) AS \"firstname_Listing\" FROM v1_passenger","parameters":[],"tableParams":[],"isForEstimation":false,"rowCountThreshold": 0}
Пример ответа:
key = [{"requestId": "4ec61462-0cf5-4b41-84a8-70f215f4109c", "subRequestId": "567fbc0a-04b9-43c8-819b-882d3414c2b1", "replyTo": "", "chunkNumber": 1, "isLastChunk": true, "streamNumber": 1, "streamTotal": 1, "uncompressedSize": 0, "isFragmented": false}],
value = [{"firstname_listing": "Григорий, Иван10, Иван11, Иван5, Иван6, Иван7, Иван8, Иван9, Станислав, Станислав"}]
Функция LISTAGG в «Сервисе исполнения запросов»
Для Сервис исполнения запросов реализована поддержка функции LISTAGG для работы с множественными атрибутами. А(10) Р(10) Д(1) = 21 Простор: А(1) Р(3) Т(2) =6
Пример запроса:
{"requestId":"d58b1fa4-e674-4698-857f-f2fb779c9245","subRequestId":"6861b2a8-6821-424b-8b1f-ced06fba75a0","datamartMnemonic":"demo_view","replyTo":"","sql":"SELECT LISTAGG(firstname, ', ') WITHIN GROUP (ORDER BY firstname) AS \"firstname_Listing\" FROM v1_passenger limit 10","parameters":[],"tableParams":[],"isForEstimation":false,"rowCountThreshold": 0}
Пример ответа:
key = [{"requestId": "d58b1fa4-e674-4698-857f-f2fb779c9245", "subRequestId": "6861b2a8-6821-424b-8b1f-ced06fba75a0", "replyTo": "", "chunkNumber": 1, "isLastChunk": true, "streamNumber": 1, "streamTotal": 1, "uncompressedSize": 0, "isFragmented": false}],
value = [{"firstname_listing": "Григорий, Иван10, Иван11, Иван5, Иван6, Иван7, Иван8, Иван9, Станислав, Станислав"}]
10. Приложение 3. Пример XML-файла со структурой витрины
<?xml version='1.0' encoding='utf-8'?>
<ns:PODDMetadataRequest
xmlns:ns="urn://x-artefacts-podd-gosuslugi-local/metadata/datamart/2/1.6.0"
xmlns:ns1="urn://x-artefacts-podd-gosuslugi-local/metadata/types/1.3">
<ns:requestId>00000000-0000-0000-0000-000000000001</ns:requestId>
<ns:metadata>
<ns1:datamart>
<ns1:id>1806436d-437a-400d-b32e-aa15c1a2d4bc</ns1:id>
<ns1:mnemonic>demo_view</ns1:mnemonic>
<ns1:description>demo_view</ns1:description>
<ns1:tenantId>c52f062e-af97-4a44-a33f-d1a94024d0cf</ns1:tenantId>
<ns1:version>
<ns1:major>1</ns1:major>
<ns1:minor>0</ns1:minor>
</ns1:version>
<ns1:supportedFrom>2021-01-01T00:00:00</ns1:supportedFrom>
<ns1:datamartClass>
<ns1:id>4c4ff97b-938b-4db6-9f4d-ae21046e4d20</ns1:id>
<ns1:mnemonic>Passenger</ns1:mnemonic>
<ns1:description>Passenger</ns1:description>
<ns1:classAttribute>
<ns1:id>6fe29bdb-7db1-405a-a05c-b49c541c92bd</ns1:id>
<ns1:mnemonic>Code</ns1:mnemonic>
<ns1:description>Code</ns1:description>
<ns1:type>LONG</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>e590e7b3-b611-4891-bbd1-a5e256105e73</ns1:id>
<ns1:mnemonic>Id</ns1:mnemonic>
<ns1:description>Id</ns1:description>
<ns1:type>STRING</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>c97a8102-6ad0-4dbd-934d-c82b83a4d83f </ns1:id>
<ns1:mnemonic>FirstName</ns1:mnemonic>
<ns1:description>FirstName</ns1:description>
<ns1:type>STRING</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>d2312bfb-7ec0-4c95-9026-0f6dea48c5d9</ns1:id>
<ns1:mnemonic>MiddleName</ns1:mnemonic>
<ns1:description>MiddleName</ns1:description>
<ns1:type>STRING</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>7b63db89-bd0e-4c92-8bc0-e609175937b9</ns1:id>
<ns1:mnemonic>LastName</ns1:mnemonic>
<ns1:description>LastName</ns1:description>
<ns1:type>STRING</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>8f3e7f95-f66b-4d4a-b2eb-55a3e6134c3e</ns1:id>
<ns1:mnemonic>Birthday</ns1:mnemonic>
<ns1:description>Birthday</ns1:description>
<ns1:type>DATE</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>e3658240-b405-4838-99af-d32cd063c463</ns1:id>
<ns1:mnemonic>Passport</ns1:mnemonic>
<ns1:description>Passport</ns1:description>
<ns1:type>STRING</ns1:type>
</ns1:classAttribute>
<ns1:primaryKey>
<ns1:id>6fe29bdb-7db1-405a-a05c-b49c541c92bd</ns1:id>
<ns1:mnemonic>Code</ns1:mnemonic>
<ns1:description>Code</ns1:description>
<ns1:type>
<ns1:id>00000000-0000-0000-0000-000000000001</ns1:id>
<ns1:value>LONG</ns1:value>
</ns1:type>
</ns1:primaryKey>
</ns1:datamartClass>
<ns1:datamartClass>
<ns1:id>cafe41db-3878-4796-ba60-cbd54f042c63</ns1:id>
<ns1:mnemonic>Ticket</ns1:mnemonic>
<ns1:description>Ticket</ns1:description>
<ns1:classAttribute>
<ns1:id>bc90563b-168a-4faa-9394-7b7390dd0d92</ns1:id>
<ns1:mnemonic>Id</ns1:mnemonic>
<ns1:description>Id</ns1:description>
<ns1:type>STRING</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>ac93618f-752b-44d5-a77c-23a3c9eb069b</ns1:id>
<ns1:mnemonic>PassengerId</ns1:mnemonic>
<ns1:description>PassengerId</ns1:description>
<ns1:type>STRING</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>51355519-2d59-426e-b199-9589930acaaa</ns1:id>
<ns1:mnemonic>TripId</ns1:mnemonic>
<ns1:description>TripId</ns1:description>
<ns1:type>STRING</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>fe92c245-929e-4684-b9c9-22bda6939c09</ns1:id>
<ns1:mnemonic>Number</ns1:mnemonic>
<ns1:description>Number</ns1:description>
<ns1:type>LONG</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>4a32ded4-c970-4874-b0b1-2e3eed8b6483</ns1:id>
<ns1:mnemonic>ByCard</ns1:mnemonic>
<ns1:description>ByCard</ns1:description>
<ns1:type>BOOLEAN</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>35f59c80-fcc3-483c-9cd3-dc3afb606d66</ns1:id>
<ns1:mnemonic>Price</ns1:mnemonic>
<ns1:description>Price</ns1:description>
<ns1:type>DOUBLE</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>8b46ff55-6853-458c-851d-6e1666da918b</ns1:id>
<ns1:mnemonic>Sold</ns1:mnemonic>
<ns1:description>Sold</ns1:description>
<ns1:type>TIMESTAMP</ns1:type>
</ns1:classAttribute>
<ns1:primaryKey>
<ns1:id>fe92c245-929e-4684-b9c9-22bda6939c09</ns1:id>
<ns1:mnemonic>Number</ns1:mnemonic>
<ns1:description>Number</ns1:description>
<ns1:type>
<ns1:id>00000000-0000-0000-0000-000000000001</ns1:id>
<ns1:value>LONG</ns1:value>
</ns1:type>
</ns1:primaryKey>
</ns1:datamartClass>
<ns1:datamartClass>
<ns1:id>76268090-60ee-4960-8268-1b91f4186e87</ns1:id>
<ns1:mnemonic>Trip</ns1:mnemonic>
<ns1:description>Trip</ns1:description>
<ns1:classAttribute>
<ns1:id>bd173e24-ea7e-4869-9d43-9f57f5b0a82f</ns1:id>
<ns1:mnemonic>Id</ns1:mnemonic>
<ns1:description>Id</ns1:description>
<ns1:type>STRING</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>1ed32816-8bdb-4d35-9f66-8c08df13ad28</ns1:id>
<ns1:mnemonic>Number</ns1:mnemonic>
<ns1:description>Number</ns1:description>
<ns1:type>INTEGER</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>78f587fa-b53e-4912-b631-0c4a249d20b6</ns1:id>
<ns1:mnemonic>Duration</ns1:mnemonic>
<ns1:description>Duration</ns1:description>
<ns1:type>STRING</ns1:type>
</ns1:classAttribute>
<ns1:classAttribute>
<ns1:id>1750c564-20a7-4e07-988a-b382227123e4</ns1:id>
<ns1:mnemonic>Length</ns1:mnemonic>
<ns1:description>Length</ns1:description>
<ns1:type>FLOAT</ns1:type>
</ns1:classAttribute>
<ns1:primaryKey>
<ns1:id>1ed32816-8bdb-4d35-9f66-8c08df13ad28</ns1:id>
<ns1:mnemonic>Number</ns1:mnemonic>
<ns1:description>Number</ns1:description>
<ns1:type>
<ns1:id>00000000-0000-0000-0000-000000000002</ns1:id>
<ns1:value>INTEGER</ns1:value>
</ns1:type>
</ns1:primaryKey>
</ns1:datamartClass>
</ns1:datamart>
</ns:metadata>
</ns:PODDMetadataRequest>
11. Приложение 4. Эксплуатация CSV-Uploader
11.1. Инструкция по эксплуатации CSV-Uploader
11.1.1. Общие правила формата загружаемых CSV-файлов
Общие правила формата загружаемых CSV-файлов приведены в Таблица 11.1.
Параметр |
Значение |
|---|---|
Разделитель строк |
Любой вариант из: CR/LF (0x0D0A), CR (0x0D), LF (0x0A) |
Разделитель полей |
по настройке csv-parser/separator (Параметры конфигурации) |
Строка заголовка |
да (обязательно) |
Порядок полей в строке |
определяется строкой заголовка |
Ограничитель текстового поля |
по настройке csv-parser/quote-char (Параметры конфигурации) |
Символ маскировки в текстовом поле |
по настройке csv-parser/escape-char (Параметры конфигурации) |
Обнаружение значения null |
До релиза 1.5.0 (включительно): по настройке csv-parser/field-as-null (Параметры конфигурации) начиная с релиза 1.10.0: в текущей реализации парсера данная настройка не поддерживается |
Кодирование символов |
UTF-8 |
Десятичный разделитель |
символ |
Формат даты |
любой из: |
Формат времени |
любой из: |
Формат даты-времени |
до релиза 1.5.0(включительно) любой из: начиная с релиза 1.10.0 любой из: |
11.1.2. Загрузка структуры Витрины
Внимание
XML-файл со структурой Витрины может быть загружен только один раз после установки Компонент «Витрина данных Лайт».
Для передачи xml-файла со структурой Витрины, выполните следующие действия:
Откройте программный интерфейс CSV-uploader.
Выберите вкладку Загрузка структуры.
В открывшемся окне Загрузка структуры Витрины нажмите кнопку Выберите файл, выберите XML-файла для загрузки и нажмите кнопку Загрузить. (см. Рисунок - 11.1)
Рисунок - 11.1 Загрузка структуры Витрины
В случае успешного применения настроек отобразится информационное сообщение: Список таблиц загружен.
11.1.3. Выгрузка шаблона CSV
Для выгрузки существующего CSV-файла со структурой Витрины, выполните следующие действия:
Откройте программный интерфейс CSV-uploader.
Выберите вкладку Выгрузка шаблона CSV.
Выберите таблицу для выгрузки, например, demo_view_podd.all_types_table, для выгрузки примера CSV-таблиц
для СМЭВ4 (см. Рисунок - 11.2).
Рисунок - 11.2 Выгрузка шаблона CSV
Нажмите кнопку Выгрузить. Файл будет загружен на локальный компьютер. Если требуется выгрузить все таблицы, нажмите кнопку Выгрузить все.
В случае успешной выгрузки на экране монитора отобразится информационное сообщение: Список таблиц выгружен.
11.1.4. Загрузка CSV-файла
Для загрузки CSV-файла, выполните следующие действия:
Откройте программный интерфейс CSV-uploader.
Выберите вкладку Загрузчик CSV.
В открывшемся окне Загрузка файла выберите Режим загрузки:
Вставка - параметр определяет, что данные будут добавлены.
Удаление - параметр определяет, что данные будут удалены.
В случае, если в настройках модуля CSV-uploader включен ФЛК и прописан адрес модуля REST-Uploader, на странице отображается переключатель с текстом «Выполнять проверку форматно-логического контроля».
Для автоматического определения типа таблиц включите переключатель Автоматическое определение таблицы, если автоматическое определение таблиц не требуется, выключите переключатель и выберите таблицу, в которую требуется внести изменения, например, demo_view_podd.all_types_table (см. Рисунок - 11.3).
Рисунок - 11.3 Загрузка CSV-файла
Нажмите кнопку Выберите файл чтобы выбрать файл для загрузки.
Нажмите кнопку Загрузить.
Убедитесь, что файл с таблицами был загружен.
При включенной настройке определения таблиц после выбора и загрузки файла:
модулем CSV-Uploader определяется таблица загрузки:
в случае, если активен переключатель «Автоматическое определение таблицы» по метаданным csv файла;
в случае если выбрана конкретная таблица, в соответствии с выбором пользователя;
модуль CSV-Uploader обогащает url запроса на загрузку именем датамарта и таблицы;
модуль CSV-Uploader выполняет запрос /v2/datamarts/{datamart_name}/tables/{table_name}/upload к модулю REST-Uploader;
модуль CSV-Uploader отображает текст ответа на странице загрузки в формате:
время ответа;
код ответа;
body ответа:
в случае успешного ответа, модуль CSV-Uploader сохраняет requestId файла в топик flk_logs в внутренней Kafka.
11.1.5. Загрузка CSV-файла с предварительным форматно-логическим контролем
В случае, если в настройках модуля CSV-Uploader включена настройка VALIDATION_ENABLE: true и прописан адрес модуля
REST-Uploader (REST_UPLOADER_URL) при активном режиме «Вставка» на странице отображается переключатель с текстом
«Выполнять проверку форматно-логического контроля» , по умолчанию значение вкл (true) см. Рисунок - 11.4.
Рисунок - 11.4 Переключатель выполнения ФЛК
При включенном переключателе «Выполнять проверку форматно-логического контроля» после выбора файла и нажатия кнопки Загрузить:
модулем CSV-Uploader определяется таблица загрузки:
в случае, если включен переключатель «автоопределение таблицы» по метаданным CSV файла;
в случае если выбрана конкретная таблица, в соответствии с выбором пользователя;
модуль CSV-Uploader обогащает URL запроса на загрузку именем датамарта и таблицы;
модуль CSV-Uploader выполняет запрос
/v2/datamarts/{datamart_name}/tables/{table_name}/uploadк модулю REST-Uploader;модуль CSV-Uploader отображает текст синхронного ответа на странице загрузки в формате:
время ответа;
код ответа;
body ответа.
При выключенном переключателе «Выполнять проверку форматно-логического контроля» загрузка выполняется стандартным способом через модуль CSV-Uploader.
11.1.6. Обязательная загрузка данных с предварительным форматно-логическим контролем
При включении настройки VALIDATION_MANDATOR: true, переключатель «Выполнять проверку форматно-логического контроля» неактивен и
находится во включенном положении.
В данном режиме загрузка данных в ручном режиме с использованием CSV-Uploader невозможна, для всех загружаемых данных будут проводиться проверки форматно-логического контроля в модуле REST-Uploader см. Рисунок - 11.5.
Рисунок - 11.5 Обязательная загрузка данных с предварительным форматно-логическим контролем
11.1.7. Аутентификация с использованием jwt-токена при включенной аутентификации в модуле REST-Uploader
Для использования jwt-токена при загрузке данных с предварительным ФЛК в случае, если в REST-Uploader включена аутентификация, необходимо включить следующие настройки в модуле CSV-Uploader:
VALIDATION_ENABLE:true;JWT_AUTH:true.
В случае, если обе настройки имеют значение true, при открытии загрузчика CSV-uploader отображается модальное окно ввода токена пользователя, а на странице загрузки данных в витрину отображается поле «Изменить JWT» (см. Рисунок - 11.6).
Рисунок - 11.6 Модальное окно ввода токена
Значение внесенного JWT-токена используется как барьерный токен при обращении к REST-Uploader.
Внесенное значение токена сохраняется в сессии пользователя и автоматически подставляется при включении переключателя выполнения ФЛК проверок. Для того, чтобы изменить JWT-токен для аутентификации, необходимо нажать кнопку Изменить JWT (см. Рисунок - 11.7).
Рисунок - 11.7 Отображение кнопки Изменить JWT
11.1.8. Настройки CSV-uploader
Для CSV-uploader можно настроить следующие параметры:
автоматический запуск загрузки CSV-файлов по расписанию;
количество отображаемых записей для Журнала операций.
11.1.9. Автоматический запуск загрузки CSV-файлов по расписанию
Для настройки автоматического запуска загрузки CSV-файлов по расписанию, выполните следующие действия:
Откройте программный интерфейс CSV-uploader.
Выберите вкладку Настройки.
В открывшемся окне Настройки в поле Запуск по расписанию, укажите время в
Cronформате (например,0 15 10? * *- загрузка файлов будет происходить каждый день в 10.15) и путь к каталогу с CSV-файлами (см. Рисунок - 11.8) .
Рисунок - 11.8 Автоматический запуск загрузки CSV-файлов по расписанию
Установите маркер в поле Включить, для активации автоматического запуска загрузки.
Нажмите кнопку Применить настройки.
В случае успешного применения настроек отобразится информационное сообщение: Конфигурация успешно получена.
11.1.10. Настройка Журнала операций
Для настройки Журнала операций, выполните следующие действия:
Откройте программный интерфейс CSV-uploader.
Выберите вкладку Настройки.
В открывшемся окне Настройки в поле Размер страницы, укажите количество записей на страницу, например,
20(см. Рисунок - 11.9).
Рисунок - 11.9 Настройка Журнала операций
Нажмите кнопку Применить настройки.
В случае успешного применения настроек отобразится информационное сообщение: Конфигурация успешно получена.
11.1.11. Просмотр Журнала операций
В Журнале операций можно просмотреть действия выполненные в CSV-uploader:
Время - время, когда операция была выполнена.
Уровень - статус операции.
ERROR- ошибка загрузки;INFO- описание операции.
Сообщение - краткое информационное сообщение об операции.
Для просмотра Журнала операций, выполните следующие действия:
Откройте программный интерфейс CSV-uploader.
Выберите вкладку Журнал операций.
В открывшемся окне просмотрите операции, которые были выполнены в CSV-uploader (см. Рисунок - 11.10).
Рисунок - 11.10 Просмотр Журнала операций
Нажмите кнопку Применить настройки.
11.1.12. Интерфейс Форматно-логического контроля
На вкладке Форматно-логический контроль (см. flk) отображается:
список последних отправленных файлов, определяемых настройками модуля CSV-Uploader - значение по умолчанию 20:
список requestId;
время записи в кафку;
статус загрузки файла;
управляющий элемент для запроса отчета об ошибках для файла (кнопка отображается активной только в случае финальных статусов):
статус 3;
статус 4;
статус 7;
элементы пагинации списка requestId.
Рисунок - 11.11 Форматно-логический контроль
При нажатии на кнопку запроса отчета об ошибках для файла, модуль CSV-Uploader:
вызывает метод
/v2/requests/{request_id}/report/;получает CSV файл с именем
report_requestId.csv;в зависимости от ответа:
если response 200 ok: скачивает файл на ПК пользователя автоматически или при нажатии на название отчета с выводом сообщения о загрузке файла;
если response 400 - выводит сообщение
Нет данных.