REST API

12 июня 2024 г.Около 5 минrestapi

Все сервисы используют базовый url /sem-restservices. Указанные в примерах адреса используются только для иллюстрации и пояснения запросов.

Авторизация пользователя

Для работы с платформой необходимо авторизоваться. Платформа не предоставляет данных не авторизованным пользователям.
Пример авторизации:

Curl

curl -X POST "http://10.0.0.1/sem-restservices/auth/login?username=demo&password=DemoPassword" -H "accept: application/json" -H "Content-Type: application/json"

Request URL

http://10.0.0.1/sem-restservices/auth/login?username=demo&password=DemoPassword

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

HTTP/1.1 200 OK
Set-Cookie: SEMSESSIONID=e7ef1f62-a6d1-0000-0000-000000000000; Path=/; HttpOnly; SameSite=lax
Set-Cookie: rememberMe=deleteMe; Path=/sem-restservices; Max-Age=0; Expires=Wed, 29-Sep-2021 10:43:42 GMT; SameSite=lax
Set-Cookie: language=ru-RU;Version=1;Path=/sem-restservices
Set-Cookie: issToken=teB%2BzETLJ2HQ2kFm6t6H6yxys5dPNUiZHZZzms3xWa2i%2FNmKDyfYqLSQni3sIcwk%2BiGZakEKFTIjkuD1rbxyPItKx4K47JTpN7bYVBmClDfP%2B;Version=1;Path=/
Access-Control-Allow-Credentials: true

Body

{
  "id": 101,
  "login": "demo",
  "firstname": "Demo User",
  "lastname": "Last name Demo",
  "middlename": "",
  "state": {
    "id": 1,
    "name": "Пользователь активен",
    "comment": "Вход в систему разрешен"
  },
  "theme": 1,
  "ilocale": "ru-RU",
  "defaultScreen": 1,
  "soundOn": false,
  "comment": null,
  "authService": "LOCAL",
  "privileges": [{...}]

Далее все запросы должны использовать cookies issToken, SEMSESSIONID.

Получить данные об объектах

Состав объектов зависит от прав доступа логина пользователя.

Краткая модель

Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/object/shortest" -H "accept: application/json"

Request URL

http://10.0.0.1/sem-restservices/db/object/shortest

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

[
  {
    "id": 10101,
    "shortname": "Объект-1"
  },
  {
    "id": 9747,
    "shortname": "Demo object"
  },..
]

Полная модель

Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/object" -H "accept: application/json"

или

curl -X GET "http://10.0.0.1/sem-restservices/db/object?state=1&state=2"" -H "accept: application/json"

где state - статус объекта (см. Объекты
Request URL

http://10.0.0.1/sem-restservices/db/object

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

[
  {
    "id": 10101,
    "shortname": "СТРЕЛКА",
    "fullname": "ОБЪЕКТ СТРЕЛКА",
    "comment": "Объект для задач тестирования",
    "zipcode": '202302',
    "timezone": 3,
    "area": 500,
    "latitude": 55.832281,
    "longitude": 37.623241,
    "employees": 50,
    "objrubric": {
      "id": 1451,
      "shortname": "Рубрика объекта"
    },
    "sdirobjectstate": {
      "id": 1,
      "objstatename": "новый",
      "comment": "На объекте не установлен или не настроен контроллер"
    },
    "worstparamstate": {
      "id": 1,
      "statename": "Норма",
      "statecolor": "Норма",
      "comment": "Значение худшего статуса у параметра на объекте "
    },
    "worstparamcount": 0,
    "paramtags": [
      "Вода",
      "Напряжение",
      "Температура",
      "НАПРЯЖЕНИЕ",
      "Электроэнергия",
      "Качество",
      "Геркон",
      "Климат",
      "ВВОД",
      "Погода"
    ],
    "calendar": {
      "id": 1,
      "name": "Производственный календарь России",
      "description": "описание календаря"
    },
    "address": 'Москва, Академика Королева',
    "controllersTotalCount": 1,
    "controllersOfflineCount": 1,
    "attrs": {
      "Рабочий тел.": "926-8383948",
      "Должность": "Директор"
    }
  }, .... {}
  ]

Данные по объекту по его ID

Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/object/10101" -H "accept: application/json"

Request URL

http://10.0.0.1/sem-restservices/db/object/10101

Дополнительно к сведениям полной модели выдается режим работы объекта (при его наличии)

Получить устройства, установленные на объекте

Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/object/10101/unit" -H "accept: application/json"

Request URL

http://10.0.0.1/sem-restservices/db/object/10101/unit

Ответ содержит список устройств и полную информацию о способе подключения устройства к контроллеру.

Получить параметры по объекту

Поскольку параметры бывают физические и вычисляемые, то реализовано несколько методов:

Получить физические параметры:
Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/object/10101/cdp" -H "accept: application/json"

Request URL

http://10.0.0.1/sem-restservices/db/object/10101/cdp

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


ctrability	true/false	фильтр по признаку поддержки управления параметром
locked	true/false	фильтр по признаку установленной блокировки на параметр
tag	string	фильтр по установленному тегу на параметр

Например:

curl -X GET "http://10.0.0.1/sem-restservices/db/object/3131/cdp?locked=false&tag=ВОДА&tag=ВВОД"" -H "accept: application/json"

Получить вычисляемые параметры

Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/object/10101/ccp" -H "accept: application/json"

Request URL

http://10.0.0.1/sem-restservices/db/object/10101/ccp

Параметры запросы такие же как у физических параметров.

Универсальный метод запроса параметров
Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/object/10101/params" -H "accept: application/json"

Request URL

http://10.0.0.1/sem-restservices/db/object/10101/params

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


calc	true/false	фильтр, с учетом вычисляемых параметров

Запрос получения параметров с выводом их краткой модели (для быстрых запросов)

Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/contrdeviceparam/shortest?controllerId=1&objectId=1" -H "accept: application/json"

Request URL

http://10.0.0.1/sem-restservices/db/contrdeviceparam/shortest?controllerId=1&objectId=1

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


controllerId	int	номер контроллера
objectId	int	номер объекта

можно задавать один из параметров, или оба.

Получить измерения параметров

Измерения физических параметров

Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/measure/8888/{to}/{from}" -H "accept: application/json"

Request URL

http://10.0.0.1/sem-restservices/db/measure/8888/1632947400000/1633022160000?count=1000

где,
8888 - ID параметра, полученное по запросу выше,
{to} - дата и время начала интервала в UTC в мск;
{from} - дата и время конца интервала в UTC в мск;

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


count	integer	кол-во выдаваемых точек

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

{
  "points": [
    {
      "timestmp": "2021-09-30T16:51:57.032Z",
      "value": 0
    }
  ],
  "id": 0
}

Этот запрос выдает сырые измерения. Платформа ограничивает получение сырых измерений интервалом до 24 часов.

Получить статус параметра

Статусы параметров являются результатом их обработки платформой. Запрос выдает статус параметра на текущий момент времени либо, если на указанное время

Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/contrdeviceparam/770472/state" -H "accept: */*"

Request URL

http://10.3.2.103/sem-restservices/db/contrdeviceparam/770472/state

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

{
  "id": 3,
  "statename": "Критическое",
  "statecolor": "error",
  "comment": "Критическое значение параметра"
}

Значения возможных статусов атрибута statecolor: none, normal, warning, error, critical.

Обработанные измерения физических параметров

Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/measure/average/8888/{to}/{from}" -H "accept: application/json"

Request URL

http://10.0.0.1/sem-restservices/db/measure/8888/average/1632947400000/1633022160000?count=1000

Ответ аналогичный, как в предыдущем запросе. Запрос не ограничивает интервал {to}-{from}, выдаются средниее значения параметра на 30 минутном интервале.

В том случае, если необходимо получить дополительные значения параметра на интервале, можно использовать следующий запрос:
Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/measure/candles/8888/{to}/{from}" -H "accept: application/json"

Request URL

http://10.0.0.1/sem-restservices/db/measure/8888/candles/1632947400000/1633022160000?count=1000

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

{
  "candles": [
    {
      "timestmp": 1632947400000,
      "open": 10,
      "close": 25,
      "low": 1,
      "high": 50
    }, ...
  ]
}

Измерения вычисляемых параметров

Запросы для получения вычисляемого параметра аналогичны как для физических параметров:
Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/calcvalue/9999/{to}/{from}" -H "accept: application/json"
curl -X GET "http://10.0.0.1/sem-restservices/db/calcvalue/average/9999/{to}/{from}" -H "accept: application/json"
curl -X GET "http://10.0.0.1/sem-restservices/db/calcvalue/candles/9999/{to}/{from}" -H "accept: application/json"

где,
9999 - ID параметра, полученное по запросу выше,
{to} - дата и время начала интервала в UTC в мск;
{from} - дата и время конца интервала в UTC в мск;

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


count	integer	кол-во выдаваемых точек

Измерения сигнальных параметров

Запрос значений сигнальных параметров (значения сигнальных параметров могут быть либо 0 либо 1) выполняется отдельными запросами:
Curl

curl -X GET "http://10.0.0.1/sem-restservices/db/signal/9999/{to}/{from}" -H "accept: application/json"

Изменение параметров

Изменять значение можно только физических параметров. Таже следует учитывать тип парамтера. Если параметр имеет сигнальный тип, то его значения могут быть только 0 или 1.

Изменить значение параметра

Curl

curl -X POST "http://10.0.0.1/sem-restservices/db/contrdeviceparam/1/setvalue?value=100" -H "accept: application/json"

Request URL

http://10.0.0.1/sem-restservices/db/contrdeviceparam/1/setvalue?value=100

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


Id	int	номер параметра
value	double	значение параметра (зависит от типа параметра)

Изменение состояние параметров командами внешних систем

Что такое внешние команды, как они работают

Внешние команды разработаны для изменения значений в интеграционных системах. Например, если в платформе зарегистрирован датчик LoraWan, то изменить значения парамтеров этого датчика возможно только через сервер сети LoraWan, в которой находится датчик.

Платформа предоставляет REST API интерфейс для получения списка команд, которые могут быть применены для устройства, и выполнение команд в интеграционных системах.

Каждая команда кроме названия содержит постоянную и переменную часть. Постоянная часть вводится на этапе регистрации команды. Переменная часть команды меняется при запросе на выполнение команд. Постоянная и перерменная часть специфичны для каждой интеграционной системы.
Например, для LoraWAN датчиков переменная часть должна быть в формате номера пакета (постоянная часть). Для Болид-Орион формат переменной части должен отвечать требованиям спецификации Болид-Орион.

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

Получить список внешних команд

Curl

curl -X GET "http://10.0.0.1/sem-restservices/extcommand?deviceId=1" -H "accept: */*"

где deviceId - номер устройства

Важно! Значение DeviceID нужно получить по запросу /sem-restservices/db/object/<ObjectID>/unit (список устройств на объекте, см. выше). Использовать атрибут : deviceconnect.device.id

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

[
  {
    "cmd": "string",
    "data": "string",
    "description": "string",
    "device": {
      "classifier": {
        "description": "string",
        "id": 0,
        "name": "string",
        "sys": true
      },
      "comment": "string",
      "devicename": "string",
      "devicetopic": "string",
      "devicetype": "AXXONSOFT_INTELLECT",
      "driverConfig": "string",
      "hierarchyInstance": {
        "hierarchyId": "string",
        "id": 0,
        "name": "string"
      },
      "id": 0,
      "productnumber": "string",
      "protocolType": {
        "id": "string",
        "name": "string"
      },
      "vendorname": "string"
    },
    "fport": 0,
    "id": 0,
    "name": "string"
  }
]

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

name - имя команды;
id - номер команды;
fport - используется только для LoraWan усторойств;
cmd - постоянная часть команды;
data - переменная часть команды;
device {} - объект с описанием устройства.

Выполнить внешнюю команду

Curl

curl -X POST "http://10.3.2.103/sem-restservices/db/unit/6132/command?commandData=10%3A0&extCommandId=31" -H "accept: */*" -d ""

Request URL

http://10.3.2.103/sem-restservices/db/unit/6132/command?extCommandId=31&commandData=10:0

где,

6132 - Id устройства (см. рест получения устройств на объекте)
extCommand - id команды, см. запрос получения внешних команд.
commandData - переменная часть команды.