MLP API

Протокол MLP API является универсальным протоколом доступа к данным Luxms BI при работе по модели MLP (Metric,Location,Period). MLP API используется клиентской частью Luxms BI.

Описание протокола в этой главе приводится на примере устаревших таблиц, которые не рекомендуются к использованию начиная с версии Luxms BI 9.

Термины и определения MLP

MLP VCP

Visual Control Point, см. ТВК

MLP ТВК

Точка Визуального Контроля. Координаты точки в многомерном пространстве измеряемых показателей вместе с её значением. Другими словами, это характеристики измеряемого значения показателя вместе с самим значением. Например, фраза “значение показателя средняя температура, измеренное 20 декабря 2015 года в Преображенской больнице и равное 36 градусам” описывает одну ТВК. Эта ТВК имеет одно значение, равное 36-и градусам, и три характеристики, как представлено в таблице:

Характеристика	Значение характеристики	Описание
Метрика	Средняя Температура	Метрики отвечают на вопрос `Что?`. Каждая метрика имеет единицу измерения (размерность). Например: км/ч, рубли, штуки и т.д.
Место взятия замера	Преображенская больница	Места (объекты контроля) отвечают на вопрос `Где?`. Объекты контроля могут иметь географические координаты: широту и долготу, а также границы.
Время взятия замера	20 декабря 2015 года	Временные метки (периоды) отвечают на вопрос `Когда?` Периоды задают временной интервал, в течение которого верно значение ТВК. Периоды имеют дату начала и стандартизованную длительность, например: день, неделя, месяц и т.д.

Введение

Протокол Luxms BI DB API разработан для поддержки четырёх типов операций с данными:

создание (Create)
получение (Retrieve)
изменение (Update)
удаление (Delete)

Этот набор операций получил название CRUD и поддерживается всеми хранилищами данных в том или ином виде.

Протокол Luxms BI DB API разработан с использованием элементов архитектурного стиля REST. Для обмена данными между клиентом и сервером используется формат JSON.

Для передачи данных используется кодировка UTF-8.

Перед тем как подавать запросы по протоколу Luxms BI DB API, необходимо пройти аутентификацию в системе.

Для загрузки ТВК в Luxms BI, нужно предварительно подготовить/узнать значения характеристик этих Точек Визуального Контроля.

Внимание! Для корректного копирования примеров из настоящего руководства в консоль, рекомендуется использовать Acrobat Reader. Другие программы для чтения PDF файлов не поддерживают формат PDF в полном объёме и работают некорректно при копировании текста.

Перед началом работы

Предполагается, что примеры будут запускаться в терминале UNIX-подобной системы. Для запуска примеров из этой главы необходимо настроить переменную окружения Shell luxmsbi_url.

Например:

export luxmsbi_url='https://luxmsbi.host'

Также, нужно получить у системного администратора логин и пароль для доступа к датасетам на сервере Luxms BI. Если требуется не только читать данные, но и изменять их, то необходимо, чтобы у пользователя был соответствующий уровень доступа к датасету.

Структуры данных Luxms BI в MLP

Luxms BI хранит ТВК (значения показателей) в виде 3-х мерного OLAP куба. Другими словами, каждое значение показателя характеризуется тремя ключами (идентификаторами). Ключи позволяют ответить на вопросы “Что?”, “Где?”, “Когда?” по отношению к значению показателя. Для хранения дополнительной информации о характеристиках “Что?-Где?-Когда?” используются таблицы-справочники.

Идентификатор	Вопрос	Таблица-справочник	Ключ в таблице значений
Идентификатор метрики	Что?	metrics	metric_id
Идентификатор локации	Где?	locations	loc_id
Идентификатор периода	Когда?	periods	period_id

Упрощённая схема данных представлена на рисунке:

MLP. Справочник метрик

Метрики отвечают на вопрос Что? по отношению к значению показателя. Другими словами, метрики характеризуют что именно измеряет то или иное значение. Подходящими названиями для метрик будут “Доходы”, “Средняя температура”, “Совокупная установленная мощность”.

Метрики в Luxms BI организованы в иерархию, при этом количество уровней вложенности технически не ограничено.

Значения родительской метрики чаще всего являются агрегатами значений своих дочерних метрик. Например, значение для родительской метрики “Доходы” может быть суммой значений метрик “Процентные доходы”, “Операционные доходы” и “Прочие доходы”.

Основные поля, характеризующие метрики указаны в таблице:

Имя поля	Значение	Тип поля	Пример JSON
id	Идентификатор метрики	Целое	`{"id": 11}`
title	Название метрики	Строка	`{"title": "Доходы"}`
tree_level	Уровень метрики в дереве. У корня дерева `tree_level`=`0`	Целое	`{"tree_level": 1}`
parent_id	Ключ родительской метрики. У корня `parent_id`=`null`	Строка	`{"parent_id": null}`
is_hidden	Признак скрытия метрики в UI	1 или 0	`{"is_hidden": 0}`
unit_id	Ключ единицы измерения из таблицы units	Целое	`{"unit_id": 2}`
srt	Порядковый номер для сортировки в UI	Целое	`{"srt": 10}`

Примечание: Перечень полей может отличаться от описанных в документации и зависит от установленной версии Luxms BI. Недокументированные поля следует игнорировать во всех запросах Luxms BI DB API. Изменение значений недокументированных полей может привести к неожиданным побочным эффектам.

MLP. Справочник единиц измерений

В описании метрик используется поле unit_id, которое задаёт единицу измерения для значений. Например, это может быть килограмм, рубль или км/ч. Используемые в датасете единицы измерения хранятся в таблице units.

Если поле unit_id у метрики установлено в null, то пользователь не сможет выбрать эту метрику в панели метрик, а значит, не сможет вывести эту метрику на график. Метрики с неустановленным полем unit_id могут быть использованы для логической группировки метрик в панели метрик.

Основные поля, характеризующие единицы измерения указаны в таблице:

Имя поля	Значение	Тип поля	Пример JSON
id	Идентификатор единицы измерения	Целое	`{"id": 1}`
title	Название единицы измерения для административного интерфейса	Строка	`{"title": "килограммы"}`
value_prefix	Префикс, отображаемый в UI перед значением	Строка	`{"value_prefix": "$"}`
value_suffix	Суффикс, отображаемый в UI после значения	Строка	`{"value_suffix": "%"}`
tiny_title	Название единицы измерения, используемое в легенде	Строка	`{"tiny_title": "шт."}`
axis_title	Название единицы измерения, используемое для подписи осей графиков	Строка	`{"axis_title": "килограммы"}`

MLP. Справочник локаций

Локации отвечают на вопрос Где? по отношению к значению показателя. Другими словами, локации характеризуют где именно получено то или иное значение. Подходящими названиями для локаций будут “Южный филиал”, “Невский район”, “г. Москва”.

Локации в Luxms BI организованы в иерархию, при этом количество уровней вложенности технически не ограничено.

Значения родительской локации чаще всего являются агрегатами значений своих дочерних локаций. Например, значение для родительской локации “г. Санкт-Петербург” может быть суммой значений локаций “Невский район”, “Центральный район” и “Кировский район”.

Основные поля, характеризующие локации указаны в таблице:

Имя поля	Значение	Тип поля	Пример JSON
id	Идентификатор локации	Целое	`{"id": 11}`
title	Название локации	Строка	`{"title": "офис"}`
tree_level	Уровень локации в дереве. У корня дерева `tree_level`=`0`	Целое	`{"tree_level": 1}`
parent_id	Ключ родительской локации. У корня `parent_id`=`null`	Строка	`{"parent_id": null}`
is_hidden	Признак скрытия локации в UI	1 или 0	`{"is_hidden": 0}`
latitude	Долгота в десятичных градусах	Рациональное	`{"latitude": 37.61556}`
longitude	Широта в десятичных градусах	Рациональное	`{"longitude": 55.75222}`
srt	Порядковый номер для сортировки в UI	Целое	`{"srt": 10}`

MLP. Справочник периодов

Периоды отвечают на вопрос Когда? по отношению к значению показателя. Другими словами, периоды характеризуют когда именно получено то или иное значение. Подходящими названиями для периодов будут “Первый квартал 2016 года”, “12 часов”, “март 2011г.”.

Основные поля, характеризующие периоды указаны в таблице:

Имя поля	Значение	Тип поля	Пример
id	Идентификатор периода	64 битное целое	`{"id": "2020010100000054"}`
title	Название периода	Строка	`{"title": "01.01.2020"}`
start_time	Дата начала периода	Строка/Дата SQL	`{"start_time" : "2020-01-01 00:00:00"}`
period_type	Тип периода, характеризующий длительность. Поддерживаются интервалы от секунды до года.	Целое	`{"period_type":4}`

Периоды характеризуются временем начала периода start_time и длительностью period_type. В Luxms BI можно использовать 8 стандартных типов периодов, от секунды до года, как описано в разделе Справочник типов периодов.

Внимание! Идентификатор периода представляет собой 64 битное целое число, в котором используется 53 бита. Такое целое число может быть корректно представлено средствами JavaScript без потери точности. По историческим причинам протокол Luxms BI DB API передаёт идентификаторы периодов в виде строки.

MLP. Справочник типов периодов

Идентификатор типа периода period_type используется для кодирования стандартной длительности периодов в Luxms BI.

Используются следующие типы периодов:

идентификатор типа периода	идентификатор гранулярности	длительность периода
1	81	Секунды
2	72	Минуты
3	63	Часы
4	54	Дни
5	45	Недели
6	36	Месяцы
7	27	Кварталы
8	18	Годы

Идентификатор гранулярности однозначно соответствует идентификатору типа периода и используется при кодировании идентификатора периода в виде 64-битного числа.

Структура URL

Точкой входа для запросов является URL путь /api/db/. Далее следует идентификатор датасета и имя таблицы, с которой будет работать запрос. Символ точки . используется в качестве разделителя между идентификатором датасета и именем таблицы.

В Luxms BI DB API используется два типа URL :

/api/db/${dataset}.${table}
/api/db/${dataset}.${table}/${object_id}

сегмент URL	Значения	Пример
`${dataset}`	GUID, имя схемы или id датасета	`4ebc64b0-39ea-4b62-a28d-722724daaa0a` или `ds_180` или `12`
`${table}`	имя таблицы	`locations` или `data`
`${object_id}`	идентификатор записи в таблице	`192` или `param1`

Тип операции задаётся методом HTTP запроса в соответствие с таблицей:

HTTP метод	Тип операции	Наличие HTTP Body в запросе	Тип URL
GET	Получение объектов	нет	`1` или `2`
POST	Создание объектов	да	`1`
PUT	Редактирование объектов	да	`2`
DELETE	Удаление объектов	нет	`2`

Кодировка данных

Luxms BI DB API использует формат JSON и кодировку UTF-8 в запросах и ответах.

Получение информации

Получение идентификаторов объектов из URL

Идентификатор набора данных

Набор данных в Luxms BI DB API идентифицируется тремя способами:

целочисленный id датасета, уникальный в рамках одного сервера Luxms BI.
текстовое имя схемы, уникальное в рамках одного сервера Luxms BI. В имени схемы используются только буквы латиницы, символ подчёркивания и цифры.
GUID, сохраняющийся при переносе датасета с одного сервера Luxms BI на другой.

Имя схемы датасета можно получить из URL при навигации в клиентской части Luxms BI. Например, из ссылки http://demo.luxmsbi.com/#/ds/ds_demo20/dashboards?locations=3&= можно получить имя схемы ds_demo20.

MLP. Идентификатор метрики

Это целочисленный идентификатор, который можно получить из ссылки. Например, из ссылки http://demo.luxmsbi.com/#/ds/ds_demo12/trends?metrics=162,150&locations=3&period.end=2013120100000036 можно получить идентификаторы метрик 162 и 150. Идентификаторы метрик кодируются с помощью параметра URL metrics.

MLP. Идентификатор локации

Это целочисленный идентификатор, который можно получить из ссылки. Например, из ссылки http://demo.luxmsbi.com/#/ds/ds_demo12/trends?metrics=162,150&locations=3&period.end=2013120100000036 можно получить идентификатор локации 3. Идентификаторы локаций кодируются с помощью параметра URL locations.

MLP. Идентификатор периода

Это целочисленный идентификатор, который можно получить из ссылки. Например, из ссылки http://demo.luxmsbi.com/#/ds/ds_demo12/trends?metrics=162,150&locations=3&period.end=2013120100000036 можно получить идентификатор периода 2013120100000036. Идентификаторы периодов кодируются с помощью параметра URL period.start для начального периода и period.end для конечного периода.

Получение информации с помощью запроса GET

Данные Luxms BI можно получить с помощью HTTP запроса GET. Для этого нужно указать датасет и имя таблицы, из которой требуется получить данные:

/api/db/${dataset}.${table}

Например, чтобы получить справочник единиц измерения в датасете с именем схемы ds_tests, нужно использовать URL:

/api/db/ds_tests.units

В качестве идентификатора датасета можно использовать любой идентификатор, например целочисленный:

/api/db/123.units

Также можно использовать и GUID датасета:

/api/db/5b3a1c32-5a91-4bdc-9036-cdb28768ccf4.units

Все эти способы указания датасета равнозначны и возвращают одинаковый результат.

Для авторизации запроса, необходимо указать идентификатор сессии, полученный на стадии аутентификации. Например, это можно сделать, отправив заголовок LuxmsBI-User-Session:

curl -k -v \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
-X GET "${luxmsbi_url}/api/db/ds_demo12.units"

Пример ответа:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
   {
      "id":2,
      "value_prefix":null,
      "value_suffix":"тыс.руб.",
      "title":"Тыс. рублей",
      "tiny_title":"тыс.руб.",
      "axis_title":"тыс.руб.",
      "updated":"2015-02-25T16:34:06.604562+03:00",
      "created":"2015-04-03T12:36:22.923085+03:00"
   },
   {
      "id":12,
      "value_prefix":null,
      "value_suffix":"тыс.мин.",
      "title":"Тыс. минут",
      "tiny_title":"тыс.мин.",
      "axis_title":"тыс.мин.",
      "updated":"2015-02-25T16:34:06.604562+03:00",
      "created":"2015-04-03T12:36:22.923085+03:00"
   }
]

В теле ответа можно увидеть список единиц измерения с указанием их идентификаторов.

Используя GET запросы можно узнать идентификаторы метрик, локаций и периодов, чтобы в дальнейшем использовать их для вставки значений в Luxms BI.

Вставка данных в Luxms BI

Для вставки данных в Luxms BI следует использовать HTTP запросы POST.

Вставка данных с помощью запроса POST

В URL запроса нужно указать датасет и имя таблицы, в которую будет происходить вставка данных:

/api/db/${dataset}.${table}

В теле одного HTTP запроса можно указать один и более объектов для добавления в датасет. Для ускорения процесса вставки данных рекомендуется в теле одного HTTP запросе передавать сразу несколько объектов. При этом либо все переданные в одном HTTP запросе объекты будут добавлены, либо ни один из них не будет добавлен из-за ошибки.

Для корректной обработки запроса на стороне сервера необходимо указывать тип и кодировку передаваемых данных:

Content-type: application/json; charset=utf-8

При вставке одного объекта в теле HTTP запроса необходимо использовать JSON нотацию объекта {}, при вставке нескольких объектов в теле HTTP запроса используется JSON нотация списка [].

При попытке вставить объект, который нарушает ограничение уникальности ключа (например: совпадение id), сервер вернёт HTTP статус 409 и в теле ответа вернёт запись, которая стала причиной конфликта. Такое поведение реализовано только для вставки одиночных объектов в нотации JSON объекта {}.

MLP. Добавление одной ТВК

URL: /api/db/${dataset}.data

В URL необходимо указать идентификатор датасета. В качестве идентификатора можно использовать GUID, имя схемы или id схемы.

Данные для вставки кодируются в формате JSON, как указано в таблице:

Имя поля	Значение	Тип поля	Пример
metric_id	Идентификатор метрики	строка	`{"metric_id" : 1}`
loc_id	Идентификатор локации	целое число	`{"loc_id":123 }`
period_id	Идентификатор периода	строка (64бит целое)	`{"period_id" : "2013120100000036"}`
val	Значение показателя	число с плавающей точкой	`{"value":123.23}`

Пример запроса:

curl -k -v \
--data '{"metric_id": 131, "loc_id":1, "period_id":2013120100000036, "val":123.23}' \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
--header 'Content-type: application/json; charset=utf-8' \
-X POST "${luxmsbi_url}/api/db/ds_tests.data/"

Пример тела ответа при успешной вставке:

{"loc_id":1, "period_id": 2013120100000036, "val":123.23, "metric_id":131}

Внимание! При добавлении ТВК не рекомендуется указывать id записей. Указание конкретных id может привести к ошибкам при последующей вставке других ТВК.

MLP. Добавление нескольких ТВК

Запрос аналогичен вставке одной ТВК, но в теле запроса передаётся массив (список) объектов для вставки.

Пример запроса:

curl -k -v \
--data '[
{"metric_id": 131,"loc_id":10, "period_id":"2013120100000036", "val":123.23},
{"metric_id": 131,"loc_id":11, "period_id":"2013120200000036", "val":0.87}
]' \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
--header 'Content-type: application/json; charset=utf-8' \
-X POST "${luxmsbi_url}/api/db/ds_tests.data"

Пример тела ответа при успешной вставке:

[
  {"loc_id":10, "period_id": 2013120100000036, "val":123.23, "metric_id":131},
  {"loc_id":11, "period_id": 2013120200000036, "val":0.87, "metric_id":131}
]

MLP. Добавление одной метрики с указанием id

URL: /api/db/${dataset}.metrics

Данные для вставки кодируются в формате JSON, как указано в таблице:

Имя поля	Значение	Тип поля	Пример JSON
id	Идентификатор метрики	Целое	`{"id": 11}`
title	Название метрики	Строка	`{"title": "Доходы"}`
tree_level	Уровень метрики в дереве. У корня дерева `tree_level`=`0`	Целое	`{"tree_level": 1}`
parent_id	Ключ родительской метрики. У корня `parent_id`=`null`	Строка	`{"parent_id": null}`
is_hidden	Признак скрытия метрики в UI	1 или 0	`{"is_hidden": 0}`
unit_id	Ключ единицы измерения из таблицы units	Целое	`{"unit_id": 2}`
srt	Порядковый номер для сортировки в UI	Целое	`{"srt": 10}`

Внимание! Система назначит идентификатор новой метрике автоматически, если в запросе не будет указано значение для ключа id.

Пример запроса:

curl -k -v \
--data '{"id": 98765, "title": "Средняя температура", "unit_id": 1}' \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
--header 'Content-type: application/json; charset=utf-8' \
-X POST "${luxmsbi_url}/api/db/ds_tests.metrics"

Пример ответа в случае ошибки:

HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8

{
  "id":98765,
  "parent_id":null,
  "alt_id":"98765",
  "title":"Минимальная температура",
  "tree_level":0,
  "unit_id":1,
  "srt":2147483647,
  "is_hidden":0
}

В данном случае ошибка произошла из-за конфликта уникальности ключа метрики. Метрика с id=98765 уже существует.

Пример ответа в случае ошибки:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{
  "title": "Ошибка SQL webapi.route",
  "message": "отношение \"ds_tests.metrics\" не существует (символ 13)"
}

Статус ответа 500 используется при любых внутренних ошибках сервера.

Пример тела ответа в случае успеха:

{
  "id":98765,
  "parent_id":null,
  "alt_id":"98765",
  "title":"Средняя температура",
  "tree_level":0,
  "unit_id":1,
  "srt":2147483647,
  "is_hidden":0
}

MLP. Добавление одной метрики без указания id

URL: /api/db/${dataset}.metrics

При вставке метрик без указания id, Luxms BI присвоит целочисленный id автоматически.

Если часть метрик добавляется с явным указанием id, а другая честь с использованием автоназначения, это может привести к проблеме неуникальных ключей в таблице metrics.

Пример запроса без указания id:

curl -k -v \
--data '{"title": "Средняя температура", "unit_id": 1}' \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
--header 'Content-type: application/json; charset=utf-8' \
-X POST "${luxmsbi_url}/api/db/ds_tests.metrics"

Пример тела ответа в случае успеха:

{
  "id":132,
  "parent_id":null,
  "alt_id":"132",
  "title":"Средняя температура",
  "tree_level":0,
  "unit_id":1,
  "srt":2147483647,
  "is_hidden":0
}

MLP. Добавление одной локации с указанием id

URL: /api/db/${dataset}.locations

Данные для вставки кодируются в формате JSON, как указано в таблице:

Имя поля	Значение	Тип поля	Пример JSON
id	Идентификатор локации	Целое	`{"id": 11}`
title	Название локации	Строка	`{"title": "офис"}`
tree_level	Уровень локации в дереве. У корня дерева `tree_level`=`0`	Целое	`{"tree_level": 1}`
parent_id	Ключ родительской локации. У корня `parent_id`=`null`	Строка	`{"parent_id": null}`
is_hidden	Признак скрытия локации в UI	1 или 0	`{"is_hidden": 0}`
latitude	Долгота в десятичных градусах	Рациональное	`{"latitude": 37.61556}`
longitude	Широта в десятичных градусах	Рациональное	`{"longitude": 55.75222}`
srt	Порядковый номер для сортировки в UI	Целое	`{"srt": 10}`

Внимание! Система назначит идентификатор новой локации автоматически, если в запросе не будет указано значение для ключа id.

Пример запроса:

curl -k -v \
--data '{"id": 987650, "title": "Головной офис", "latitude": 37.61556, "longitude": 55.75222}' \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
--header 'Content-type: application/json; charset=utf-8' \
-X POST "${luxmsbi_url}/api/db/ds_tests.locations"

Пример ответа в случае ошибки:

HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8

{
  "id":987650,
  "title":"Офис Тайга",
  "latitude":37.61556,
  "longitude":55.75222,
  "parent_id":null,
  "tree_level":0,
  "srt":2147483647,
  "is_hidden":0
}

В данном случае ошибка произошла из-за конфликта уникальности ключа локации. Локация с id=987650 уже существует.

Пример ответа в случае ошибки:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{
  "title": "Ошибка SQL webapi.route",
  "message": "отношение \"ds_tests.locations\" не существует (символ 13)"
}

Статус ответа 500 используется при любых внутренних ошибках сервера.

Пример тела ответа в случае успеха:

{
  "id":987650,
  "title":"Головной офис",
  "latitude":37.61556,
  "longitude":55.75222,
  "parent_id":null,
  "tree_level":0,
  "srt":2147483647,
  "is_hidden":0
}

MLP. Добавление одного периода

URL: /api/db/${dataset}.periods

Данные для вставки кодируются в формате JSON, как указано в таблице:

Имя поля	Значение	Тип поля	Пример
id	Идентификатор периода	64 битное целое	`{"id": 2013120200000036}`
title	Название периода	Строка	`{"title": "1кв. 2015"}`
start_time	Дата начала периода	Строка/Дата SQL	`{"start_time" : "2015-12-01"}`
period_type	Тип периода, характеризующий длительность. Поддерживаются интервалы от секунды до года.	Целое	`{"period_type":6}`

Внимание! Алгоритмы визуализации данных используют особые свойства id периодов. Для корректной и эффективной работы клиентской части рекомендуется всегда пользоваться автоматической генерацией id периодов и никогда не указывать их при вставке данных.

Внимание! В Luxms BI используются специальные id периодов, которые могут быть корректно представлены средствами Javascript в качестве целых чисел без потери точности.

Пример запроса:

curl -k -v \
--data '{"title":"12-2010", "start_time": "2010-12-01", "period_type":6}' \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
--header 'Content-type: application/json; charset=utf-8' \
-X POST "${luxmsbi_url}/api/db/ds_tests.periods"

Пример ответа в случае ошибки:

HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8

{
   "id": 2010120100000036,
   "period_type": 6,
   "start_time": "2010-12-01T00:00:00+03:00",
   "qty":1,
   "title": "12-2010",
   "updated": "2016-06-29T15:34:38.740998+03:00",
   "created": "2016-06-29T15:34:38.740998+03:00"
}

В данном случае ошибка произошла из-за конфликта уникальности периода. Период с указанной датой и типом уже существует и имеет id 2010120100000036.

Пример ответа в случае ошибки:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{
  "title": "Ошибка SQL webapi.route",
  "message": "отношение \"ds_tests.periods\" не существует (символ 13)"
}

Статус ответа 500 используется при любых внутренних ошибках сервера.

Пример тела ответа в случае успеха:

{
    "id":2010120100000036,
    "parent_id":null,
    "tree_level":0,
    "period_type":6,
    "qty":1,
    "start_time":"2010-12-01T00:00:00",
    "title":"12-2010",
    "updated":"2020-09-30T11:59:28.629989+00:00",
    "created":"2020-09-30T11:59:28.629989+00:00"
}

MLP. Изменение данных в Luxms BI

Для изменения данных в Luxms BI следует использовать HTTP запросы PUT.

Изменение данных с помощью запроса PUT

MLP. Изменение значения ТВК по условию

URL: /api/db/${dataset}.data/${LPE}

Выборку записей для обновления можно производить не только указывая id записи, но и с помощью выражений Lux Path Expressions, которые позволяют фильтровать записи по условию. Например, можно указать значения ключей Что?-Где?-Когда?, которые уникальным образом идентифицируют запись в таблице data, и тем самым, выбрать единственную запись для обновления.

Для фильтрации записей используется функция .filter. В качестве аргумента функции нужно указать выражение, накладывающее условия на поля записи.

Допускается использовать логические операции and, or, and.

Допускается использовать операции сравнения: >, <, != и т.д.

Двойной амперсанд && можно использовать вместо and ( логическое И).

Символы || можно использовать вместо or ( логическое ИЛИ).

В выражениях допускается использование пробелов для удобства чтения и скобок для создания сложных запросов.

Таким образом, условие SQL:

WHERE
    loc_id = 4 AND
    period_id = 2010120100000036 AND
    metric_id = 17

можно записать с помощью Lux Path Expression:

.filter(loc_id=4 && period_id= 2010120100000036 and metric_id=17)

Для выполнения запроса, это выражение LPE необходимо указать в сегменте URL на месте ${LPE}:

PUT /api/db/ds_tests.data/.filter(loc_id=4 && period_id= 2010120100000036 and metric_id=17)
Content-type: application/json; charset=utf-8

{"val":19.74}

Пример для выполнения в командной строке:

curl -k -v --globoff \
--data '{"val":20.02}' \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
--header 'Content-type: application/json; charset=utf-8' \
-X PUT "${luxmsbi_url}/api/db/ds_tests.data/.filter(loc_id=4 && period_id= 2010120100000036 and metric_id=17)"

В ответе всегда возвращается список записей в состоянии после внесения изменений. В данном случае возвращается список из одного элемента, так как в запросе был указан уникальный id записи.

Пример ответа:

[
  {
    "loc_id":4,
    "period_id": 2010120100000036,
    "updated":"2016-06-16T12:37:24.998473+03:00",
    "created":"2015-04-03T12:36:23.491845+03:00",
    "val":20.02,
    "metric_id":17
  }
]

MLP. Изменение метрики с указанием id

URL: /api/db/${dataset}.metrics/${id}

Для изменения одной определённой метрики нужно знать её id.

id метрики указывается в URL запроса в сегменте ${id}, а список изменяемых полей и их значений передаётся в теле запроса в формате JSON.

Например, чтобы изменить название метрики с id = 10 в датасете ds_tests на ЗАМЕТНОЕ название, нужно выполнить такой HTTP запрос:

PUT /api/db/ds_tests.metrics/10
Content-type: application/json; charset=utf-8

{"title": "ЗАМЕТНОЕ название"}

Пример для выполнения в командной строке:

curl -k -v \
--data '{"title": "ЗАМЕТНОЕ название"}' \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
--header 'Content-type: application/json; charset=utf-8' \
-X PUT "${luxmsbi_url}/api/db/ds_tests.metrics/10"

В ответе всегда возвращается список метрик в состоянии после внесения изменений. В данном случае возвращается список из одного элемента, так как в запросе был указан уникальный id метрики.

Пример ответа:

[
  {
      "id":10,
      "parent_id":25,
      "alt_id":"I11",
      "title":"ЗАМЕТНОЕ название",
      "tree_level":2,
      "unit_id":11,
      "srt":90,
      "is_hidden":0,
      "updated":"2016-08-09T19:55:53.239045+03:00",
      "created":"2015-04-03T12:36:23.346958+03:00"
  }
]

В одном запросе можно поменять сразу несколько полей метрики. Например, для изменения и названия, и порядка сортировки, нужно в теле сообщения передать такой JSON:

{"title": "ЗАМЕТНОЕ название", "srt": 1}

MLP. Изменение локации с указанием id

URL: /api/db/${dataset}.locations/${id}

Для изменения одной определённой локации нужно знать её id.

id локации указывается в URL запроса в сегменте ${id}, а список изменяемых полей и их значений передаётся в теле запроса в формате JSON.

Например, чтобы изменить название локации с id = 10 в датасете ds_tests на Головной офис, нужно выполнить такой HTTP запрос:

PUT /api/db/ds_tests.locations/10
Content-type: application/json; charset=utf-8

{"title": "Головной офис"}

Пример для выполнения в командной строке:

curl -k -v \
--data '{"title": "Головной офис"}' \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
--header 'Content-type: application/json; charset=utf-8' \
-X PUT "${luxmsbi_url}/api/db/ds_tests.locations/10"

В ответе всегда возвращается список локаций в состоянии после внесения изменений. В данном случае возвращается список из одного элемента, так как в запросе был указан уникальный id локации.

Пример ответа:

[
    {
        "id":10,
        "title":"Головной офис",
        "latitude":57.8136,
        "longitude":28.3496,
        "parent_id":1,
        "level":1,
        "srt":0,
        "is_hidden":0,
        "tree_level":1,
        "updated":"2016-06-16T12:37:24.998473+03:00",
        "created":"2015-04-03T12:36:23.22108+03:00"
  }
]

В одном запросе можно поменять сразу несколько полей локации. Например, для изменения названия, широты и долготы, нужно в теле сообщения передать такой JSON:

{
    "title": "Головной офис",
    "latitude": 57.8,
    "longitude": 28.3
}

MLP. Изменение периода с указанием id

URL: /api/db/${dataset}.periods/${id}

Для изменения одного определённого периода нужно знать его id.

id периода указывается в URL запроса в сегменте ${id}, а список изменяемых полей и их значений передаётся в теле запроса в формате JSON.

Например, чтобы изменить название периода с id = 2010120100000036 в датасете ds_tests на декабрь 2010, нужно выполнить такой HTTP запрос:

PUT /api/db/ds_tests.periods/2010120100000036
Content-type: application/json; charset=utf-8

{"title": "декабрь 2010"}

Пример для выполнения в командной строке:

curl -k -v \
--data '{"title": "2000 год"}' \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
--header 'Content-type: application/json; charset=utf-8' \
-X PUT "${luxmsbi_url}/api/db/ds_tests.periods/2010120100000036"

В ответе всегда возвращается список периодов в состоянии после внесения изменений. В данном случае возвращается список из одного элемента, так как в запросе был указан уникальный id периода.

Пример ответа:

[
    {
      "id": 2010120100000036,
      "title":"декабрь 2010",
      "period_type":6,
      "start_time":"2010-12-01T00:00:00+03:00",
      "qty":1,
      "updated":"2016-08-09T19:44:10.147325+03:00",
      "created":"2016-08-09T19:41:10.724793+03:00"
  }
]

В одном запросе можно поменять сразу несколько полей периода. Например, для изменения названия и времени начала периода, нужно в теле сообщения передать такой JSON:

{
    "title": "январь 2000",
    "start_time":"2000-01-01"
}

Удаление данных из Luxms BI

Для удаления данных из Luxms BI следует использовать HTTP запросы DELETE.

Удаление данных с помощью запроса DELETE

MLP. Удаление ТВК по условию

URL: /api/db/${dataset}.data/${LPE}

Удаление записей можно производить не только указывая id записи, но и с помощью выражений Lux Path Expressions, которые позволяют фильтровать записи по условию. Например, можно указать значения ключей Что?-Где?-Когда?, которые уникальным образом идентифицируют запись в таблице data, и тем самым, выбрать единственную запись для удаления.

Допускается использовать логические операции and, or, and.

Допускается использовать операции сравнения: >, <, != и т.д.

Двойной амперсанд && можно использовать вместо and ( логическое И).

Символы || можно использовать вместо or ( логическое ИЛИ).

Таким образом, условие SQL:

WHERE
    loc_id = 4 AND
    period_id = 2010120100000036 AND
    metric_id = 17

можно записать с помощью Lux Path Expression:

.filter(loc_id=4 && period_id=2010120100000036 and metric_id=17)

Для выполнения запроса, это выражение LPE необходимо указать в сегменте URL на месте ${LPE}:

DELETE /api/db/ds_tests.data/.filter(loc_id=4 && period_id=2010120100000036 and metric_id=17

Пример для выполнения в командной строке:

curl -k -v --globoff \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
-X DELETE "${luxmsbi_url}/api/db/ds_tests.data/.filter(loc_id=4 && period_id=2010120100000036 and metric_id=17)"

В случае удаления хотя бы одной записи, возвращается статус 200 и пустой список в качестве тела ответа.

Пример тела ответа в случае успешного удаления записи:

[]

Пример ответа, в случае, если по условию не найдено ни одной записи:

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"key":"OBJECT_NOT_FOUND", "type":"ERR", "message":"Невозможно найти указанный объект."}

MLP. Удаление метрики с указанием id

URL: /api/db/${dataset}.metrics/${id}

Внимание! При удалении метрики, автоматически удаляются все значения Точек Визуального Контроля, у которых метрика равна удаляемой метрике!

Для удаления одной определённой метрики нужно знать её id.

id метрики указывается в URL запроса в сегменте ${id}.

Например, чтобы удалить метрику с id = 10 в датасете ds_tests, нужно выполнить такой HTTP запрос:

DELETE /api/db/ds_tests.metrics/10

Пример для выполнения в командной строке:

curl -k -v \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
-X DELETE "${luxmsbi_url}/api/db/ds_tests.metrics/10"

В случае успешного удаления записи, возвращается статус 200 и пустой список в качестве тела ответа.

Пример тела ответа в случае успешного удаления метрики:

[]

Пример ответа, в случае ошибки:

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"key":"OBJECT_NOT_FOUND", "type":"ERR", "message":"Невозможно найти указанный объект."}

MLP. Удаление локации с уазанием id

URL: /api/db/${dataset}.locations/${id}

Внимание! При удалении локации, автоматически удаляются все значения Точек Визуального Контроля, у которых локация равна удаляемой локации!

Для удаления одной определённой локации нужно знать её id.

id локации указывается в URL запроса в сегменте ${id}.

Например, чтобы удалить локацию с id = 123 в датасете ds_tests, нужно выполнить такой HTTP запрос:

DELETE /api/db/ds_tests.locations/123

Пример для выполнения в командной строке:

curl -k -v \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
-X DELETE "${luxmsbi_url}/api/db/ds_tests.locations/123"

В случае удаления хотя бы одной записи, возвращается статус 200 и пустой список в качестве тела ответа.

Пример тела ответа в случае успешного удаления локации:

[]

Пример ответа, в случае ошибки:

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"key":"OBJECT_NOT_FOUND", "type":"ERR", "message":"Невозможно найти указанный объект."}

MLP. Удаление периода с уазанием id

URL: /api/db/${dataset}.periods/${id}

Внимание! При удалении периода, автоматически удаляются все значения Точек Визуального Контроля, у которых период равен удаляемому периоду!

Для удаления одного определённого периода нужно знать его id.

id периода указывается в URL запроса в сегменте ${id}.

Например, чтобы удалить период с id = 2013120100000036 в датасете ds_tests, нужно выполнить такой HTTP запрос:

DELETE /api/db/ds_tests.periods/2013120100000036

Пример для выполнения в командной строке:

curl -k -v \
--header "LuxmsBI-User-Session: ${luxmsbi_cookie}" \
-X DELETE "${luxmsbi_url}/api/db/ds_tests.periods/2013120100000036"

В случае удаления хотя бы одной записи, возвращается статус 200 и пустой список в качестве тела ответа.

Пример тела ответа в случае успешного удаления периода:

[]

Пример ответа, в случае ошибки:

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"key":"OBJECT_NOT_FOUND", "type":"ERR", "message":"Невозможно найти указанный объект."}

MLP API

Термины и определения MLP​

MLP VCP​

MLP ТВК​

Введение​

Перед началом работы​

Структуры данных Luxms BI в MLP​

MLP. Справочник метрик​

MLP. Справочник единиц измерений​

MLP. Справочник локаций​

MLP. Справочник периодов​

MLP. Справочник типов периодов​

Структура URL​

Кодировка данных​

Получение информации​

Получение идентификаторов объектов из URL​

Идентификатор набора данных​

MLP. Идентификатор метрики​

MLP. Идентификатор локации​

MLP. Идентификатор периода​

Получение информации с помощью запроса GET​

Вставка данных в Luxms BI​

Вставка данных с помощью запроса POST​

MLP. Добавление одной ТВК​

MLP. Добавление нескольких ТВК​

MLP. Добавление одной метрики с указанием id​

MLP. Добавление одной метрики без указания id​

MLP. Добавление одной локации с указанием id​

MLP. Добавление одного периода​

MLP. Изменение данных в Luxms BI​

Изменение данных с помощью запроса PUT​

MLP. Изменение значения ТВК по условию​

MLP. Изменение метрики с указанием id​

MLP. Изменение локации с указанием id​

MLP. Изменение периода с указанием id​

Удаление данных из Luxms BI​

Удаление данных с помощью запроса DELETE​

MLP. Удаление ТВК по условию​

MLP. Удаление метрики с указанием id​

MLP. Удаление локации с уазанием id​

MLP. Удаление периода с уазанием id​

Термины и определения MLP

MLP VCP

MLP ТВК

Введение

Перед началом работы

Структуры данных Luxms BI в MLP

MLP. Справочник метрик

MLP. Справочник единиц измерений

MLP. Справочник локаций

MLP. Справочник периодов

MLP. Справочник типов периодов

Структура URL

Кодировка данных

Получение информации

Получение идентификаторов объектов из URL

Идентификатор набора данных

MLP. Идентификатор метрики

MLP. Идентификатор локации

MLP. Идентификатор периода

Получение информации с помощью запроса GET

Вставка данных в Luxms BI

Вставка данных с помощью запроса POST

MLP. Добавление одной ТВК

MLP. Добавление нескольких ТВК

MLP. Добавление одной метрики с указанием id

MLP. Добавление одной метрики без указания id

MLP. Добавление одной локации с указанием id

MLP. Добавление одного периода

MLP. Изменение данных в Luxms BI

Изменение данных с помощью запроса PUT

MLP. Изменение значения ТВК по условию

MLP. Изменение метрики с указанием id

MLP. Изменение локации с указанием id

MLP. Изменение периода с указанием id

Удаление данных из Luxms BI

Удаление данных с помощью запроса DELETE

MLP. Удаление ТВК по условию

MLP. Удаление метрики с указанием id

MLP. Удаление локации с уазанием id

MLP. Удаление периода с уазанием id