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-адаптера
Общий процесс установки состоит из следующих действий:
- Настроить конфигурацию модуля.
- Создать на сервере директорию для загрузки файлов модуля.
- Загрузить файлы модуля в созданную директорию.
- Запустить jar-файл модуля.
- Проверить установку модуля.
Настройка конфигурации
Настройка конфигурации выполняется путем редактирования параметров файла application.yml. Пример конфигурации файла application.yml и возможные настройки конфигурации модуля см. раздел Конфигурация BLOB-адаптер (application.yml).
Добавление папки для загрузки файлов модуля
Создайте на сервере папку, в которую будут загружены файлы модуля, например, /opt/blob-adapter. В случае, если ранее была установлена старая версия модуля BLOB-адаптер, сделайте его резервную копию.Загрузка файлов на сервер
Загрузите в созданную на предыдущем шаге папку:- jar-файл модуля;
- файл настроек конфигурации модуля BLOB-адаптер (application.yml).
Конфигурация BLOB-адаптера (application.yml)
Файл application.yml – основной конфигурационный файл BLOB-адаптер, в котором задана логика и порядок работы адаптера: получение входящих запросов, их обработка, а также настройка подключения к СМЭВ3-адаптер, к PODD-адаптер и другие настройки необходимые для корректной работы адаптера.
.kafkaUrl: &kafkaUrl ${KAFKA_BOOTSTRAP_SERVERS:t5-adsp-01.ru-central1.internal:9092}
|
Параметры конфигурации
Настройка конфигурации 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:
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: |
Запуск модуля
Перед запуском модуля необходимо убедиться, что на сервере с ОС Centos установлена Java. Если Java отсутствует на сервере, то запустить модуль BLOB-адаптера не получится. Чтобы установить Java на сервер необходимо воспользоваться командой:
java
-Dconfig.location=<путь до application.yml> |
или
$ 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", |
где
- 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 |
|
Key |
Сериализация: в Avro (см. схему ниже.) |
Value |
массив байтов, являющихся фрагментом (с номером chunkNumber) запрошенного тела BLOB’а. Не сериализуется. |
Схема:
{
"type": "record", |
где:
- requestId - значение копируется из соответствующего параметра запроса, на который дается этот ответ;
- queryRequestId - значение копируется из соответствующего параметра запроса, на который дается этот ответ;
- chunkNumber - номер фрагмента (начинается с 1);
- isLastChunk - признак последнего фрагмента.
Настоящая спецификация определяет формат обмена электронными сообщениями через BLOB-адаптер.
Топик blob.err используется в случае ошибки считывания BLOB-объекта. Негативный ответ на запрос - описание причины ошибки, передается только в случае неудачного выполнения считывания. Один запрос - один ответ. Один ответ - одно сообщение.
Формат сообщения:
Header |
|
Key |
строка, содержит значение параметра requestId из запроса. |
Value |
Сериализация: в Avro (см. схему ниже.) |
Схема:
{
"type": "record", |
где:
- requestId - значение копируется из соответствующего параметра запроса, на который дается этот ответ.
- queryRequestId - значение копируется из соответствующего параметра запроса, на который дается этот ответ;
- errorCode- код ошибки (формат DATAMART-ddddd, где ddddd - десятичные цифры кода ошибки);
- message - сообщение об ошибке.
Если http-запрос к хранилищу BLOB’ов вернул ошибку (код ответа не равен 200), то возвращенный код логируется (как ошибка), а в Kafka передается (errorCode =DATAMART-17001, errorMessage= "Внутренняя ошибка"). Если запрос вернул 200, то ошибки нет и передаем ровно столько байтов, сколько вернул запрос (ноль байтов (пустой файл) не считается ошибкой).