01 DB API

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

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

Введение

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

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

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

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

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

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

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

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

Например:

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

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

Аутентификация

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

URL: /api/auth/login

Параметры запроса:

Имя параметра	Тип параметра	Пример
username	строка	username=developer
password	строка	password=devpass

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

curl -k -v \
--header 'Content-type: application/x-www-form-urlencoded' \
--data 'username=admin&password=abcd' \
-X POST "${luxmsbi_url}/api/auth/login"

Внимание! При запуске примеров, скопированных из этого документа, убедитесь, что Вы выполнили шаги, описанные в разделе Перед началом работы.

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Set-Cookie: LuxmsBI-User-Session=97f948ed-58ae-414c-b6fe-58e8105a29f4; expires=Thu, 03 Nov 2016 09:55:25 GMT; path=/;

{
    "id" : "1", 
    "username" : "admin", 
    "email" : "blackhole@localhost.localdomain", 
    "access_level" : "admin", 
    "name" : "Default Admin", 
    "config" : {}, 
    "sys_config" : {}
}

Для корректной пары логин/пароль возвращается HTTP статус 200 и в заголовке Set-Cookie возвращается идентификатор сессии (cookie). Предоставленный идентификатор сессии необходимо использовать в последующих запросах к сервису Luxms BI DB API.

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

В теле HTTP ответа передаётся информация о пользователе, который прошёл аутентификацию.

При ошибке аутентификации (логин и/или пароль неверны, доступ пользователю запрещен) возвращается HTTP статус 403 Forbidden.

Пример ответа при ошибке аутентификации:

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

{"key":"WRONG_PASSWORD_OR_USER_NAME", "type":"ERR", "message":"Неверный логин и/или пароль."}

В теле HTTP ответа передаётся сообщение об ошибке аутентификации в формате JSON.

Авторизация

Для авторизации запроса необходимо передать на сервер полученный на стадии аутентификации идентификатор сессии. Это можно сделать с помощью HTTP заголовков Cookie или LuxmsBI-User-Session. Если в запросе указаны оба заголовка, то проверяется только заголовок Cookie, а заголовок LuxmsBI-User-Session игнорируется.

Для запуска примеров из этой главы необходимо присвоить переменной окружения Shell luxmsbi_cookie значение cookie, полученное в процессе аутентификации.

Например:

export luxmsbi_cookie='4350779b-5a72-4523-a87a-61b59295b18d'

Для авторизации необходимо передать на сервер стандартный заголовок Cookie, как описано в rfc6265.

Пример заголовка:

Cookie: LuxmsBI-User-Session=4350779b-5a72-4523-a87a-61b59295b18d

Авторизация с помощью заголовка LuxmsBI-User-Session:

Для авторизации необходимо передать на сервер заголовок LuxmsBI-User-Session

Пример заголовка:

LuxmsBI-User-Session: 4350779b-5a72-4523-a87a-61b59295b18d

Авторизация с помощью Token

Альтернативный способ авторизации - использование Token, который можно получить в разделе API токены - API токены. Раздел “API токены” доступен через WEB интерфейс пользователю с ролью Super или Admin.

curl --location --request GET '${luxmsbi_url}/api/db/koob.cubes/.filter(source_ident = '\''luxmsbi'\'')' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9XXX'

Доступ к таблицам DB API

Доступ к тем или иным таблицам БД метаданных Luxms BI регулируется Лицензионной и Сайтовой Ролями пользователя, который выполняет запросы к DB API. Доступ к таблицам/обектам описан в разеде Система прав доступа Luxms BI

Структура 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 можно получить имя схемы ds_demo20.

Получение информации с помощью запроса 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"
   }
]

Вставка данных в 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 объекта {}.

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

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

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

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

Выборку записей для обновления можно производить не только указывая id записи, но и с помощью выражений Lux Path Expressions, которые позволяют фильтровать записи по условию.

Для фильтрации записей используется функция .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
  }
]

Изменение метрики с указанием 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}

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

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

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

Удаление по условию

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

Удаление записей можно производить не только указывая id записи, но и с помощью выражений Lux Path Expressions, которые позволяют фильтровать записи по условию.

Допускается использовать логические операции 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":"Невозможно найти указанный объект."}

01 DB API

Введение​

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

Аутентификация​

Авторизация​

Авторизация с помощью заголовка Cookie:​

Авторизация с помощью заголовка LuxmsBI-User-Session:​

Авторизация с помощью Token​

Доступ к таблицам DB API​

Структура URL​

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

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

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

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

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

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

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

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

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

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

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

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

Удаление по условию​

Введение

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

Аутентификация

Авторизация

Авторизация с помощью заголовка Cookie:

Авторизация с помощью заголовка LuxmsBI-User-Session:

Авторизация с помощью Token

Доступ к таблицам DB API

Структура URL

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

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

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

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

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

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

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

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

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

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

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

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

Удаление по условию