Различия

Показаны различия между двумя версиями страницы.

--- документация:описание_протокола_rest_api [2024/01/20 04:34] – удалено - внешнее изменение (Дата неизвестна) 127.0.0.1
+++ документация:описание_протокола_rest_api [2024/01/29 06:57] (текущий) – adm0001
@@ Строка 1: / Строка 1: @@
+===== Описание протокола REST API =====
+==== Общие настройки ====
+Протокол предназначен для обмена данными с устройствами и сторонними системами сбора данных, подключаемых по шине REST API. Обмен данными осуществляется в формате JSON.
+**Подключение к серверу системы мониторинга по протоколу REST API**
+Для подключения к серверу системы мониторинга по протоколу REST API используется //http//-протокол соединения. В //http//-адресе нужно указать домен или IP-адрес сервера. Например:
+<code>
+http://[Домен или IP адрес]/api/[Параметр запроса]
+</code>
+На сервере поддерживается два типа запроса:
+  * GET-запрос для получения данных из системы мониторинга;
+  * POST-запрос для записи данных в систему мониторинга.
+**Регистрация устройств и сторонних систем сбора данных по протоколу REST API**
+Для авторизации необходимо указать API-токен. Токен указан в настройках Пользователя. Для того, чтобы токен работал, в настройках Пользователя должен быть включен чек-бокс «Доступ к API».
+{{:документация:описание_протокола_rest_api:rest_api_токен_.jpg?200|}}
+Для запроса данных необходимо использовать GET-запрос с параметром «Authorization» в заголовке запроса. В адресной строке в качестве GET-параметра указать API-токен. Например:
+<code>
+http://[SERVER]/api/[Параметр_запроса]?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn)
+</code>
+Для отправки данных на сервер создать POST-запрос одним из трех способов:
+. В адресной строке в качестве GET-параметра указать API-токен. Например:
+<code>
+http://[SERVER]/api/[Параметр_запроса]?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn)
+</code>
+. В теле запроса указать параметр API-токен
+. В заголовке запроса («Bearer») указать параметр «Authorization», значение «Bearer» ''hBI4O8rClizALOPcrJ4DbljhHS8cVthn''.
+**Синхронизация времени сервера и источника данных**
+Для синхронизации времени формируется запрос метки времени, который возвращает текущее время сервера в формате JSON. Параметр GET запроса – «''timestamp''». Время указано в формате GMT.
+Пример запроса:
+<code>
+http://[SERVER]/api/timestamp?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn
+</code>
+Пример ответа:
+<code>
+{
+"code":200,
+"status":"success",
+"data":{
+  "timestamp":1660039669
+       }
+}
+</code>
+==== Запросы ====
+**Запрос списка шин**
+Запрос списка шин формируется для отображения параметров активных шин в системе. Параметр GET запроса – «''/buses''».
+Таблица 1.
+^  Параметр в JSON^Поле в системе мониторинга|
+|//id// |Уникальный номер шины в системе мониторинга|
+|//code// |Код шины|
+|//comment// |Комментарий|
+|//tcp_remote_address// |IP-адрес (Конвертор, OPC Gateway Service, XNB mqtt URL)|
+|//tcp_port// |Порт сервера|
+|//bus_type// |Тип шины|
+|//enabled/disabled// |Шина включена/выключена|
+Пример запроса:
+<code>
+http://[SERVER]/api/buses?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn
+</code>
+Пример ответа:
+<code>
+{
+"code": 200,
+"status": "success",
+"data": [{
+    "id": 1,
+    "code": "rest1",
+    "comment": null,
+    "tcp_remote_address": null,
+    "tcp_port": null,
+    "bus_type": "restapijson",
+    "enabled": true
+    }]
+}
+</code>
+**Запрос информации по выбранной шине**
+Для получения параметров шины и списка устройств необходимо сформировать 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// |Система координат|
+Пример запроса:
+<code>
+http://[SERVER]/api/buses/rest1?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn
+</code>
+Пример ответа:
+<code>
+{
+"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
+          }
+    }
+}
+</code>
+**Запрос информации по выбранному устройству**
+Для получения параметров устройства и списка каналов необходимо сформировать GET-запрос «''/sensors/{device_code}''».
+Для выбора устройства необходимо указать «''code''» (код устройства) вместо переменной «''{device_code}''». Входные данные на запрос содержат информацию по шине (см. Таблица 1), запрошенному устройству (см. Таблица 2) и информацию по всем каналам выбранного устройства (см. Таблица 3).
+Таблица 3.
+^Параметр в JSON (массив значений: //channels//)^Поле в системе мониторинга|
+|//id// |Уникальный номер канала в системе мониторинга|
+|//sensor_id// |Уникальный номер устройства в системе мониторинга|
+|//addr// |Адрес|
+|//code// |Код канала|
+|//height// |Высотная отметка, м|
+|//correction_ratio// |Коэффициент преобразования|
+|//correction// |Смещение 0|
+Пример запроса (запрос возвращает данные за последние 24 часа):
+<code>
+http://[SERVER]/api/sensors/test1?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn
+</code>
+Пример ответа:
+<code>
+{
+"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
+      }
+    }
+ }
+</code>
+**Запрос данных измерения по выбранному Каналу**
+Для получения информации об измерениях за выбранный период времени необходимо сформировать GET-запрос «''/channels_data/{channel_id}''».
+Для выбора канала необходимо указать «''id''» (уникальный номер канала в Системе Мониторинга) вместо переменной «''{channel_id}''». Входные данные на запрос содержат информацию данных в выбранном канале (см. Таблица 4).
+Таблица 4.
+^Параметр в JSON^Поле в системе мониторинга|
+|//dateFrom// |Дата начала запрошенного периода|
+|//dateTo// |Дата окончания запрошенного периода|
+|//values→time// |Время измерения|
+|//values→val// |Значения измерения|
+Пример запроса:
+<code>
+http://[SERVER]/api/channels_data/2?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn
+</code>
+Пример ответа:
+<code>
+{
+"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
+      }]
+    }
+}
+</code>
+**Запрос статусов по объекту мониторинга**
+Для получения статусов по каналам (сигнализации) на объекте мониторинга необходимо сформировать 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// |Статус|
+Пример запроса:
+<code>
+http://[SERVER]/api/objects_status/{object_id}?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn
+</code>
+Пример ответа:
+<code>
+{
+"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"
+         }]
+     }, ....
+</code>
+**Запрос элементов конструкции по объекту мониторинга**
+Для получения информации о параметрах конструктивных элементов и сигнализации по каналам на объекте мониторинга необходимо сформировать 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// |Параметры Канала, привязанного к элементу|
+Пример запроса:
+<code>
+http://[HOSTNAME]/api/object_elements/{object_id}?api_token=1I18lUJW0lIiBjE0zvSeum3TSs06vcKi
+</code>
+Пример ответа:
+<code>
+{
+"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": []
+      }]
+  }
+}
+</code>
+==== Запись данных по протоколу ====
+Запись данных в базу данных Систему Мониторинга осуществляется при условии, что для устройства выбран тип шины «REST API (JSON)».
+Для записи данных необходимо сформировать POST-запрос «''/sensors_data/ {device_code}''».
+Для выбора устройства укажите «''code''» (код устройства) вместо переменной «''{device_code}''». Данные запроса для записи в базу данных содержат информацию по каналу выбранного устройства (см. Таблица 7).
+Таблица 7.
+^Параметр в JSON^Поле в системе мониторинга|
+|//api_token// |Токен для доступа к API|
+|//timestamp// |Время измерения|
+|//data→addr// |Адрес канала|
+|//data→value// |Значения измерения|
+Пример адреса для POST запроса:
+<code>
+http://[SERVER]/api/sensors_data/test1
+</code>
+Пример JSON-формата, где параметр ''data''  – строковое значение:
+<code>
+{
+"api_token": "hBI4O8rClizALOPcrJ4DbljhHS8cVth",
+"timestamp": 1659696538,
+"data": “[{\"addr\": \"t1\", \"value\": 12}, {\"addr\": \"t2a\",\"value\": 22}]”
+</code>
+==== Сообщения об ошибках в протоколе ====
+А. Ответ при отсутствии ID объекта мониторинга при запросе списка элементов:
+<code>
+{
+"code": 404,
+"status": "error",
+"message": "Object with this id was not found.",
+"data": {
+    "object_id": 15
+        }
+}
+</code>
+Б. Ответ при отключении пользователя (чек-бокс «Доступ к API» выключен у Пользователя):
+<code>
+{
+"code": 404,
+"status": "error",
+"message": "Device with this code was not found.",
+"data": {
+     "device_code": "test3"
+        }
+}
+</code>
+В. Ответ при неверном API-Токене:
+<code>
+{
+"code": 401,
+"status": "error",
+"message": "Unauthenticated."
+}
+</code>
+Г. Не найдена шина в системе мониторинга:
+<code>
+{
+"code": 404,
+"status": "error",
+"message": "Bus with this code was not found.",
+"data": {
+      "bus_code": "rest2"
+        }
+}
+</code>
+Д. При записи данных протокол обмена указан неверно (не «REST API (JSON)»):
+<code>
+{
+"code": 403,
+"status": "error",
+"message": "Bus type must be REST API (JSON).",
+"data": {
+      "bus_code": "rest1"
+        }
+}
+</code>
+Е. Шина выключена или не создана:
+<code>
+{
+"code": 403,
+"status": "error",
+"message": "The bus is off.",
+"data": {
+      "bus_code": "rest1"
+        }
+}
+</code>
+Ж. Код устройства не найден:
+<code>
+{
+"code": 404,
+"status": "error",
+"message": "Device with this code was not found.",
+"data": {
+      "device_code": "test3"
+        }
+}
+</code>
+З. Устройство выключено или отсутствует в системе мониторинга:
+<code>
+{
+"code": 403,
+"status": "error",
+"message": "The device is off.",
+"data": {
+      "bus_code": "rest1",
+      "sensor_code": "test1"
+        }
+}
+</code>
+И. Ответ при отсутствии записи отдельных каналов в базе данных (при этом запись в базе данных других каналов не останавливается):
+<code>
+{
+"code": 201,
+"status": "success",
+"data": {
+      "sensor_code": "test2",
+      "answer": "Skipped addresses: ['t1v']"
+        }
+}
+</code>