Описание формата загрузки данных

В некоторых случаях для загрузки данных в 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, с синтаксисом которого можно более подробно ознакомиться здесь.

format

Тип: строка Обязательный: нет

Формат исходных данных для преобразования. Обязателен для полей типа date, datetime, timestamp. С параметрами формата можно более подробно ознакомиться здесь.

Учитывая, что на данный момент все описание формируется вручную, и в результате этого довольно высока вероятность ошибок, мы рекомендуем перед использованием полученного JSON у нас в сервисе проверить его синтаксис на корректность при помощи таких онлайн-сервисов, как “JSON Formatter & Validator” и использовать уже отформатированное описание, скопировав его из результата форматирования.

// var firstViewer=new JSONViewer();var secondViewer=new JSONViewer();var thirdViewer=new JSONViewer();var fourthViewer=new JSONViewer();document.querySelector(“#json1”).appendChild(firstViewer.getContainer());document.querySelector(“#json2”).appendChild(secondViewer.getContainer());document.querySelector(“#json3”).appendChild(thirdViewer.getContainer());document.querySelector(“#json4”).appendChild(fourthViewer.getContainer());first_json=JSON.stringify([{“table”:“general_traffic”,“description”:“Параметры трафика”,“type”:“dimension”,“shared”:!0,“order”:3,“fields”:[{“name”:“grouping”,“description”:“Название группы”,“type”:“string(128)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:channelGrouping’”},{“name”:“source”,“description”:“Источник”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:source’”},{“name”:“medium”,“description”:“Канал”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:medium’”},{“name”:“campaign”,“description”:“Кампания”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:campaign’”},{“name”:“content”,“description”:“Объявление”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:adContent’”},{“name”:“keyword”,“description”:“Ключевое слово”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:keyword’”},{“name”:“landing_page”,“description”:“Страница входа”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:landingPagePath’”}]},{“table”:“general_sites”,“description”:“Параметры сайтов”,“type”:“dimension”,“shared”:!0,“order”:3,“fields”:[{“name”:“domain”,“description”:“Доменное имя”,“type”:“string(64)”,“primary”:!0,“index”:!0,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:hostname’”},{“name”:“description”,“description”:“Описание”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:null,“path”:null}]},{“table”:“general_costs_facts”,“description”:“Статистика по расходам”,“date”:“dates_id”,“type”:“fact”,“shared”:!0,“order”:1,“fields”:[{“name”:“dates_id”,“description”:“Идентификатор даты”,“type”:“date”,“primary”:!1,“index”:!0,“nullable”:!1,“source”:“details”,“path”:“$.simple_date”},{“name”:“sites_id”,“description”:“Идентификатор сайта”,“type”:“integer”,“primary”:!1,“index”:!1,“nullable”:!1,“source”:“tables”,“path”:“$.general_sites[0].id”},{“name”:“traffic_id”,“description”:“Идентификатор источника трафика”,“type”:“integer”,“primary”:!1,“index”:!0,“nullable”:!1,“source”:“tables”,“path”:“$.general_traffic[0].id”},{“name”:“impressions”,“description”:“Показы”,“type”:“integer”,“primary”:!1,“index”:!1,“nullable”:!1,“source”:“request”,“path”:“$.‘ga:impressions’”},{“name”:“clicks”,“description”:“Клики”,“type”:“integer”,“primary”:!1,“index”:!1,“nullable”:!1,“source”:“request”,“path”:“$.‘ga:adClicks’”},{“name”:“cost”,“description”:“Расходы”,“type”:“float”,“primary”:!1,“index”:!1,“nullable”:!1,“source”:“request”,“path”:“$.‘ga:adCost’”}]}]);second_json=JSON.stringify([{“ga:source”:“yandex”,“ga:medium”:“cpc”,“ga:campaign”:“First Campaign”,“ga:adContent”:“First Content”,“ga:keyword”:“First Keyword”,“ga:impressions”:14,“ga:adClicks”:3,“ga:adCost”:“4.27”},{“ga:source”:“yandex”,“ga:medium”:“cpc”,“ga:campaign”:“Second Campaign”,“ga:adContent”:“Second Content”,“ga:keyword”:“Second Keyword”,“ga:impressions”:5,“ga:adClicks”:0,“ga:adCost”:“0.0”}]);third_json=JSON.stringify({“table”:“general_traffic”,“description”:“Параметры трафика”,“type”:“dimension”,“shared”:!0,“order”:3,“fields”:[{“name”:“grouping”,“description”:“Название группы”,“type”:“string(128)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:channelGrouping’”},{“name”:“source”,“description”:“Источник”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:source’”},{“name”:“medium”,“description”:“Канал”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:medium’”},{“name”:“campaign”,“description”:“Кампания”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:campaign’”},{“name”:“content”,“description”:“Объявление”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:adContent’”},{“name”:“keyword”,“description”:“Ключевое слово”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:keyword’”},{“name”:“landing_page”,“description”:“Страница входа”,“type”:“string(256)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:landingPagePath’”}]});fourth_json=JSON.stringify({“name”:“grouping”,“description”:“Название группы”,“type”:“string(128)”,“primary”:!1,“index”:!1,“nullable”:!0,“source”:“request”,“path”:“$.‘ga:channelGrouping’”});try{firstViewer.showJSON(JSON.parse(first_json),null,1);secondViewer.showJSON(JSON.parse(second_json),null,1);thirdViewer.showJSON(JSON.parse(third_json),null,1);fourthViewer.showJSON(JSON.parse(fourth_json),null,1)} catch(err){alert(err)} //