.. _etl_config:

Основные требования к исходным файлам
#######################################

Загрузка данных в систему производится в виде сообщений, каждое из которых имеет структуру, представленную на :ref:`message_structure`

.. _message_structure:

.. figure:: img/message_structure.png
         :align: center
         :alt: Структура загружаемых сообщений

         Структура загружаемых сообщений

Для успешной загрузки данные должны соответствовать следующим условиям:

1. Тело сообщения представляет собой файл Avro (**Object Container File**), который состоит из заголовка и блоков данных. 
2. Заголовок файла содержит схему данных Avro.
3. Схема данных содержит следующие элементы: 

   - имя;
   - тип “record”;
   - перечень полей.

4. Последним полем схемы должно быть указано служебное поле ``sys_op`` с типом данных ``avro.int``. 
5. Каждый блок данных содержит запись, представленную в бинарной кодировке. 
6. Каждая запись содержит перечень полей и их значений. 
7. Состав и порядок полей должны совпадать во всех следующих объектах:

   - в схеме данных заголовка файла Avro;
   - в наборе загружаемых записей;
   - во внешней таблице загрузки (поле ``sys_op`` должно отсутствовать);
   - в таблице-приемнике данных (поле ``sys_op`` должно отсутствовать).

Более подробно про формат данных Avro описано в источнике: https://avro.apache.org/docs/1.10.2/spec.html#Object+Container+Files

.. note:: В загружаемой схеме данных Avro и записях Avro важны порядок и тип полей. Имена полей не сравниваются с именами полей внешней таблицы и таблицы-приемника.

Пример ниже содержит схему данных Avro, используемую для загрузки данных о сотрудниках в таблицу ``staff``. 

Для поля ``date_of_birth`` указан логический тип Avro, для поля ``middle_name`` — элемент union (поле является не обязательным 
для заполнения, поэтому маркер ``null`` выведен в отдельный параметр).

Пример схемы данных Avro:

.. code-block:: json

  {
    "name": "staff",
    "type": "record",
    "fields": [
        {
        "name": "id",
        "type": "long"
        },
        {
        "name": "firstname",
        "type": "string"
        },
        {
        "name": "lastname",
        "type": "string"
        },
        {
        "name": "middle_name",
        "type": [
            "null",
            "string"
        ]
        },
        {
        "name": "date_of_birth",
        "type": {
        "logicalType": "timestamp-micros",
        "type": "long"
        }   
        },
        {
        "name": "employee_position",
        "type": "string"
        },
        {
        "name": "department_category",
        "type": "long"
        },
        {
        "name": "sys_op",
        "type": "int"
        }
    ]
  }

Пример ниже содержит набор записей о сотрудниках, загружаемых в таблицу ``staff``. 

Для наглядности примера бинарные данные представлены в JSON-формате.

.. code-block:: json

  [
    {
        "id": 1000111,
        "firstname": "Елена",
        "lastname": "Фролова",
        "middle_name": "Андреевна",
        "date_of_birth": 4641084000000000,
        "employee_position": "Менеджер по подбору персонала",
        "department_category": 1,
        "description": "Сотрудники отдела кадров",
        "sys_op": 0
    },
    {
        "id": 1000005,
        "firstname": "Пётр",
        "lastname": "Платонов",
        "middle_name": "",
        "date_of_birth": 5639904000000000,
        "employee_position": "Руководитель отдела кадров",
        "department_category": 1,
        "description": "Сотрудники отдела кадров",
        "sys_op": 0
    }
  ]

.. _etl_implementation:

Особенности реализации ETL
#############################

Функциональные особенности реализованного ETL включают в себя следующие пункты:

1. Генерация первичных ключей записей, передаваемых для загрузки, производится на стороне источника.
2. Каждая Avro-структура должна содержать данные только для одной таблицы Витрины.
3. В Avro-структурах данных источник заполняет тип операции ``sys_op``:

   - 0 – для добавления новой или обновления существующей записи;
   - 1 – для удаления существующей записи (см. пример записей Avro в :ref:`etl_config`).

4. ETL не выполняет преобразования данных, предназначенных для загрузки в Витрину данных.
5. При выполнении операций, требующих консистентности данных, в рамках одной дельты могут быть только операции одного типа: либо 
   добавления/обновления, либо удаления. При этом в рамках одной дельты первичные ключи всех записей должны быть уникальны.
6. Не должно быть двух версий одной записи в рамках одной дельты.
7. Нельзя менять порядок атрибутов в avro-схеме, поскольку данные при загрузке в БД распределяются в соответствии с тем 
   перечнем, который был указан в avro-схеме.

.. _token_get:

Получение токена Рroxy API
#############################

Этапы настройки Proxy API включают в себя следующие шаги:

1. Для начала необходимо пройти авторизацию в Datamart Studio. Сделать это можно, направив запрос ниже:

.. code-block:: 

    curl -X POST \
    'http://<ip-studio>:8088/api/v1/auth_system' \
    -d "username=<username>" \
    -d "password=<password>" \
    -d "organization_ogrn=<organization_ogrn>" \
    -d "datamart_mnemonic=<datamart_mnemonic>"

где:

- ``ip-studio`` — ip-адрес Datamart Studio;
- ``username`` — имя пользователя IAM;
- ``password`` — пароль пользователя IAM;
- ``organization_ogrn`` — ОГРН организации, в рамках которой развёрнута Витрина данных;
- ``datamart_mnemonic`` — мнемоника Витрины (пример: eduejd##, где ## – номер региона).

.. note:: Безопасность передачи данных по протоколу HTTP обеспечивается защищенной сетью. Требуется обращать внимание на протокол запроса. Если он будет некорректным (например, HTTPS вместо HTTP), то ответ сервера будет содержать ошибку с кодом 500 - InternalServerError.

Пример успешного ответа Datamart Studio на запрос токена представлен ниже:

.. code-block::

  {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI5NGRuNzhOeVF2TjBhRG3NMcUdkc0tTOTNlTWxjNkRwRjZ5V1NXSUo4In0.eyJleHAiOjE2OTMzMTg0NzIsImlhdCI6MTY5MzMxNDg3MiwianRpIjoiYTJkNTQ5NDktZWYwZC00MzA1LWI5OTAtMDIxMTAyZDkzODU2IiwiaXNzIjoiaHR0cHM6Ly9rYy5kYXRhbWFydC5ydS9yZWFsbXMvc3R1ZGlvLWRldiIsInN1YiI6IjE1NjdkYWI3LTc1OTAtNGM0Zi1iNWNhLWYzMmFkOTU1NThjYyIsInR5cCI6IkJlYXJlciIsImF6cCI6InN0dWRpbyIsInNlc3Npb25fc3RhdGUiOiJlMGE0MjJlZC1hNDQxLTQzY2MtYTAxMS01MzNiY2RiNTc5OGQiLCJhY3IiOiIxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbInN1cGVyYWRtaW4iLCJhZG1pbiJdfSwic2NvcGUiOiJvcGVuaWQgZW1haWwiLCJzaWQiOiJlMGE0MjJlZC1hNDQxLTQzY2MtYTAxMS01MzNiY2RiNTc5OGQiLCJ1cG4iOiJhZG1pbiIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJhZGRyZXNzIjp7fSwibmFtZSI6ImFkbWluIGFkbWluIiwiZ3JvdXBzIjpbInN1cGVyYWRtaW4iLCJhZG1pbiJdLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhZG1pbiIsImdpdmVuX25hbWUiOiJhZG1pbiIsIm9yZ2FuaXphdGlvbl9vZ3JuIjpbIjExMTIyMjMzMzQ0NCIsIjExMTEiXSwiZmFtaWx5X25hbWUiOiJhZG1pbiIsImVtYWlsIjoiYWRtaW5AYWRtaW4uYWRtaW4ifQ.BC3sREXC3nf2LNvBX8SiHKouVGqJVfUBokVJa-B-9YW0zLhnNTs7mGZVOnC-kM-5mWE6bz8du0lvxQqiGpi3HRlAv1eedcGMTf_2TmjhohAaz--zSCdLC5NSmI79r54XYTLORiWKXj5T_AY8efFwWnWgUJ1LEkd5BTQyGSTvaoJkMv7xextA_isx_WoReHC5_-3GznNtcf_hOd2J1CfMHUFjhqMRSxMkIQDPHnspgU6WUz9IeVA1VWKh1GcggqYDtrruigQcl4_f7XeJQKJ49NNVdhjHtywUVbTpEDKYh4FsgAbf3vIPYUVwGWFW0Qm7LgUCpB8UvMQfb4UYZMF4UA",
    "expires_in": 3600,
    "refresh_expires_in": 3600,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmYmMzOWNmNi1kZTRkLTQ2YWEtYTAwZi1iZGU3ZmFkNTJmNTgifQ.eyJleHAiOjE2OTMzMTg0NzIsImlhdCI6MTY5MzMxNDg3MiwianRpIjoiYWIxN2M0MzQtZGI4Yi00N2QwLTkyM2YtMTFiYmM3NzBiNmE4IiwiaXNzIjoiaHR0cHM6Ly9rYy5kYXRhbWFydC5ydS9yZWFsbXMvc3R1ZGlvLWRldiIsImF1ZCI6Imh0dHBzOi8va2MuZGF0YW1hcnQucnUvcmVhbG1zL3N0dWRpby1kZXYiLCJzdWIiOiIxNTY3ZGFiNy03NTkwLTRjNGYtYjVjYS1mMzJhZDk1NTU4Y2MiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoic3R1ZGlvIiwic2Vzc2lvbl9zdGF0ZSI6ImUwYTQyMmVkLWE0NDEtNDNjYy1hMDExLTUzM2JjZGI1Nzk4ZCIsInNjb3BlIjoib3BlbmlkIGVtYWlsIiwic2lkIjoiZTBhNDIyZWQtYTQ0MS00M2NjLWEwMTEtNTMzYmNkYjU3OThkIn0.SI6Tb6CJ5HIHwzETOyJZ-2nTLibGNq7JEQwW07fY-2M",
    "token_type": "Bearer",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI5NGRuNzhOeVF2TjBhRGtvX3NMcUdkc0tTOTNlTWxjNkRwRjZ5V1NXSUo4In0.eyJleHAiOjE2OTMzMTg0NzIsImlhdCI6MTY5MzMxNDg3MiwiYXV0aF90aW1lIjowLCJqdGkiOiI5NDM1ZDE3NS00MzE2LTQyN2QtODlkYi1lYTJkOWJlZjJmNWIiLCJpc3MiOiJodHRwczovL2tjLmRhdGFtYXJ0LnJ1L3JlYWxtcy9zdHVkaW8tZGV2IiwiYXVkIjoic3R1ZGlvIiwic3ViIjoiMTU2N2RhYjctNzU5MC00YzRmLWI1Y2EtZjMyYWQ5NTU1OGNjIiwidHlwIjoiSUQiLCJhenAiOiJzdHVkaW8iLCJzZXNzaW9uX3N0YXRlIjoiZTBhNDIyZWQtYTQ0MS00M2NjLWEwMTEtNTMzYmNkYjU3OThkIiwiYXRfaGFzaCI6Ik9UZzZoUFQtWjhhWHR1Yjl1VV91LWciLCJhY3IiOiIxIiwic2lkIjoiZTBhNDIyZWQtYTQ0MS00M2NjLWEwMTEtNTMzYmNkYjU3OThkIiwidXBuIjoiYWRtaW4iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiYWRkcmVzcyI6e30sIm5hbWUiOiJhZG1pbiBhZG1pbiIsImdyb3VwcyI6WyJzdXBlcmFkbWluIiwiYWRtaW4iXSwicHJlZmVycmVkX3VzZXJuYW1lIjoiYWRtaW4iLCJnaXZlbl9uYW1lIjoiYWRtaW4iLCJvcmdhbml6YXRpb25fb2dybiI6WyIxMTEyMjIzMzM0NDQiLCIxMTExIl0sImZhbWlseV9uYW1lIjoiYWRtaW4iLCJlbWFpbCI6ImFkbWluQGFkbWluLmFkbWluIn0.K372NBffA3xtsxyM3hixr5GF1ouHNdr8DFMBYnGQ-t-REbYcwOymvs-D-HYEsmaUhkCWjKSeLM9taLmAPloSt2hb8xN_VG4s-gc_yvGs_aHkUehTqddjGMislPyAlydzCaDVxQ5Px-TplsDzIAwm5P0V23LDU3qwnVxVR7P3Dbxi5YB84_38zjClNrDWt9YOxnPMCzDT4fnBjGXkDcQZoHo5jsbFP_K5ymugsYEumKIZyekbY_l_A-XkRcTM6SMTRhKLAvQ3lq2YguLm2LFF3e-PrGsaEymeS-Peuff5qJw5Vf9r3_nD3APCivVc0Kunl8miRpr3lsZgSAp-xi3Jow",
    "not-before-policy": 0,
    "session_state": "e0a422ed-a441-43cc-a011-533bcdb5798d",
    "scope": "openidemail"
  }

2. С полученным токеном послать запрос для подключения к API инсталляции приложения типового ПО Витрины данных для выбранной 
   организации:

.. code-block:: 

    curl -X <method>
    'http://<ip-studio>:8088/api/v1/secure/<organization_ogrn>/<datamart_mnemonic>/<installation_name>/<installation_id>/<request_path>' \
    -H "Authorization: Bearer <access_token>" \
    -H "<headers>" \
    -d "<data>"

где:

- ``ip-studio`` — ip-адрес Datamart Studio;
- ``organization_ogrn`` — ОГРН организации, в рамках которой развёрнута Витрина данных;
- ``datamart_mnemonic`` — мнемоника Витрины (пример: eduejd##, где ## – номер региона);
- ``installation_name`` — имя инсталляции в целевой Витрине;
- ``installation_id`` — идентификатор инсталляции (присутствует в её названии);
- ``request_path`` — URI оригинального API инсталляции;
- ``access_token`` — токен Proxy API;
- ``headers`` — заголовки запроса;
- ``data`` — данные запроса.