Все сервисы используют базовый 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",
"Должность": "Директор"
}
}, .... {}
]
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 -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 -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"
}
]
Параметры ответа:
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
где,