Установка BLOB-адаптера

BLOB-адаптер - это программный модуль Витрины данных, предназначенный для получения доступа из Витрины данных к BLOB-объектам ведомства. Подробнее о том, как он используется в СМЭВ4 можно узнать в статье Использование Blob Адаптера для обмена blob объектами.

Хранилище BLOB-объектов располагается на стороне ведомства и не является частью Витрины данных. Хранилище BLOB-объектов должно поддерживать регламентированный Витриной данных интерфейс доступа к BLOB-объектам по запросу.

Перед развёртыванием BLOB-адаптера необходимо ознакомится с требованиями к серверу и к самому хранилищу BLOB-адаптера, которые нужно учитывать перед развёртыванием BLOB-адаптера.

Требования к серверу BLOB-адаптера

Следующие файлы и папки файловой системы сервера, должны быть доступны процессу установки для создания и модификации, и не должны контролироваться системой управления конфигурации (при её наличии):

• /etc/hosts
• /etc/selinux/config
• /etc/sysctl.conf
• файлы директории /usr/lib/systemd/system/
• /etc/sysconfig/iptables*
• /etc/firewalld/*
• /etc/docker/*

Снаружи сервер должен быть доступен по следующим портам:

• 22 (ssh)

Требования к Хранилищу BLOB-объектов

Для корректной работы с хранилищем BLOB-объектов, необходимо предоставить:

• доступ к таблицам с метаданными по документам, хранилища ведомства;
• доступ к ссылкам на BLOB-объекты (изображения, архивы, pdf-файлы и т.д.) в хранилище ведомства, соответствующие метаданным;
• связь между ссылками и метаданными, если они разнесены по разным хранилищам.

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

Установка модуля

Модуль BLOB-адаптер поставляется в виде jar-файла. В поставку также входит файл настроек конфигурации модуля BLOB-адаптер (application.yml).

Рисунок 1 – Состав jar файла BLOB-адаптера

Общий процесс установки состоит из следующих действий:

1. Настроить конфигурацию модуля.
2. Создать на сервере директорию для загрузки файлов модуля.
3. Загрузить файлы модуля в созданную директорию.
4. Запустить jar-файл модуля.
5. Проверить установку модуля.

Настройка конфигурации

Настройка конфигурации выполняется путем редактирования параметров файла application.yml. Пример конфигурации файла application.yml и возможные настройки конфигурации модуля см. раздел Конфигурация BLOB-адаптер (application.yml).

Добавление папки для загрузки файлов модуля

Создайте на сервере папку, в которую будут загружены файлы модуля, например, /opt/blob-adapter. В случае, если ранее была установлена старая версия модуля BLOB-адаптер, сделайте его резервную копию.

Загрузка файлов на сервер

Загрузите в созданную на предыдущем шаге папку:

• jar-файл модуля;
• файл настроек конфигурации модуля BLOB-адаптер (application.yml).

Конфигурация BLOB-адаптера (application.yml)

Файл application.yml – основной конфигурационный файл BLOB-адаптер, в котором задана логика и порядок работы адаптера: получение входящих запросов, их обработка, а также настройка подключения к СМЭВ3-адаптер, к PODD-адаптер и другие настройки необходимые для корректной работы адаптера.

Параметры конфигурации

Настройка конфигурации BLOB-адаптера осуществляется путем редактирования параметров настроек в файле application.yml.

В файле конфигурации BLOB-адаптер могут быть настроены следующие секции:

• vertx - настройки параметров фреймворка Vert.x  (подробнее на сайте разработчиков: https://vertx.io/docs/);
• client- настройка работы с BLOB-объектами через PODD-адаптер;
• chunk - настройка  фиксированного размера блока данных для отправки через Kafka;
• blob-storage - настройка подключения к Хранилищу BLOB-объектов;
• logging - настройка сохранения лог-файла.

Секция kafkaUrl

URL для доступа к Kafka PODD-агент.

Секция vertx предназначена для настройки параметров фреймворка Vert.x  (подробнее на сайте разработчиков: https://vertx.io/docs/).

vertx: clustered: false

Секция client определяет настройки взаимодействия с PODD-адаптер для получения входящих и исходящих запросов.

Параметры конфигурации:

• enabled - включение/отключение работы с шиной данных Kafka через PODD-адаптер. Если значение true - взаимодействие с BLOB-объектами осуществляется через PODD-адаптер, если значение false - через СМЭВ3-адаптер.
• kafka - настройка интеграции с шиной данных Kafka (при активном (true) значении enabled).
• zookeeperHosts - подключение к Zookeeper ПОДД-агента.
• consumer - получатель данных.
• rqTopicName- формат запроса (см. раздел Спецификация модуля «BLOB-адаптер» ).
• rsTopicName - формат запроса к серверу Kafka на считывание BLOB-объекта по ссылке - blob.rs (см. раздел Спецификация модуля «BLOB-адаптер» ).
• errTopicName - формат ответа Kafka в случае ошибки - blob.err (см. раздел Спецификация модуля «BLOB-адаптер» ).
• bootstrap.servers - путь к серверу Kafka.
• bootstrap.servers - путь к серверу Kafka.

Например:

client: enabled: ${KAFKA_TRANSPORT_ENABLED:true} kafka: cluster: zookeeperHosts: ${ZOOKEEPER_HOSTS:localhost} rootPath: ${KAFKA_CLUSTER_ROOT_PATH:} blob: consumer: rqTopicName: blob.rq property: bootstrap.servers: *kafkaUrl group.id: blob.consumer auto.offset.reset: earliest enable.auto.commit: true producer: rsTopicName: blob.rs errTopicName: blob.err base-producer-property: bootstrap.servers: *kafkaUrl base-consumer-property: bootstrap.servers: *kafkaUrl

Секция chunk определяет настройки размера фрагмента (в байтах), на которые дробятся сообщения, содержащее тело BLOB-объекта. Размер одного chunk для каждого сообщения Kafka не должен превышать 1мб.

Секция blob-storage предназначена для настройки пути к Хранилищу BLOB-объектов (GET-запрос).

Например:

blob-storage: host: ${BLOB_STORAGE_HOST:http://localhost:8080}

Формат записи имеет следующий вид:

protocol://name[:port]/[path/]

где

• protocol - одно из значений http или https;
• name - ip или FQDN http-сервера, содержащего ссылку на BLOB-объекты;
• port - номер tcp-порта, если отсутствует, то следует использовать следующие порты 80 для http, 443 для https);
• path - постоянная часть пути до Хранилища BLOB-объектов (содержимого BLOB-объекта).

Секция logging предназначена для настройки параметров логирования:

logging: level:     ru.itone.datamart: DEBUG

Запуск модуля

Перед запуском модуля необходимо убедиться, что на сервере с ОС Centos установлена Java. Если Java отсутствует на сервере, то запустить модуль BLOB-адаптера не получится. Чтобы установить Java на сервер необходимо воспользоваться командой:

java     -Dconfig.location=<путь до application.yml>     -jar <путь до blob-adapter.jar> &

или

$ sudo yum install java-11-openjdk-devel

Для того, чтобы проверить наличие на сервере установленное ПО Java, а также узнать версию Java, необходимо воспользоваться командой:

$ java -version

Рисунок 2 – Результат проверки версии установленного ПО Java.

Для ручного запуска модуля необходимо подключиться по ssh на сервер, перейти в директорию расположения jar-файла, например:

$ cd /opt/blob-adapter

И запустить модуль командой:

$ java -jar blob-adapter.jar -migrate application.yaml

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

Рисунок 3 – Запуск загрузчика модулей.

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

Проверка модуля

Для проверки модуля BLOB-адаптер  необходимо выполнить запрос к сервису.

curl -s IP:Port/metrics | grep '^liveness '

где

• IP - адрес сервера.
• Port - адрес сервера.
• liveness - параметр проверки работоспособности модуля.

Например:

curl -s http://172.16.10.67:9837/metrics | grep '^liveness '

Пример успешного ответа:

liveness 1.0

Ответ "1" означает, что модуль работает.

Остановка модуля

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

ps aux | grep   blob-adapter

  "kill" «номер процесса»

Спецификация модуля «BLOB-адаптер»

Запрос на считывание BLOB

Настоящая спецификация определяет формат обмена электронными сообщениями через BLOB-адаптер. Описывает возможность запроса на считывание BLOB-объект по полученной ссылке, получения успешного ответа на чтение содержимого BLOB или ошибки, в случае невозможности считывания, с описанием причины ошибки.

Топик	Назначение
blob.rq	Запросы на считывание BLOB’а по ссылке.
blob.rs	Содержимое BLOB’а (ответ на запрос).
blob.err	Сообщения об ошибке считывания.

Для строковых параметров используется кодировка UTF-8.

Настоящая спецификация определяет формат обмена электронными сообщениями через BLOB-адаптер.

Топик blob.rq - определяет запрос на считывание BLOB-объект. Одно сообщение - один запрос. Один запрос - один BLOB-объект.

Формат сообщения:

Header	REQUEST_ID, AGENT_CONSUMER_ID
Key	текст, содержит requestId, не используется.
Value	Сериализация: в Avro (см. схему ниже.)

Схема:

{ "type": "record", "name": "BlobRequest", "namespace": "datamart.blob", "fields": [         {           "name": "requestId",           "type": {                 "type": "string",                 "logicalType": "uuid"           }         },         {           "name": "queryRequestId",           "type": {                 "type": "string",                 "logicalType": "uuid"           }         },         {           "name": "reference",           "type": {                 "type": "record",                 "name": "BinaryReference",                 "namespace": "query.result",                 "fields": [                   {                         "name": "subRequestId",                         "type": {                           "type": "string",                           "logicalType": "uuid"                         }                   },                   {                         "name": "path",                         "type": "string"                   }                 ]           }         } ] }

где

• requestId - UUID базового запроса;
• queryRequestId - UUID исходного запроса, в рамках которого была получена ссылка;
• reference - объект ссылки:
• subRequestId - UUID подзапроса, в рамках которого сформирована ссылка
• path - ссылка на тело BLOB’а (получена ранее запросом данных из Витрины).

Если размер BLOB’а в хранилище 0 Байтов, то мы ответ отправляем в BLOB.RS и при этом в сообщении Value будет пустым.

Настоящая спецификация определяет формат обмена электронными сообщениями через BLOB-адаптер.

В топике blob.rs передается содержимое BLOB-объекта. Запрос на считывание BLOB-объекта определяется в топике blob.rq. Успешный ответ на запрос передается только в случае успешного выполнения считывания содержимого BLOB-объекта. Один запрос - один ответ. Один ответ - несколько сообщений. Одно сообщение - один chunk.

Если размер BLOB’а в хранилище 0 Байтов, то ответ отправляется в BLOB.RS и при этом в сообщении Value будет пустым.

В случае ошибки считывания возвращается ошибка (топик blob.err).

Формат сообщения:

Header	REQUEST_ID (содержание значения запроса) AGENT_CONSUMER_ID (содержит значение из запроса)
Key	Сериализация: в Avro (см. схему ниже.)
Value	массив байтов, являющихся фрагментом (с номером chunkNumber) запрошенного тела BLOB’а. Не сериализуется.

Схема:

{ "type": "record", "name": "BlobChunk", "namespace": "datamart.blob", "fields": [ {         "name": "requestId",         "type": {         "type": "string",         "logicalType": "uuid"         } }, {         "name": "queryRequestId",         "type": {         "type": "string",         "logicalType": "uuid"         } }, {         "name": "chunkNum",         "type": "int" }, {         "name": "isLast",         "type": "boolean" } ] }

где:

• requestId - значение копируется из соответствующего параметра запроса, на который дается этот ответ;
• queryRequestId - значение копируется из соответствующего параметра запроса, на который дается этот ответ;
• chunkNumber - номер фрагмента (начинается с 1);
• isLastChunk - признак последнего фрагмента.

Настоящая спецификация определяет формат обмена электронными сообщениями через BLOB-адаптер.

Топик blob.err используется в случае ошибки считывания BLOB-объекта. Негативный ответ на запрос - описание причины ошибки, передается только в случае неудачного выполнения считывания. Один запрос - один ответ. Один ответ - одно сообщение.

Формат сообщения:

Header	REQUEST_ID (содержание значения запроса) AGENT_CONSUMER_ID (содержит значение из запроса)
Key	строка, содержит значение параметра requestId из запроса.
Value	Сериализация: в Avro (см. схему ниже.)

Схема:

{ "type": "record", "name": "BlobError", "namespace": "datamart.blob", "fields": [ {     "name": "requestId",     "type": {       "type": "string",       "logicalType": "uuid"     } }, {     "name": "queryRequestId",     "type": {       "type": "string",       "logicalType": "uuid"     } }, {     "name": "errorCode",     "type": "string" }, {     "name": "errorMessage",     "type": "string" } ]       }

где:

• requestId - значение копируется из соответствующего параметра запроса, на который дается этот ответ.
• queryRequestId - значение копируется из соответствующего параметра запроса, на который дается этот ответ;
• errorCode- код ошибки (формат DATAMART-ddddd, где ddddd - десятичные цифры кода ошибки);
• message - сообщение об ошибке.

Если http-запрос к хранилищу BLOB’ов вернул ошибку (код ответа не равен 200), то возвращенный код логируется (как ошибка), а в Kafka передается (errorCode =DATAMART-17001, errorMessage= "Внутренняя ошибка"). Если запрос вернул 200, то ошибки нет и передаем ровно столько байтов, сколько вернул запрос (ноль байтов (пустой файл) не считается ошибкой).