REST-uploader

REST-uploader — это модуль ПО «Витрина данных» (ВД), предназначенный для асинхронной загрузки данных из сторонних источников. REST-uploader взаимодействует с ядром витрины данных (Prostore) по REST API. Загрузка/обновление данных осуществляется в формате CSV в разрезе отдельных таблиц. Ниже представлена схема загрузки данных в витрину (Рисунок 1):

Рисунок 1 — Схема загрузки данных в БД с помощью REST-uploader

Для взаимодействия с REST API в продуктивной среде на стороне источника данных необходимо использовать сертифицированную версию ОС, а также механизмы, соответствующие требованиям безопасности, установленным для эксплуатации системы. В данной статье в качестве примера используется ПО Postman. 

  Важно!

 Для обеспечения возможности загрузки данных в БД витрины с помощью REST-uploader необходимо также установить модули Redis и Data-uploader.

Установка модулей REST-uploader, Redis и Data-uploader описана в сатье — Установка витрины в конфигурации стандарт. Минимальный набор.

Требования к загружаемым файлам

CSV-файлы с данными для загрузки в витрину должны соответствовать следующим требованиям:

1. Кодировка — UTF-8 без BOM.
2. Заголовки столбцов должны быть в нижнем регистре и расположены в таком же порядке, как в шаблоне структуры таблицы.
3. Разделитель — точка с запятой (;).
4. Внутри полей в файле должны отсутствовать переносы строк.
5. Для типов данных, относящихся к дате, необходимо использовать формат записи: YYYY-MM-DD.
6. Для типов данных, относящихся к отпечатку времени (timestamp), необходимый формат записи: yyyy-MM-dd HH:mm:ss.
7. Количество полей данных в строке CSV-файла должно совпадать с количеством заголовков в таблице.
8. Если требуется передать в каком-либо поле null, то это поле обозначается разделителем. Например, если таблица содержит пять столбцов, и в четвертом поле требуется передать null, то строка данных в файле должна выглядеть  следующим образцу образом:

  Пример:

 v_1;v_2;v_3;;v_5

где: 

      v_* — данные для первого, второго, третьего и пятого столбцов таблицы.

Ниже представлен пример файла для загрузки:

column_1;column_2;column_3;column_4 1;1;1;val_0_4 2;;data;val_1_4 3;5;;val_2_4

здесь:

• column_1 — заголовок первого столбца, тип данных: bigint (not null);
• column_2 — заголовок второго столбца, тип данных: bigint (null);
• column_3 — заголовок третьего столбца, тип данных: varchar (null);

• column_4 — заголовок четвертого столбца, тип данных: varchar (not null).

Загрузка данных в витрину (метод POST)

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

В случае загрузки через терминал при помощи утилиты Curl запрос выглядит следующим образом:

curl --max-time 120 --header "Content-Type: text/csv" --data-binary  @<path_to_filename> http://<rest-uploader-host>:8181/v2/datamarts/<mnemonica_vd>/tables/<table_1>/upload

где:

• <path_to_filename> — абсолютный или относительный путь к CSV-файлу, подготовленному для загрузки;
• <rest-uploader-host> — хост, на котором развернут модуль REST-uploader;
• <mnemonica_vd> — мнемоника витрины данных;
• <table_1> — название таблицы внутри витрины данных, в которую необходимо загрузить данные.

  Примечание

 По умолчанию для обращения к REST-uploader используется порт 8181. Если в витрине данных этот порт задействован под другой модуль или приложение, необходимо указать другой порт. О том, как это сделать, читайте в статье «Установка минимального набора компонентов витрины “Стандарт”» (добавить ссылку на статью).

Чтобы проверить, какой порт в ВД задействован под модуль REST-uploader, на машине с установленным модулем просмотрите конфигурационный файл (env) контейнера с помощью команды:

docker exec rest-uploader-24 env

Рисунок 2 – Проверка номера порат в настройках контейнера REST-uploader

Удобнее использовать для отправки запросов на загрузку данных из файлов в витрину по REST API специальные приложения. Рассмотрим, как это сделать при помощи приложения Postman:

1.     В интерфейсе Postman выберите вкладку Collections, нажмите кнопку + и создайте новую коллекцию, дав ей понятное наименование.

2.     В созданную коллекцию добавьте запрос, дав ему понятное наименование, например Rest_uploader(upload) (Рисунок 3):

Рисунок 3 – Создание запроса в Postman-коллекции

После создания коллекции на правой панели отобразится область для создания запроса.

3.     Выберите метод передачи данных POST, в адресной строке укажите адрес: 
http://localhost:8181/v2/datamarts/<mnemonica_vd>/tables/<table_1>/upload

где:

• localhost:8181 — хост, на котором развернут модуль REST-uploader;
• <mnemonica_vd> — мнемоника витрины данных;
• <table_1> — название таблицы внутри витрины данных, в которую необходимо загрузить данные.

4.      Ниже адресной строки перейдите на вкладку Headers и задайте параметры заголовков (Рисунок 4):

• Key – выберите значение Content-Type,
• Value – укажите text/csv,
• Description – оставьте незаполненным.

Рисунок 4 – Редактирование параметров в Postman-коллекции. Вкладка Headers

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

• выберите радиокнопку binary для передачи бинарных объектов;
• приложите файл (Рисунок 5):

Рисунок 5 – Редактирование параметров в Postman-коллекции. Вкладка Body

На основании всех заданных настроек коллекции Postman сформирует запрос для отправки данных в витрину.

6.     Нажмите кнопку «Send».

Запрос будет отправлен (Рисунок 6):

Рисунок 6 – Адресная строка в Postman-коллекции. Кнопка отправки запроса

Варианты ответных сообщений при загрузке данных:

1)     Статус запроса – 200 ОК, в ответе отображается идентификатор запроса (request_ID). Это означает, что операция загрузки выполнена успешно (Рисунок 7):

Рисунок 7 – Запрос на загрузку завершен успешно

2)     Статус запроса – 200 ОК, ответ содержит фразу «Запрос буферизирован» (Рисунок 8). Это означает наличие проблем на стороне приёмщика, то есть витрины данных. Запрос не может быть выполнен, пока эти проблемы не будут устранены.

Рекомендация: обратиться в СЦ за помощью.

Рисунок 8 –Запрос буферизирован

3)     Статус запроса – 400 Bad Request, ответ содержит фразу «Отсутствуют файлы в запросе». Это означает, что к запросу не был приложен файл с данными (Рисунок 9):

Рисунок 9 –В запросе отсутствует файл с данными

Рекомендация: повторить отправку запроса, приложив файл.

4)     Статус запроса – 400 Bad Request, при попытке загрузки файла в ответе выводится информация с указанием на ошибку в файле. В примере, показанном на Рисунке 10, значение поля в загружаемом файле не соответствует типу данных, которые должны передаваться в соответствии со схемой, ожидается тип данных DATE:

Рисунок 10 – Ошибка в файле с данными

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

5)     При попытке загрузки файла выводится сообщение об ошибке «Could not send request» (Error: connect ECONNREFUSED). Это означает отсутствие сетевого подключения к модулю REST-uploader (Рисунок 11):

Рисунок 11 – Ошибка «Could not send request»

Рекомендация: проверить и исправить адрес для отправки запроса.

Удаление данных (метод POST)

Для удаления данных из витрины необходимо удалить эти данные из ранее загруженного в витрину CSV-файла и заново загрузить его.

Запрос на удаление данных через терминал при помощи утилиты Curl выглядит следующим образом:

curl --max-time 120 --header "Content-Type: text/csv" --data-binary  @<path_to_filename> http://<rest-uploader-host>:8181/v2/datamarts/<mnemonica_vd>/tables/<table_1>/delete

где:

• <path_to_filename> — абсолютный или относительный путь к CSV-файлу, загруженному на этапе загрузки данных (см. п. «Загрузка данных»);
• <rest-uploader-host> — хост, на котором развернут модуль REST-uploader;
• <mnemonica_vd> — мнемоника витрины данных;
• <table_1> — название таблицы внутри витрины данных, в которую необходимо загрузить данные.

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

1.     В существующую коллекцию добавьте новый запрос, дайте ему понятное наименование, например Rest_uploader(delete) (Рисунок 12):

Рисунок 12 – Создание нового запроса в Postman-коллекции

2.     На правой панели Postman выберите метод передачи данных POST, в адресной строке укажите адрес: http://localhost:8181/v2/datamarts/<mnemonica_vd>/tables/<table_1>/delete 

где:

• localhost:8181 — хост, на котором развернут модуль REST-uploader;
• <mnemonica_vd> — мнемоника витрины данных;
• <table_1> — название таблицы внутри витрины данных, в которую необходимо загрузить данные.

3.     Ниже адресной строки перейдите на вкладку Headers и задайте параметры заголовков:

• Key – выберите значение Content-Type,
• Value – укажите text/csv,
• Description – оставьте незаполненным.

4.     Перейдите на вкладку Body и выберите файл с данными для передачи:

• выберите радиокнопку binary для передачи бинарных объектов;
• приложите файл (см. п. «Загрузка данных»).

На основании всех заданных настроек коллекции Postman сформирует запрос для отправки данных в витрину.

5.     Нажмите кнопку «Send». При успешной загрузке файла (то есть успешном удалении данных) в ответ вернётся request_ID.

Проверка статуса обработки файла (метод GET)

По идентификатору запроса (request_ID), полученному после выполнения операции, можно проверить результаты обработки файла.

Запрос для выполнения такой проверки через терминал при помощи утилиты Curl выглядит следующим образом:

curl –X GET ‘http://<rest-uploader-host>:8181/v2/requests/<request_ID>/status’

где:

• <rest-uploader-host> — хост, на котором развернут модуль REST-uploader;
• <request_ID> — идентификатор запроса (request_ID), полученный в результате выполнения команды на загрузку или удаление данных.

При помощи приложения Postman отправить запрос на просмотр статуса можно следующим образом:

1.     В существующую коллекцию добавьте новый запрос, дайте ему понятное наименование, например Rest_uploader(status) (Рисунок 13):

Рисунок 13 – Создание нового запроса в Postman-коллекции

2.     На правой панели Postman выберите метод передачи данных GET, в адресной строке укажите адрес: http://localhost:8181/v2/requests/<request_ID>/status

3.     Нажмите кнопку «Send».
Запрос будет отправлен.

В ответе будет отражена следующая информация:

• код статуса обработки файла;
• описание статуса;
• описание ошибки. При отсутствии ошибок отображается слово null.

Пример проверки статуса запроса по request_ID представлен ниже (Рисунок 14):

Рисунок 14 – Проверка статуса обработки файла

Возможные статусы обработки файла:

 -1 – Загрузка данных в буфер
  0 –  Запрос буферизирован
  1 –  Ожидает открытия дельты
  2 –  В обработке
  3 –  Успешно обработан
  4 –  Ошибка обработки запроса
  5 –  Идентификатор запроса не обнаружен
  6 –  Форматно-логический контроль
  7 –  Ошибки ФЛК

  Примечание

 Успешной обработке файла соответствует статус 3. В случае получения статуса 4  необходимо убедиться, что загруженный файл с данными соответствует всем требованиям, описанным в разделе «Требования к загружаемым файлам».

ФЛК-проверки

Форматно-логический контроль (ФЛК) — это автоматизированная проверка данных в соответствии с установленными форматами и логическими правилами. Цель таких проверок — обеспечить высокое качество и корректность информации.

ФЛК-проверки подразделяются на:

1.   Синхронные проверки.

Особенности синхронных проверок:

• выполняются вне зависимости от настроек модуля REST-uploader;
• являются блокирующими;
• ошибки синхронных проверок возвращаются в теле ответа по REST API.

К синхронным относятся следующие проверки:

1)     Проверка соответствия инфосхеме:

• проверка соответствия имен и количества полей в заголовках;
• проверка типа данных;
• проверка экранирования данных: соответствие количества столбцов по каждой строке.

2)     Проверка соответствия файла кодировке UTF-8, отсутствие BOM (при наличии BOM при загрузке отрезаются начальные байты ef bb bf).

3)     Проверка максимально допустимого размера загружаемого файла:

• если файл хранится в Redis – 512Мб;
• если файл хранится в S3 – без ограничений на размер.

4)     Проверка наличия данных в файле.

2.   Асинхронные проверки.

Особенности асинхронных проверок:

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

К асинхронным относятся следующие проверки:

1)     Проверка уникальности полей:

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

2)     Сравнение значения с константой.

3)     Соответствие регулярному выражению.

  Примечание

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

Проверка уникальности по одному полю или по сочетанию полей

Проверка уникальности выполняется по следующим направлениям:

1.     В рамках группы файлов, если заданы headers — для проверки в рамках группы обязательно заполнение всех полей: 

• group_id;
• group_file_num;
• group_file_count.

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

15 - Пример запроса с прописанными полями

  Примечание

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

2.     По всем файлам в рамках группы – при наличии групповых атрибутов.

3.     По одному файлу – при отсутствии групповых атрибутов.

  Пример json-файла для проверки уникальности по группе файлов:

{     "fields": {         "id": {             "uniq": true,             "uniq-with": [                 "type",                 "region"             ]         },         "snils": {             "match": "/^[-\s\d]{11}$/",             "uniq": true         }     } }

  Описание блоков:

--проверка по сочетанию полей fields: id: uniq: true uniq-with: [type,region] --проверка уникальности по одному полю snils: match: "/^[-\s\d]{11}$/" uniq: true

Проверка соответствия заданному значению

Проверка на соответствие заданному значению проводится по следующему принципу:

• для каждого файла вне зависимости от наличия group_id;
• для значений каждого поля в соответствии с заданным правилом;
• когда включает в себя проверку сравнения с константой ('>', '<', ‘>=', '<=', '=', '!=' ).

Поведение в случае таймаута валидации

Период выполнения асинхронных проверок определяется конфигурационным параметром ‘validation-timeout’ и по умолчанию составляет 60 минут.

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

В случае возникновения подобной ошибки рекомендуется:

1)     Проверить регулярные выражения, по которым происходит проверка, так как неверно заданное регулярное выражение кратно увеличивает время проверки;

2)     Увеличить значение ‘validation-timeout’ и повторить загрузку данных.

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

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

Таблица 1 – Реализованные проверки

Наименование проверки	Код ошибки	Кириллическое описание в отчете
Проверка уникальности	dublicate	'дубликат файла/группы’
Проверка парсинга файла	parsingErr	'ошибка парсинга: * текст ошибки *'
Проверка кодирования	encodingErr	'кодировка файла не соответствует кодировке UTF-8'
Проверка превышения предельного размера файла (больше 512 Мб)	tooLargeFile	'слишком большой файл'
Проверка наличия данных в файле	emptyFile	'пустой файл'
Проверка соответствия заголовков инфосхеме	wrongMetadata	'структура файла не соответствует схеме'
проверка соответствия числа столбцов в строке	wrongFieldsCount	'некорректное число столбцов в строке'
Проверка соответствия типам полей	wrongFieldType	'значение не соответствует типу * требуемый тип *'
Проверка уникальности полей	nonUniq	'значение не отвечает требованиям уникальности'
Проверка регулярных выражений	nonMatchRegex	'значение не соответствует регулярному выражению *регулярное выражение*'
Проверка соответствия условию	nonMatchConstant	'значение не соответствует условию * условие *'
Таймаут валидации	validationTimeout	'истек таймаут валидации файла'

РАБОТА С ФЛК ЧЕРЕЗ REST-UPLOADER

REST-uploader позволяет выполнять загрузку данных в витрину с учётом форматно-логического контроля (ФЛК). Данный механизм может использоваться в случае, когда в витрину данных необходимо загрузить только строки, прошедшие проверку ФЛК. Строки, которые не прошли проверку, загружены не будут.

Перед дальнейшими действиями следует подготовить json-файл по аналогии с примером json-файла для проверки уникальности по группе файлов.

Включение проверок ФЛК

Для того, чтобы включить ФЛК-проверки необходимо изменить настройки конфигурации модуля Rest-uploader. Файле application.yaml модуля Rest-uploader, определяющего конфигурационные параметры проверок ФЛК, расширен блоком conditions, который включает в себя настройки, приведенные в таблице 2.

Таблица 2 – Описание настроек для проверок ФЛК в блоке conditions

Наименование настройки	Описание настройки	Значение по умолчанию	Возможные значения
mode	Включение/отключение асинхронных проверок ФЛК и поведение при обнаружении ошибок	warning	-  off проверки выключены, отчет не формируется -  skip_string пропуск строки, в отчет попадают все ошибки - skip_file пропуск файла, в отчет попадают все ошибки -  skip_on_first_err пропуск файла по первой ошибке, в отчет попадает первая ошибка -  skip_string_except_last пропускаются строки не прошедшие ФЛК по уникальности кроме последней -  warning все строки передаются в Redis (даже ошибочные), только формируется отчет
save-time	Период хранения отчетов об ошибках по итогам ФЛК и отчетов по группе	1d	Время в днях
save-path	Путь к месту хранения журналов ошибок на общем диске, значение по умолчанию	/tmp/REST-Uploader/reports
zookeeper-path	Путь к месту хранения правил в Zookeeper ADS	/adapter/[env]/REST-Uploader/conditions
rest-timeout	Тайм-аут обработки REST-запроса	60s	Время в секундах
save_group_time	Период жизни группы	1d	Время в днях
validation-timeout	Тайм-аут валидации	60m	Время в минутах
poll-timeout	Тайм-аут процесса валидации	30s	Время в секундах
max-concurrent-handle	Число корутин асинхронной валидации	1
batch-size	Размер порции вычитки сообщений из Redis	1
charset-check-enabled	Включение/выключение проверки кодировки файла	true	true/false
timeout-active	Период жизни флага активности модуля	3m	Время в минутах
publish-period	Период обновления статуса активности модуля	30s	Время в секундах

Необходимо найти настройку CONDITIONS_MODE и поменять значение по умолчанию – warning на возможное значение в соответствии с таблицей 2.

Рисунок 16 – Env модуля REST-uploader

Загрузка списка правил для сохранения таблицы в Zookeeper

Для того чтобы загрузить список правил для сохранения таблицы в Zookeeper, необходимо выполнить следующую команду:

curl --max-time 120 --header "Content-Type: text/csv" --data-binary  @<path_to_filename> http://<rest-uploader-host>:8181/v2/conditions/<mnemonica_vd>/<table_1>

где:

• <path_to_filename> — абсолютный или относительный путь к json-файлу со списком правил, подготовленному для загрузки;
• <rest-uploader-host> — хост, на котором развернут модуль REST-uploader;
• <mnemonica_vd> — мнемоника Витрины данных;
• <table_1> — название таблицы внутри витрины данных.

Пример результата загрузки и удаления списка правил показан на рисунке 17:

Рисунок 17 – Postman. Результат загрузки списка правил

  Примечание

 В случае повторного выполнения запроса файл проверок полностью перезаписывается.

Удаление всего списка проверок по таблице

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

curl -X DELETE --header "Content-Type: text/csv" --data-binary  @<path_to_filename> http://<rest-uploader-host>:8181/v2/conditions/<mnemonica_vd>/<table_1>

где:

• <path_to_filename> — абсолютный или относительный путь json-файлу, подготовленному на предыдущем шаге;
• <rest-uploader-host> — хост, на котором развернут модуль rest-uploader;
• <mnemonica_vd> — мнемоника Витрины данных;
• <table_1> — название таблицы внутри витрины данных.

Получение списка проверок для таблицы, хранящейся в Zookeeper

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

сurl -X GET ‘http://<rest-uploader-host>:8181/v2/conditions/<mnemonica_vd>/<table_1>’

где:

• <rest-uploader-host> — хост, на котором развернут модуль REST-uploader;
• <mnemonica_vd> — мнемоника Витрины данных;
• <table_1> — название таблицы внутри витрины данных.

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

Рисунок 18 – Postman. Результат запроса списка проверок для таблицы

Получение отчета о форматно-логическом контроле загружаемых данных в формате CSV

Получение отчёта о ФЛК происходит по следующему запросу:

сurl -X GET
‘http://<rest-uploader-host>:8181/v2/requests/<request_ID>/report/’

где:

• <rest-uploader-host> — хост, на котором развернут модуль REST-uploader;
• <request_ID> — request_ID, полученный в рамках загрузки.

В результате сформируется отчет в формате CSV-файла.

  Пример возвращаемых данных в отчёте:

"line";"field";"err_code";"value";"text"
"3";"";"wrongFieldsCount";"";"некорректное число столбцов в строке"