Раздел API

Датчики и счётчики

Модуль «Датчики и счётчики»: холодильные контроллеры, ИБП, счётчики электроэнергии, датчики Zigbee и ПЛК по OPC UA (Modbus RTU/TCP, SNMP, Меркурий, Zigbee, OPC UA). Последние значения и тревоги, опрос по запросу, журнал за период и CSV для проверяющих, запись уставок и реле, SNMP-трапы. Настройка устройств — на странице агента (вкладка «Датчики»); нужен модуль sensors в ключе (кроме эмулятора).

Modbus RTU/TCP, SNMP, Меркурий, Zigbee, OPC UA: значения, журнал, тревоги

POST	`/api/v1/sensors/{id}/poll`	Опросить сейчас
POST	`/api/v1/sensors/{id}/points/{point}`	Записать значение точки
GET	`/api/v1/sensors`	Устройства и последние значения
GET	`/api/v1/sensors/{id}`	Устройство и его значения
GET	`/api/v1/sensors/traps`	Последние SNMP-трапы
GET	`/api/v1/sensors/profiles`	Профили устройств
GET	`/api/v1/sensors/journal.csv`	Журнал для Excel и проверяющих (CSV)
GET	`/api/v1/sensors/history`	Журнал значений

Опросить сейчас#

POST/api/v1/sensors/{id}/poll

Не дожидаясь интервала; ответ — свежие значения

Параметры

Имя	Где	Тип	Описание
`id`обязательный	path	string

Ответ 200 application/json

Поля · DeviceView

deviceSensorDevice
22 поля · SensorDevice
- idstring
- namestring
- protocolstring
- profilestring
- portstring
- baudRateinteger int32
- paritystring
- stopBitsinteger int32
- hoststring
- tcpPortinteger int32
- modestring
- unitinteger int32
- communitystring
- snmpVersionstring
- passwordstring
- intervalSecinteger int32
- timeoutMsinteger int32
- alarmDelaySecinteger int32
- enabledboolean
- pointsмассив Point
  16 полей · Point
  - idstring
  - namestring
  - tablestring
  - addressinteger int32
  - typestring
  - wordOrderstring
  - bitinteger int32
  - scalenumber double
  - offsetnumber double
  - unitstring
  - writableboolean
  - minnumber double
  - maxnumber double
  - oidstring
  - paramstring
  - logboolean
- usernamestring
- numberinteger int32
profileNamestring
statusstring
errorstring
lastOkstring
lastPollstring
readingsмассив Reading
10 полей · Reading
- pointstring
- namestring
- valuenumber double
- textstring
- unitstring
- atstring
- alarmstring
- minnumber double
- maxnumber double
- writableboolean
alarmsinteger int32
zigbeeZigbeeView
4 поля · ZigbeeView
- statestring
- coordinatorstring
- permitJoinLeftinteger int32
- nodesмассив Node
  6 полей · Node
  - ieeestring
  - nwkinteger int32
  - manufacturerstring
  - modelstring
  - endpointsсловарь → массив integer int32
  - joinedAtstring
detailstring

Ошибки — problem+json с полем code, см. коды ошибок.

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

curl

curl -X POST 'http://localhost:7790/api/v1/sensors/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/poll'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/sensors/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/poll' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Записать значение точки#

POST/api/v1/sensors/{id}/points/{point}

Только точки с writable: true (уставка, реле Zigbee вкл/выкл — 1/0). Без модуля — 402 LICENSE_REQUIRED

Параметры

Имя	Где	Тип	Описание
`id`обязательный	path	string
`point`обязательный	path	string

Тело запроса application/json обязательное

Поля · WriteRequest

valuenumber double

JSON

{
  "value": 1.5
}

Ответ 200 application/json

Поля · Reading

pointstring
namestring
valuenumber double
textstring
unitstring
atstring
alarmstring
minnumber double
maxnumber double
writableboolean

Ошибки — problem+json с полем code, см. коды ошибок.

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

curl

curl -X POST 'http://localhost:7790/api/v1/sensors/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/points/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11' \
  -H 'Content-Type: application/json' \
  --data '{"value":1.5}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/sensors/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/points/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Content-Type: application/json' \
  --data '{"value":1.5}'

Устройства и последние значения#

GET/api/v1/sensors

Каждое устройство: состояние опроса, точки с последним значением, тревоги (alarm: high/low)

Ответ 200 application/json

Поля · SensorList

licensedboolean
devicesмассив DeviceView
10 полей · DeviceView
- deviceSensorDevice
  22 поля · SensorDevice
  - idstring
  - namestring
  - protocolstring
  - profilestring
  - portstring
  - baudRateinteger int32
  - paritystring
  - stopBitsinteger int32
  - hoststring
  - tcpPortinteger int32
  - modestring
  - unitinteger int32
  - communitystring
  - snmpVersionstring
  - passwordstring
  - intervalSecinteger int32
  - timeoutMsinteger int32
  - alarmDelaySecinteger int32
  - enabledboolean
  - pointsмассив Point
    16 полей · Point
    idstring
    namestring
    tablestring
    addressinteger int32
    typestring
    wordOrderstring
    bitinteger int32
    scalenumber double
    offsetnumber double
    unitstring
    writableboolean
    minnumber double
    maxnumber double
    oidstring
    paramstring
    logboolean
  - usernamestring
  - numberinteger int32
- profileNamestring
- statusstring
- errorstring
- lastOkstring
- lastPollstring
- readingsмассив Reading
  10 полей · Reading
  - pointstring
  - namestring
  - valuenumber double
  - textstring
  - unitstring
  - atstring
  - alarmstring
  - minnumber double
  - maxnumber double
  - writableboolean
- alarmsinteger int32
- zigbeeZigbeeView
  4 поля · ZigbeeView
  - statestring
  - coordinatorstring
  - permitJoinLeftinteger int32
  - nodesмассив Node
    6 полей · Node
    ieeestring
    nwkinteger int32
    manufacturerstring
    modelstring
    endpointsсловарь → массив integer int32
    joinedAtstring
- detailstring

Ошибки — problem+json с полем code, см. коды ошибок.

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

curl

curl 'http://localhost:7790/api/v1/sensors'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/sensors' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Устройство и его значения#

GET/api/v1/sensors/{id}

Параметры

Имя	Где	Тип	Описание
`id`обязательный	path	string

Ответ 200 application/json

Поля · DeviceView

deviceSensorDevice
22 поля · SensorDevice
- idstring
- namestring
- protocolstring
- profilestring
- portstring
- baudRateinteger int32
- paritystring
- stopBitsinteger int32
- hoststring
- tcpPortinteger int32
- modestring
- unitinteger int32
- communitystring
- snmpVersionstring
- passwordstring
- intervalSecinteger int32
- timeoutMsinteger int32
- alarmDelaySecinteger int32
- enabledboolean
- pointsмассив Point
  16 полей · Point
  - idstring
  - namestring
  - tablestring
  - addressinteger int32
  - typestring
  - wordOrderstring
  - bitinteger int32
  - scalenumber double
  - offsetnumber double
  - unitstring
  - writableboolean
  - minnumber double
  - maxnumber double
  - oidstring
  - paramstring
  - logboolean
- usernamestring
- numberinteger int32
profileNamestring
statusstring
errorstring
lastOkstring
lastPollstring
readingsмассив Reading
10 полей · Reading
- pointstring
- namestring
- valuenumber double
- textstring
- unitstring
- atstring
- alarmstring
- minnumber double
- maxnumber double
- writableboolean
alarmsinteger int32
zigbeeZigbeeView
4 поля · ZigbeeView
- statestring
- coordinatorstring
- permitJoinLeftinteger int32
- nodesмассив Node
  6 полей · Node
  - ieeestring
  - nwkinteger int32
  - manufacturerstring
  - modelstring
  - endpointsсловарь → массив integer int32
  - joinedAtstring
detailstring

Ошибки — problem+json с полем code, см. коды ошибок.

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

curl

curl 'http://localhost:7790/api/v1/sensors/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/sensors/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Последние SNMP-трапы#

GET/api/v1/sensors/traps

До 50, новые первыми; приём включается настройкой trapPort

Ответ 200 application/json

Тип: массив словарь → любое значение

Ошибки — problem+json с полем code, см. коды ошибок.

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

curl

curl 'http://localhost:7790/api/v1/sensors/traps'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/sensors/traps' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Профили устройств#

GET/api/v1/sensors/profiles

Встроенные карты регистров и OID, и свои из data/sensors/profiles

Ответ 200 application/json

Массив · SensorProfile

idstring
namestring
vendorstring
kindstring
protocolstring
baudRateinteger int32
paritystring
stopBitsinteger int32
unitinteger int32
notestring
pointsмассив Point
16 полей · Point
- idstring
- namestring
- tablestring
- addressinteger int32
- typestring
- wordOrderstring
- bitinteger int32
- scalenumber double
- offsetnumber double
- unitstring
- writableboolean
- minnumber double
- maxnumber double
- oidstring
- paramstring
- logboolean
customboolean

Ошибки — problem+json с полем code, см. коды ошибок.

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

curl

curl 'http://localhost:7790/api/v1/sensors/profiles'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/sensors/profiles' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Журнал для Excel и проверяющих (CSV)#

GET/api/v1/sensors/journal.csv

Разделитель «;», дробная часть через запятую; по умолчанию — текущий месяц

Параметры

Имя	Где	Тип
`device`	query	string
`from`	query	string date
`to`	query	string date

Ответ 200

Файл.

Ошибки — problem+json с полем code, см. коды ошибок.

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

curl

curl 'http://localhost:7790/api/v1/sensors/journal.csv'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/sensors/journal.csv' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Журнал значений#

GET/api/v1/sensors/history

Значения точек раз в historySec и каждое срабатывание и снятие тревоги. Даты — yyyy-MM-dd, по умолчанию сегодня

Параметры

Имя	Где	Тип
`device`	query	string
`point`	query	string
`from`	query	string date
`to`	query	string date
`limit`	query	integer int32

Ответ 200 application/json

Массив · HistoryRow

atstring
devicestring
pointstring
valuenumber double
unitstring
alarmstring

Ошибки — problem+json с полем code, см. коды ошибок.

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

curl

curl 'http://localhost:7790/api/v1/sensors/history'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/sensors/history' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'