.. _rest_uploader_doc:

Общее описание
^^^^^^^^^^^^^^

.. attention:: С версии 2.6.0 по умолчанию для хранения персистентных данных используется Prostore версии 7.6 и выше с хотя бы одним ADP 
               (для обеспечения высокой доступности персистентных данных модуля необходимо использование больше одного датасорса ADP). 

REST-Uploader - Модуль асинхронной загрузки данных из сторонних источников реализован для обеспечения параллельного обновления 
данных в Компоненте "Витрина данных" с независимым масштабированием REST-интерфейса.

Операции с данными:

- загрузка: отправка запроса на ``.../upload``;
- Модификация данных из внешних источников: отправка запроса на ``.../modify``;
- логическое удаление: отправка запроса на ``.../delete`` (при этом для логических таблиц данные только помечаются как удаленные);
- удаление исторических данных: отправка запроса на ``.../truncate``.

В :numref:`tab_rest_uploader_functions` приведен перечень операций, выполняемых REST-Uploader с данными Витрины.

.. _tab_rest_uploader_functions:

.. table:: Функции REST-Uploader

    +--------------+---------------------------------------+-----------------------------------------------------------------------------------+
    | **Операция** | **Описание операций**                 | **Поддерживаемые режимы для типов таблиц**                                        |
    |              |                                       +---------------------+-------------------+-------------------+---------------------+
    |              |                                       | Логическая          | proxy             | standalone        | spapshot            |
    +==============+=======================================+=====================+===================+===================+=====================+
    | upsert       | Загрузка или обновление данных для    | llw, stream         | llw, stream       | llw, stream       | llw, stream         |
    |              | переданного набора первичных ключей   |                     |                   |                   |                     |
    | без sys_op   |                                       |                     |                   |                   |                     |
    +--------------+---------------------------------------+---------------------+-------------------+-------------------+---------------------+
    | delete       | Удаление данных по переданному        | llw, stream         | llw               | llw               | llw, stream         |
    |              | набору первичных ключей               |                     |                   |                   |                     |
    | без sys_op   |                                       |                     |                   |                   |                     |
    +--------------+---------------------------------------+---------------------+-------------------+-------------------+---------------------+
    | truncate     | Удаление данных, включая исторические | llw                 | llw               | llw               | llw                 |
    |              |                                       |                     |                   |                   |                     |
    | без sys_op   |                                       | [с for_system_time] |                   |                   | [с for_system_time] |
    +--------------+---------------------------------------+---------------------+-------------------+-------------------+---------------------+
    | modify       | Cовмещение загрузки и логического     | stream              | не поддерживается | не поддерживается | stream              |
    |              | удаления в одной операции.            |                     |                   |                   |                     |
    | с sys_op     |                                       |                     |                   |                   |                     |
    +--------------+---------------------------------------+---------------------+-------------------+-------------------+---------------------+

.. note:: Для управления прикладными данными в снапшот-таблицах требуется обновление REST-Uploader до версии 2.6.0 и выше.
          Все изменения данных снапшот-таблиц выполняются в операциях записи, но вне механизма дельт. Т.е. при открытой дельте данные не изолируются 
          (запишутся/удалятся сразу, не дожидаясь закрытия дельты) и не откатываются при выполнении rollback delta.

Спецификация модуля асинхронной загрузки данных из сторонних источников приведена в документе "Руководство администратора Компонента Витрина данных" в :numref:`rest_uploader_specification`.

.. attention:: Не рекомендуется использовать персональные данные в качестве первичного ключа, т.к. первичный ключ может отображаться в логах Системы при удалении истории.

Обеспечена буферизация поступающих на загрузку данных. Буферизированные данные направляются в базу менеджером дельт с 
группировкой по датамартам. 

Обеспечены следующие функциональные особенности:

- идентификатор в формате строки;
- метаданные от сервера витрины кешируются механизмом, и проверяются на соответствие по количеству и по типам полей (при 
  несоответствии загружаемых данных метаданным целевой таблицы сервис для передачи / загрузки данных возвращает статус запроса 
  с ошибкой, без размещения данных в очереди на загрузку);
- загруженные данные размещаются вместе с UUID в очереди с именем «queue»;
- формируется запись с ключом «status.[UUID запроса]» и статусом 0 в очереди;
- клиенту, отправившему запрос, возвращается успешный статус запроса вместе с UUID;
- в логе приложения формироваться запись события получения запроса на загрузку с указанием идентификатора запроса, 
  идентификатора ВУЗа, времени обработки и размера загруженных данных.

.. attention:: Загружаемые файлы обязательно должны быть в кодировке UTF-8

.. note:: Заливка данных через через модуль REST-Uploader не предусматривают параллельную заливку в датамарты вместе с другими инструментами. 
          Параллельная заливка данных в те же датамарты вручную или средствами ETL приведет к конфликту в работе с дельтами и к ошибкам соответственно.

Общие правила формата загружаемых CSV-файлов приведены в таблице :numref:`csv_format_rest_uploader`.


.. _csv_format_rest_uploader:


.. table:: Общие правила формата загружаемых CSV-файлов

  +------------------------+----------------------------------------------------------------------------+
  | Параметр               | Значение                                                                   |
  +========================+============================================================================+
  | Разделитель строк      | Любой вариант из:  CR/LF (0x0D0A), CR (0x0D), LF (0x0A)                    |
  +------------------------+----------------------------------------------------------------------------+
  | Разделитель полей      | по настройке csv-parser/separator (:numref:`csv_uploader_config_params`)   |
  +------------------------+----------------------------------------------------------------------------+
  | Строка заголовка       | да (обязательно)                                                           |
  +------------------------+----------------------------------------------------------------------------+
  | Порядок полей в        | определяется строкой заголовка                                             |
  | строке                 |                                                                            |
  +------------------------+----------------------------------------------------------------------------+
  | Ограничитель           | по настройке csv-parser/quote-char (:numref:`csv_uploader_config_params`)  |
  | текстового поля        |                                                                            |
  +------------------------+----------------------------------------------------------------------------+
  | Символ маскировки      | по настройке csv-parser/escape-char (:numref:`csv_uploader_config_params`) |
  | в текстовом поле       |                                                                            |
  +------------------------+----------------------------------------------------------------------------+
  | Обнаружение            | До релиза 1.5.0 (включительно): по настройке csv-parser/field-as-null      |
  | значения null          | (:numref:`csv_uploader_config_params`)                                     |
  |                        |                                                                            |
  |                        | начиная с релиза 1.10.0: в текущей реализации парсера данная настройка     |
  |                        | не поддерживается                                                          |
  +------------------------+----------------------------------------------------------------------------+
  | Кодирование символов   | UTF-8                                                                      |
  +------------------------+----------------------------------------------------------------------------+
  | Десятичный разделитель | символ ``.`` (0x2E), может не указываться для целых значений               |
  +------------------------+----------------------------------------------------------------------------+
  | Формат даты            | любой из: ``dd.MM.yyyy``, ``yyyy-MM-dd``                                   |
  +------------------------+----------------------------------------------------------------------------+
  | Формат времени         | любой из: ``HH:mm:ss``, ``H:mm:ss``                                        |
  +------------------------+----------------------------------------------------------------------------+
  | Формат даты-времени    | до релиза 1.5.0(включительно) любой из: ``yyyy-MM-dd HH:mm:ss``,           |
  |                        | ``dd.MM.yyyy HH:mm:ss``                                                    |
  |                        |                                                                            |
  |                        | начиная с релиза 1.10.0 любой из: ``yyyy-MM-dd HH:mm:ss.000000``,          |
  |                        | ``dd.MM.yyyy HH:mm:ss.000000``                                             |
  +------------------------+----------------------------------------------------------------------------+