Содержание
Описание протокола REST API
Общие настройки
Протокол предназначен для обмена данными с устройствами и сторонними системами сбора данных, подключаемых по шине REST API. Обмен данными осуществляется в формате JSON.
Подключение к серверу системы мониторинга по протоколу REST API
Для подключения к серверу системы мониторинга по протоколу REST API используется http-протокол соединения. В http-адресе нужно указать домен или IP-адрес сервера. Например:
http://[Домен или IP адрес]/api/[Параметр запроса]
На сервере поддерживается два типа запроса:
- GET-запрос для получения данных из системы мониторинга;
- POST-запрос для записи данных в систему мониторинга.
Регистрация устройств и сторонних систем сбора данных по протоколу REST API
Для авторизации необходимо указать API-токен. Токен указан в настройках Пользователя. Для того, чтобы токен работал, в настройках Пользователя должен быть включен чек-бокс «Доступ к API».
Для запроса данных необходимо использовать GET-запрос с параметром «Authorization» в заголовке запроса. В адресной строке в качестве GET-параметра указать API-токен. Например:
http://[SERVER]/api/[Параметр_запроса]?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn)
Для отправки данных на сервер создать POST-запрос одним из трех способов:
1. В адресной строке в качестве GET-параметра указать API-токен. Например:
http://[SERVER]/api/[Параметр_запроса]?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn)
2. В теле запроса указать параметр API-токен
3. В заголовке запроса («Bearer») указать параметр «Authorization», значение «Bearer» hBI4O8rClizALOPcrJ4DbljhHS8cVthn.
Синхронизация времени сервера и источника данных
Для синхронизации времени формируется запрос метки времени, который возвращает текущее время сервера в формате JSON. Параметр GET запроса – «timestamp». Время указано в формате GMT.
Пример запроса:
http://[SERVER]/api/timestamp?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn
Пример ответа:
{
"code":200,
"status":"success",
"data":{
"timestamp":1660039669
}
}
Запросы
Запрос списка шин
Запрос списка шин формируется для отображения параметров активных шин в системе. Параметр GET запроса – «/buses».
Таблица 1.
| Параметр в JSON | Поле в системе мониторинга |
|---|---|
| id | Уникальный номер шины в системе мониторинга |
| code | Код шины |
| comment | Комментарий |
| tcp_remote_address | IP-адрес (Конвертор, OPC Gateway Service, XNB mqtt URL) |
| tcp_port | Порт сервера |
| bus_type | Тип шины |
| enabled/disabled | Шина включена/выключена |
Пример запроса:
http://[SERVER]/api/buses?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn
Пример ответа:
{
"code": 200,
"status": "success",
"data": [{
"id": 1,
"code": "rest1",
"comment": null,
"tcp_remote_address": null,
"tcp_port": null,
"bus_type": "restapijson",
"enabled": true
}]
}
Запрос информации по выбранной шине
Для получения параметров шины и списка устройств необходимо сформировать GET-запрос «/buses/{buse_code}».
Для выбора шины необходимо указать «code» (код шины) вместо переменной «{buse_code}». Входные данные на запрос содержат информацию по запрошенной шине (см. Таблица 1) и информацию по всем устройствам, подключенным к шине (см. Таблица 2).
Таблица 2.
| Параметр в JSON (массив значений: device) | Поле в системе мониторинга |
|---|---|
| id | Уникальный номер устройства в системе мониторинга |
| code | Код устройства |
| device_type | Тип устройства |
| comment | Комментарий |
| active_metering_period | Периодичность опроса устройства, секунд |
| auto_metering_period | Периодичность сеансов измерений, секунд |
| correction_angle | Коррекция азимута, градус |
| correction_reverse | Система координат |
Пример запроса:
http://[SERVER]/api/buses/rest1?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn
Пример ответа:
{
"code": 200,
"status": "success",
"message": "Information on devices and buses"
"data": {
"id": 1,
"code": "rest1",
"comment”: "",
"tcp_remote_address": "192.168.0.1",
"tcp_port": 0,
"bus_type": "restapijson",
"device1": {
"id": 1,
"code": "test1"
"device_type": "Спектроанализатор",
"comment": "",
"active_metering_period": 600,
"auto_metering_period": 60,
"correction_angle": 0,
"correction_reverse": 0
}
}
}
Запрос информации по выбранному устройству
Для получения параметров устройства и списка каналов необходимо сформировать GET-запрос «/sensors/{device_code}».
Для выбора устройства необходимо указать «code» (код устройства) вместо переменной «{device_code}». Входные данные на запрос содержат информацию по шине (см. Таблица 1), запрошенному устройству (см. Таблица 2) и информацию по всем каналам выбранного устройства (см. Таблица 3).
Таблица 3.
| Параметр в JSON (массив значений: channels) | Поле в системе мониторинга |
|---|---|
| id | Уникальный номер канала в системе мониторинга |
| sensor_id | Уникальный номер устройства в системе мониторинга |
| addr | Адрес |
| code | Код канала |
| height | Высотная отметка, м |
| correction_ratio | Коэффициент преобразования |
| correction | Смещение 0 |
Пример запроса (запрос возвращает данные за последние 24 часа):
http://[SERVER]/api/sensors/test1?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn
Пример ответа:
{
"code": 200,
"status": "success",
"data": {
"id": 1,
"bus_id": 1,
"code": "test1",
"device_type": "spectroanalyzer",
"comment": null,
"active_metering_period": "600.00",
"auto_metering_period": "0.0000",
"correction_angle": "0",
"correction_reverse": false,
"enabled": true,
"channels": [{
"id": 1,
"sensor_id": 1,
"addr": "t1",
"code": "t1",
"height": "0",
"correction_ratio": null,
"correction": "0"
}, {
"id": 2,
"sensor_id": 1,
"addr": "t2a",
"code": "t2c",
"height": "0",
"correction_ratio": null,
"correction": "0"
}],
"bus": {
"id": 1,
"code": "rest1",
"tcp_remote_address": "62.213.109.66",
"tcp_port": 0,
"bus_type": "restapijson",
"enabled": true,
"comment": null
}
}
}
Запрос данных измерения по выбранному Каналу
Для получения информации об измерениях за выбранный период времени необходимо сформировать GET-запрос «/channels_data/{channel_id}».
Для выбора канала необходимо указать «id» (уникальный номер канала в Системе Мониторинга) вместо переменной «{channel_id}». Входные данные на запрос содержат информацию данных в выбранном канале (см. Таблица 4).
Таблица 4.
| Параметр в JSON | Поле в системе мониторинга |
|---|---|
| dateFrom | Дата начала запрошенного периода |
| dateTo | Дата окончания запрошенного периода |
| values→time | Время измерения |
| values→val | Значения измерения |
Пример запроса:
http://[SERVER]/api/channels_data/2?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn
Пример ответа:
{
"code": 200,
"status": "success",
"data": {
"dateFrom": "2022-08-09 20:14:35",
"dateTo": "2022-08-10 20:14:35",
"values": [{
"time": 1660058075,
"val": null
, {
"time": 1660058675,
"val": null
}, {
"time": 1660115343,
"val": null
"time": 1660116283,
"val": 160
}, {
"time": 1660144475,
"val": null
}]
}
}
Запрос статусов по объекту мониторинга
Для получения статусов по каналам (сигнализации) на объекте мониторинга необходимо сформировать GET-запрос «/objects_status/{object_id}».
Для выбора объекта мониторинга укажите «id» (уникальный номер объекта мониторинга в Системе) вместо переменной «{object_id}». Входные данные на запрос содержат информацию по объекту мониторинга (см. Таблица 5).
Таблица 5.
| Параметр в JSON | Поле в системе мониторинга |
|---|---|
| id | Уникальный номер объекта мониторинга |
| title | Название объекта |
| interval | Интервал, секунды (для внешних систем) |
| date | Дата и время запроса данных |
| enabled_buses→bus_id | Уникальный номер шины |
| enabled_buses→name | Название шины |
| enabled_buses→code | Код шины |
| enabled_sensors→sensor_id | Уникальный номер устройства |
| enabled_sensors→name | Название устройства |
| enabled_sensors→code | Код устройства |
| channels→channel_id | Уникальный номер канала |
| channels→name | Название канала |
| channels→code | Код канала |
| channels→state | Статус |
Пример запроса:
http://[SERVER]/api/objects_status/{object_id}?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn
Пример ответа:
{
"code": 200,
"status": "success",
"data": {
"id": 1,
"title": "Название объекта",
"interval": 15,
"date": "2022-10-03 22:24:34",
"enabled_buses": [{
"bus_id": 1,
"name": "REST API (JSON)",
"code": "rest1",
"enabled_sensors": [{
"sensor_id": 1,
"name": "Название устройства",
"code": "Код устройства",
"channels": [{
"channel_id": 1,
"name": "Название канала",
"code": "Код канала",
"state": "gray"
}, {
"channel_id": 2,
"name": "Название канала",
"code": "Код канала",
"state": "gray"
}]
},{
"sensor_id": 2,
"name": "RestAPI 2",
"code": "test2",
"channels": [{
"channel_id": 3,
"name": "T1",
"code": "t1",
"state": "red"
}, {
"channel_id": 4,
"name": "T2",
"code": "t2c",
"state": "green"
}]
}, ....
Запрос элементов конструкции по объекту мониторинга
Для получения информации о параметрах конструктивных элементов и сигнализации по каналам на объекте мониторинга необходимо сформировать GET-запрос «object_elements/{object_id}». Для выбора объекта мониторинга укажите «id» (уникальный номер объекта мониторинга в Системе) вместо «{object_id}». Назначение параметров в JSON-формате – см. Таблица 6.
Таблица 6.
| Параметр в JSON | Поле в системе мониторинга |
|---|---|
| location_id | Уникальный номер ОМ |
| location_title | Название объекта мониторинга |
| location_code | Код объекта мониторинга |
| elements→id | ID элемента |
| elements→bus_id | Уникальный номер шины |
| elements→_lft | Параметр для построения дерева элемента конструкции |
| elements→_rgt | Параметр для построения дерева элемента конструкции |
| elements→parent_id | Параметр для построения дерева элемента конструкции |
| elements→title | Название элемента |
| elements→type | Тип элемента |
| elements→code | Код элемента |
| elements→description | Описание элемента |
| elements→state | Категория технического состояния |
| elements→sensors | Параметры устройства, привязанного к элементу |
| elements→sensor_channels | Параметры Канала, привязанного к элементу |
Пример запроса:
http://[HOSTNAME]/api/object_elements/{object_id}?api_token=1I18lUJW0lIiBjE0zvSeum3TSs06vcKi
Пример ответа:
{
"code": 200,
"status": "success",
"data": {
"location_id": 1,
"location_title": "1",
"location_code": null,
"elements": [{
"id": 9,
"_lft": 2,
"_rgt": 5,
"parent_id": 1,
"title": "L1E1",
"type": "",
"code": "l1e1",
"description": null,
"state": "",
"sensors": [{
"id": 8,
"name": "A1.1 X",
"code": "8",
"enabled": true,
"channels": [{
"channel_id": 26,
"name": "1 d1",
"code": "d1",
"state": "gray"
}, {
"channel_id": 34,
"name": "5 f5-2",
"code": "f5-2",
"state": "gray"
}]
}],
"sensor_channels": [{
"channel_id": 26,
"sensor_id": 8,
"name": "1 d1",
"code": "d1",
"enabled": true,
"state": "gray"
}]
}, {
"id": 15,
"_lft": 9,
"_rgt": 10,
"parent_id": 14,
"title": "L1E2222",
"type": “",
"code": "l1e2222",
"description": null,
"state": "",
"sensors": [{
"id": 9,
"name": "A1.1 Z",
"code": "9",
"enabled": true,
"channels": [{
"channel_id": 41,
"name": "1 d1",
"code": "d1",
"state": "gray"
}, {
"channel_id": 42,
"name": "1 f1",
"code": "f1",
"state": "gray"
}, {
"channel_id": 48,
"name": "5 f5",
"code": "f5",
"state": "gray"
}, {
"channel_id": 49,
"name": "5 f5-2",
"code": "f5-2",
"state": "gray"
}]
}],
"sensor_channels": []
}]
}
}
Запись данных по протоколу
Запись данных в базу данных Систему Мониторинга осуществляется при условии, что для устройства выбран тип шины «REST API (JSON)».
Для записи данных необходимо сформировать POST-запрос «/sensors_data/ {device_code}».
Для выбора устройства укажите «code» (код устройства) вместо переменной «{device_code}». Данные запроса для записи в базу данных содержат информацию по каналу выбранного устройства (см. Таблица 7).
Таблица 7.
| Параметр в JSON | Поле в системе мониторинга |
|---|---|
| api_token | Токен для доступа к API |
| timestamp | Время измерения |
| data→addr | Адрес канала |
| data→value | Значения измерения |
Пример адреса для POST запроса:
http://[SERVER]/api/sensors_data/test1
Пример JSON-формата, где параметр data – строковое значение:
{
"api_token": "hBI4O8rClizALOPcrJ4DbljhHS8cVth",
"timestamp": 1659696538,
"data": “[{\"addr\": \"t1\", \"value\": 12}, {\"addr\": \"t2a\",\"value\": 22}]”
Сообщения об ошибках в протоколе
А. Ответ при отсутствии ID объекта мониторинга при запросе списка элементов:
{
"code": 404,
"status": "error",
"message": "Object with this id was not found.",
"data": {
"object_id": 15
}
}
Б. Ответ при отключении пользователя (чек-бокс «Доступ к API» выключен у Пользователя):
{
"code": 404,
"status": "error",
"message": "Device with this code was not found.",
"data": {
"device_code": "test3"
}
}
В. Ответ при неверном API-Токене:
{
"code": 401,
"status": "error",
"message": "Unauthenticated."
}
Г. Не найдена шина в системе мониторинга:
{
"code": 404,
"status": "error",
"message": "Bus with this code was not found.",
"data": {
"bus_code": "rest2"
}
}
Д. При записи данных протокол обмена указан неверно (не «REST API (JSON)»):
{
"code": 403,
"status": "error",
"message": "Bus type must be REST API (JSON).",
"data": {
"bus_code": "rest1"
}
}
Е. Шина выключена или не создана:
{
"code": 403,
"status": "error",
"message": "The bus is off.",
"data": {
"bus_code": "rest1"
}
}
Ж. Код устройства не найден:
{
"code": 404,
"status": "error",
"message": "Device with this code was not found.",
"data": {
"device_code": "test3"
}
}
З. Устройство выключено или отсутствует в системе мониторинга:
{
"code": 403,
"status": "error",
"message": "The device is off.",
"data": {
"bus_code": "rest1",
"sensor_code": "test1"
}
}
И. Ответ при отсутствии записи отдельных каналов в базе данных (при этом запись в базе данных других каналов не останавливается):
{
"code": 201,
"status": "success",
"data": {
"sensor_code": "test2",
"answer": "Skipped addresses: ['t1v']"
}
}