Войти

Установка 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-адаптера.png

Рисунок 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-адаптер и другие настройки необходимые для корректной работы адаптера.

Пример файла application.yml
 .kafkaUrl: &kafkaUrl ${KAFKA_BOOTSTRAP_SERVERS:t5-adsp-01.ru-central1.internal:9092}


server:
enabled: ${SERVER_ENABLED:true}
port: ${SERVER_PORT:8081}
metrics:
port: ${METRICS_PORT:9837}
executor:
reader-pool-size: ${EXECUTOR_READER_POOL_SIZE:20}
chunk:
size: ${CHUNK_SIZE:524288}
kafka:
enabled: ${KAFKA_ENABLED:true}
consumer:
blob-request: ${AGENT_TOPIC_PREFIX:}blob.rq
property:
bootstrap.servers: *kafkaUrl
group.id: ${AGENT_TOPIC_PREFIX:}blob-consumer
auto.offset.reset: earliest
enable.auto.commit: true
producer:
blob-result: ${AGENT_TOPIC_PREFIX:}blob.rs
blob-error: ${AGENT_TOPIC_PREFIX:}blob.err
property:
bootstrap.servers: *kafkaUrl
blob-storage:
protocol: ${BLOB_STORAGE_PROTOCOL:http}
host: ${BLOB_STORAGE_HOST:localhost}
port: ${BLOB_STORAGE_PORT:8888}
path-prefix: ${BLOB_STORAGE_PATH_PREFIX:}
path-postfix: ${BLOB_STORAGE_PATH_POSTFIX:}
auth:
type: ${BLOB_STORAGE_AUTH_TYPE:NONE}
user: ${BLOB_STORAGE_AUTH_USER:user}
password: ${BLOB_STORAGE_AUTH_PASSWORD:pass}
token: ${BLOB_STORAGE_AUTH_TOKEN:token}
#  params:
#    name1: value1
#    name2: value2

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

Настройка конфигурации 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

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

 vertx:

clustered: false


Секция client

Секция 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

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

Секция blob-storage
Секция 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 предназначена для настройки параметров логирования:

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.png
Рисунок 2 – Результат проверки версии установленного ПО Java.

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

 $ cd /opt/blob-adapter

И запустить модуль командой:
 $ java -jar blob-adapter.jar -migrate application.yaml

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

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

Рисунок 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.rq

Настоящая спецификация определяет формат обмена электронными сообщениями через 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.rs

Настоящая спецификация определяет формат обмена электронными сообщениями через 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.err

Настоящая спецификация определяет формат обмена электронными сообщениями через 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, то ошибки нет и передаем ровно столько байтов, сколько вернул запрос (ноль байтов (пустой файл) не считается ошибкой).

Авторизуйтесь, чтобы оставить комментарий к статье