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

Загрузка данных в систему производится в виде сообщений, каждое из которых имеет структуру, представленную на Рисунок - 4.9

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

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

Тело сообщения представляет собой файл Avro (Object Container File), который состоит из заголовка и блоков данных.
Заголовок файла содержит схему данных Avro.
Схема данных содержит следующие элементы:
- имя;
- тип “record”;
- перечень полей.
Последним полем схемы должно быть указано служебное поле sys_op с типом данных avro.int.
Каждый блок данных содержит запись, представленную в бинарной кодировке.
Каждая запись содержит перечень полей и их значений.
Состав и порядок полей должны совпадать во всех следующих объектах:
- в схеме данных заголовка файла Avro;
- в наборе загружаемых записей;
- во внешней таблице загрузки (поле sys_op должно отсутствовать);
- в таблице-приемнике данных (поле sys_op должно отсутствовать).

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

Примечание

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

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

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

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

{
  "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-формате.

[
  {
      "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
  }
]

3. Особенности реализации ETL

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

Генерация первичных ключей записей, передаваемых для загрузки, производится на стороне источника.
Каждая Avro-структура должна содержать данные только для одной таблицы Витрины.
В Avro-структурах данных источник заполняет тип операции sys_op:
- 0 – для добавления новой или обновления существующей записи;
- 1 – для удаления существующей записи (см. пример записей Avro в Раздел 4.17.2.1).
ETL не выполняет преобразования данных, предназначенных для загрузки в Витрину данных.
При выполнении операций, требующих консистентности данных, в рамках одной дельты могут быть только операции одного типа: либо добавления/обновления, либо удаления. При этом в рамках одной дельты первичные ключи всех записей должны быть уникальны.
Не должно быть двух версий одной записи в рамках одной дельты.
Нельзя менять порядок атрибутов в avro-схеме, поскольку данные при загрузке в БД распределяются в соответствии с тем перечнем, который был указан в avro-схеме.

4. Получение токена Рroxy API

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

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

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##, где ## – номер региона).

Примечание

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

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

{
  "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"
}

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

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 — данные запроса.