В некоторых случаях для загрузки данных в mybi connect может использоваться специальное описание в формате JSON, в котором перечислены правила для разбора входного набора данных и загрузки его в таблицы БД. На данный момент этот функционал доступен в выгрузке пользовательских отчетов и в вебхуках.
Далее мы подробно разберем формат на примере описания, использованного при выгрузке расходов из Google Analytics:
Данные, которые мы получаем на вход, имеют следующий вид:
Параметры таблиц
Начнем с того, что описание по своей сути является ни чем иным, как просто списком таблиц, в которые должны загружаться входные данные. В результате чего в приведенном выше примере мы видим три элемента массива, то есть три таблицы. В описании каждой таблицы существует ряд параметров
которые мы сейчас рассмотрим подробнее.
table
Тип: строка
Обязательный: да
Название таблицы в базе данных. Может содержать английские буквы, цифры и символы подчеркивания. Этот параметр обрабатывается сервисом в зависимости от значения параметра shared:
- true — параметр должен содержать полное название таблицы, например general_traffic
- false — к названию в параметре будет автоматически добавляться префикс источника, допустим webhook_ для вебхуков
description
Тип: строка
Обязательный: нет
Краткое описание таблицы, которое используется в качестве названия представления. Мы рекомендуем использовать понятное название на русском, так как представление в большей степени необходимо для удобства работы с данными.
type
Тип: строка
Обязательный: нет
Тип таблицы, необязательный параметр, который может иметь значение:
- dimension
- attribute
- fact
Данный параметр необходим для использования правильного способа при сохранении данных в таблицу. Когда в организации связей между таблицами в базе данных нет необходимости, этот параметр можно не использовать.
shared
Тип: логический
Обязательный: нет
Флаг, отражающий является ли таблица общей, то есть, может ли использоваться несколькими различными источниками/заданиями, или нет.
order
Тип: целое число
Обязательный: нет
Очередь удаления данных из таблицы. К примеру, если в базе данных мы имеем “снежинку”, то данные из таблицы измерений должны удаляться в последнюю очередь, к примеру:
- 1 — fact
- 2 — attribute
- 3 — dimension
В случае, когда между таблицами нет связей, данный параметр можно не использовать.
date
Тип: строка
Обязательный: нет
Имя поля типа “дата”, которое будет использоваться для удаления данных при перевыгрузке данных за период
fields
Тип: массив
Обязательный: да
Описание полей таблицы.
Параметры полей
Учитывая что описание полей, так же, как и описание таблиц, имеют ряд собственных параметров
мы рассмотрим их отдельно.
name
Тип: строка
Обязательный: да
Название таблицы в базе данных. Может содержать английские буквы, цифры и символы подчеркивания.
description
Тип: строка
Обязательный: нет
Краткое описание поля, которое используется в качестве названия поля в представлении. Как и в случае с названием представления, мы рекомендуем использовать понятное название на русском для дальнейшего удобства работы с данными.
type
Тип: строка
Обязательный: да
Тип и размерность поля. Может иметь одно из следующих значений:
- string(длина)
- integer
- float
- json
- datetime
- timestamp
- date
- boolean
Данный параметр позволяет преобразовывать входные данные в необходимый тип при сохранении их в БД.
primary
Тип: логический
Обязательный: нет
Флаг, показывающий, является ли текущее поле первичным ключом в исходных данных, к примеру, какой-либо уникальный идентификатор, на основании которого могут формироваться таблицы измерений.
index
Тип: логический
Обязательный: нет
Флаг, показывающий, необходимо ли создавать индекс по этому полю в таблице БД. Полезно указывать true для полей, в которых хранятся какие-либо уникальные идентификаторы, или по которым может быть организован поиск данных в БД.
nullable
Тип: логический
Обязательный: нет
Флаг, отражающий, может ли поле быть пустым.
default
Тип: произвольный
Обязательный: нет
Значение, которое будет использоваться по умолчанию для записи в поле таблицы, в случае, если не указан путь для извлечения или в результате извлечения не были получены данные. Этот параметр особенно важен, если поле не допускает пустых значений.
source
Тип: строка
Обязательный: да
Секция из которой извлекаются данные. Может иметь одно из трех значений:
- request — основной набор данных, полученный из сервиса-источника
- details — вспомогательный набор данных, формируемый mybi connect
- tables — набор данных, сохраненный в БД
path
Тип: строка
Обязательный: да
Путь для извлечения данных из набора. Для указания пути используется JSONPath, с синтаксисом которого можно более подробно ознакомиться здесь.
Учитывая, что на данный момент все описание формируется вручную, и в результате этого довольно высока вероятность ошибок, мы рекомендуем перед использованием полученного JSON у нас в сервисе проверить его синтаксис на корректность при помощи таких онлайн-сервисов, как “JSON Formatter & Validator” и использовать уже отформатированное описание, скопировав его из результата форматирования.