WEB REST API
Содержание
- 1 Введение
- 2 Общие сведения
- 3 Доступ к данным учета ресурсов
- 3.1 Данные сервера
- 3.2 Данные справочников базы данных
- 3.2.1 Список параметров
- 3.2.2 Список систем учета
- 3.2.3 Список приборов учета
- 3.2.4 Список приборов учета расширенный
- 3.2.5 Список домов
- 3.2.6 Список точек учета для дома
- 3.2.7 Список точек учета для дома расширенный
- 3.2.8 Список точек учета для квартиры
- 3.2.9 Список точек учета для квартиры расширенный
- 3.2.10 Запрос идентификатора точки учета по серийному номеру и типу системы учета
- 3.3 Данные показаний
- 3.3.1 Запрос показаний по идентификатору точки учета
- 3.3.2 Запрос показаний по идентификатору точки учета расширенный
- 3.3.3 Запрос показаний по типу системы учета для выбранного дома
- 3.3.4 Запрос показаний указанного параметра по типу системы учета для выбранного дома
- 3.3.5 Запрос архивных показаний параметра для точки учета на выбранном интервале
- 3.4 Коммандные запросы
Введение
Данное API позволяет получить доступ к данными циркулирующим в ПО АСУД.SCADA посредством выполнения запросов по HTTP(S) протоколу к специализированному WEB-сервису.
WEB-сервис поставляется отдельно или может входить в дистрибутив ПО АСУД.SCADA
Для работы WEB-сервиса требуется отдельная лицензия записанная на USB-ключ защиты
WEB-сервис предоставляет доступ к данным:
- Учета ресурсов (расход воды, тепла, электроэнергии и т.д.) - данные аккумулированные в БД учета ресурсов.
WEB-сервис не предоставляет доступа непосредственно к прибору учета.
Работу API обеспечивает служба WEBService
Общие сведения
Самый простой способ вызвать серверный метод - выполнить GET-запрос со следующим URL-адресом, без содержимого в теле сообщения:
http://host:port/rest/api/[ClassName]/[MethodName]/[ParamValue]
Регистр
- ClassName
- MethodName
- не имеет значения.
Следующие параметры не являются обязательными:
- port
- ParamValue
ParamValue - представляет собой список значений параметров, разделенных косой чертой (/), которые соответствуют входным параметрам, необходимым для вызываемого метода сервера.
Если серверный метод не имеет входных параметров, ничего не должно следовать за именем метода в URL-адресе.
Две косые черты (//) в части URL-адреса, представляющей значения параметров, устанавливают значение параметра в этом индексе, как пустую строку.
Значения, передаваемые таким образом, должны быть закодированы, по правилам представления URL-адреса.
Значения являющиеся объектами JSON или массивами JSON должны быть переданы в теле HTTP(S)-запроса. А тип запроса должен быть POST или PUT.
При обработке запроса может выполняться аутентификация на основе WEB BASIC.
Ответ, возвращаемый на запроса, будет содержать в тексте ответа строковое представление JSON-объекта :
{"result":["123456"]}
Для ответов в формате JSON может применяться сжатие данных по алгоритму defalte, о чем будет указано в HTTP-заголовке ответа.
Если во время вызова на сервере возникает ошибка, такая как истекший сеанс, неавторизованный пользователь или недопустимые входные значения, то вместо свойства result возвращаемый объект JSON будет содержать свойство error или SessionExpired, например:
{"SessionExpired": "Срок действия указанного сеанса истек из-за бездействия или был недопустимым"} {"error": "Неожиданная ошибка"}
Доступ к данным учета ресурсов
Общий вид запрос для доступа к данным системы учета ресурсов выглядит следующим образом
http://host:port/rest/api/ASKUE/[MethodName]/[ParamValue]
Данные сервера
http://host:port/rest/api/ASKUE/ServerInformation
Ответ:
{ "result": [ { "startime":"2020-11-01T00:00:03.572Z", "currenttime":"2020-11-01T13:33:03.604Z", "version":"1.0" } ] }
starttime - время старта WEB-сервера
currenttime - текущее время WEB-сервера
version - версия ПО WEB-сервера
Время передается в формате ISO8601.
Данные справочников базы данных
Указанные ниже запросы позволяют получить информацию о конфигурации системы учета ресурсов.
Типовая форма ответа на запросы:
{ "result": [ { "DBData": [ ] } ] }
Объект DBData представляет собой массив, значения которого зависят от выполняемого запроса.
Список параметров
Список идентификаторов параметров системы учета ресурсов.
http://host:port/rest/api/ASKUE/DirectoryParams
Ответ:
{ ... "DBData": [ { "PID":60, "NAME":"Время наработки", "SMALLNAME":"tнар", "UNIT":"ч" }, ... ] ... }
где,
PID - идентификатор учетного параметра.
При обработке запросов с показаниями, значение кода параметра должно интерпретироваться следующим образом.
Код параметра | Описание | Примечание | Пример |
1.99 | Значение расхода или усредненного значения параметра за час | Показание на 01.09.20 11:00 означает расход (или усреднение) параметра с 10:00 до 11:00 |
код - 60 (время наработки) Время наработки канала (устройства) с 10 до 11 часов составило 1 час Средняя температура подающей трубы с 10 до 11 часов составила 15,1 градуса цельсия |
101..199 | Значение расхода или усредненного значения параметра за сутки |
Время всегда 00:00
|
код - 60 Время наработки канала (устройства) за 01.09.2020 составило 24 час |
201..299 |
Значение расхода или усреднение параметра за месяц |
Дата всегда 01.хх.yy
|
|
Код + 1000 | Значение параметра нарастающим итогом |
Для нарастающих надо смотреть на время записи, поскольку запись на 00:00 часов одинакова по сути и для значения нарастающим итогом за час и за сутки, месяц |
код - 1060 Время наработки канала (устройства) на 01.09.20 11:00 часов составило 15687 часов |
Код + 10000 | Текущее значение параметра (на момент запроса или последнего измерения) | ||
Код + (Тариф – 1) * 2000 |
Для электросчетчиков значение параметра по тарифу 1, 2, 3 и т.д. |
Форма представления параметра: значением расхода или нарастающим итогом, зависит от канала (устройства) измерения.
Все параметры, связанные с конкретным устройством можно разделить на две большие группы:
- текущие (код параметра > 10000) - то, что измерено непосредственно сейчас и отображается на информационном табло прибора
- архивные (код параметра < 10000) - результаты измерений аккумлированные в памяти прибора учета
- часовой архив
- посуточный архив
- помесячный архив
С каждого прибора учета, подключенного к системе учета, как правило читаются текущие значения и один или несколько архивов.
Алгоритм определение расшифровки кода параметра:
- Код меньше 10000 - это значение архивной записи
- определить тарифную зону
- определить тип параметра: нарастающий итог или значение расхода
- определить тип архива: часовой, посуточный или помесячный
- определить идентификатор параметра = Код параметра mod 100
- Код больше 10000 - это значение текущего измерения
- определить тарифную зону
- определить тип параметра: нарастающий итог или среднее значение
- определить идентификатор параметра = Код параметра mod 100
Пример расшифровки параметров:
- 10 - масса подающая, расход за час
- 110 – масса подающая, расход за сутки
- 210 – масса подающая, расход за месяц
- 1010 – масса подающая нарастающим итогом
- 1110 - масса подающая нарастающим итогом
- 1210 – масса подающая нарастающим итогом
- 10020 – мгновенное значение расхода
- 10120 – некорректно
- 10220 – некорректно
- 11010 – мгновенное значение массы подающей нарастающим итогом
- 271 - расход за месяц, 1 тариф, активная прямая
- 2271 – расход за месяц, 2 тариф, активная прямая
Для приборов учета электрической энергии, набор описателей идентификаторов параметров находится в диапазоне 401..499.
Соответственно для определения по коду параметра смыслового значения следует выполнить преобразование Код параметра mod 100 + 400.
Внимание! Важно.
Для архивных параметров время архивной записи соответствует времени записи по часам прибора учета.
Для результатов текущих измерений - время соответствует времени АРМ АСУД, и отражает время последнего опроса прибора учета.
Некоторые специальные типы параметров
Идентификатор | Описание | Примечаение |
69 | Разница в минутах между показаниями часов АРМ и прибора учета | Параметр есть только в наборе текущих результатов измерений |
82 |
Оценка опроса. |
Параметр есть только в наборе текущих результатов измерений |
83 | Служебный | Параметр есть только в наборе текущих результатов измерений |
88 | Состояние шлейфа подключения импульсных приборов учета | Имеет смысл только для приборов со схемой Намур. В остальных случаях отображает только состояние геркона: замкнут / разомкнут |
Список систем учета
Список идентификаторов систем учета
http://host:port/rest/api/ASKUE/DirectoryServices
Ответ:
{ ... "DBData": [ { "SID":1, "NAME":"ХВС" } ... ] ... }
где,
SID - идентификатор системы учета.
Список приборов учета
Список идентификаторов приборов учета, зарегистрированных в системе учета на данном объекте
http://host:port/rest/api/ASKUE/DirectoryDevices
Ответ:
{ ... { "DBData": [ { "DID":1, "NAME":"ВП-10", "FACTOR":0.01, "COUNT":373 } , ... ] ... }
где,
- DID - идентификатор прибора учета
- < 1000 - импульсный прибор учета
- иначе - цифровой прибор учета
- FACTOR - коэффициент пересчета импульсов в единицу измеряемой величины. Имеет смысл только для импульсных приборов учета
- COUNT - число точек учета для данного типа прибора учета (следует иметь ввиду, что например общедомовой теплосчетчик ВИС.Т может иметь от 1 до 5 точек учета).
Список приборов учета расширенный
Список всех идентификаторов приборов учета в БД. Отображает полный перечень устройств, которые могут быть подключены к системе учета.
http://host:port/rest/api/ASKUE/DirectoryDevicesEx
Ответ:
... "DBData": [ { "DID":1, "NAME":"ВП-10", "FACTOR":0.01 } , ...
Список домов
Список идентификаторов домов, зарегистрированных в системе учета
http://host:port/rest/api/ASKUE/DirectoryHouses
Ответ:
{ ... "DBData": [ { "HID":25, "STREET":"ул. Бородинская", "NUMBER":"1", "BUILDING":"", "KORPUS":"" }, ... ] ... }
где,
- HID - идентификатор дома
Список точек учета для дома
Список идентификаторов точек учета для выбранного дома
http://host:port/rest/api/ASKUE/DirectoryDevRegInfo/HID
Параметры:
- HID - идентификатор дома
Ответ:
{ ... "DBData": [ { "CID":8369, "DID":1001, "UIN":0, "FLAT":0, "INFO":"", "PACCOUNT":"", "KT":1, "SID":1, "DATATYPE":2 } , ... ] ... }
где,
- CID - идентификатор точки учета
- DID - идентификатор прибора учета (1001 - теплосчетчик ВИС.Т
- UIN - серийный номер прибора учета
- FLAT - номер квартиры
- 0 - общедомовые приборы учета
- > 0 - номера квартир
- > 1000 - места общего пользования и нежилые помещения
- INFO - комментарий
- PACCOUNT - персональный идентификатор (не обязательный)
- KT - коэффициент трансформации. Только для электросчетчиков
- SID - идентификатор типа системы учета
- DATATYPE - набор данных точки учета (битовая маска)
- 1 - есть текущие (мгновенные) значения
- 2 - есть часовой архив
- 4 - есть посуточный архив
- 8 - есть помесячный архив
Внимание! Важно!
Серийный номер прибора учета (UIN) хранится в поле типа Integer. Соответсвенно, если серийный номер прибора учета имеет вид, например: 12-0057685, то в БД , как правило, записано просто 57685.
Список точек учета для дома расширенный
Список идентификаторов точек учета для выбранного дома
http://host:port/rest/api/ASKUE/DirectoryDevRegInfoEx/HID
Параметры:
- HID - идентификатор дома
Ответ:
{ ... "DBData": [ { "CID":8369, "DID":1001, "DEVNAME":"ВИС.Т", "UIN":0, "FLAT":0, "INFO":"", "PACCOUNT":"", "KT":1, "SID":1, "SERVNAME":"ХВС", "DATATYPE":2 } , ... ] ... }
по сравнению с предыдущим запросом добавлены имя прибора учета и название системы учета.
Список точек учета для квартиры
Список идентификаторов точек учета для квартиры
http://host:port/rest/api/ASKUE/DirectoryDevRegInfo/HID/FLAT
Параметры:
- HID - идентификатор дома
- FLAT - номер квартиры
Ответ:
аналогичен запросу Список точек учета для дома
Список точек учета для квартиры расширенный
Список идентификаторов точек учета для квартиры
http://host:port/rest/api/ASKUE/DirectoryDevRegInfoEx/HID/FLAT
Параметры:
- HID - идентификатор дома
- FLAT - номер квартиры
Ответ:
аналогичен запросу Список точек учета для дома расширенный.
Запрос идентификатора точки учета по серийному номеру и типу системы учета
Определение идентификатора точки учета по входным параметрам
http://host:port/rest/api/ASKUE/RESOLVECID/HID/SID/UIN
Параметры:
- HID - идентификатор дома
- SID - идентификатор системы учета
- UIN - серийный номер прибора учета (только цифры)
Ответ:
{ ... "DBData": [ { "CID":8370 } ] ... }
Данные показаний
Следующий набор запросов позволяет получить информацию о показаниях приборов учета, сохранненных в БД системы учета
(возможность прямого запроса данных у прибора учета - не реализована).
Запрос показаний по идентификатору точки учета
Полный список последних значений анализируемых параметров точки учета:
- текущие (мгновенные) значения
- последняя архивная запись для каждого из архивов
полученных при последнем опросе прибора системой учета.
http://host:port/rest/api/ASKUE/LastValues/CID
Параметры:
- CID - идентификатор точки учета
Ответ:
... "DBData": [ { "PARAM":10, "RVALUE":20.889, "RDATE":"2020-09-30T11:00:00.000Z" } , { "PARAM":11, "RVALUE":20.886, "RDATE":"2020-09-30T11:00:00.000Z" } , { "PARAM":30, "RVALUE":43, "RDATE":"2020-09-30T11:00:00.000Z" } , ...
, где
- PARAM - код параметра (см. справочник идентификаоторов параметров)
- RVALUE - значение параметра
- RDATE - дата/время в формте ISO
Сортировка: код параметра.
Набор данных для той или иной точки учета, зависит от типа прибора учета.
Запрос показаний по идентификатору точки учета расширенный
Список последних значений анализируемых параметров точки учета, полученных при последнем опросе прибора системой учета.
http://host:port/rest/api/ASKUE/LastValuesEx/CID/DATATYPE
Параметры:
- CID - идентификатор точки учета
- DATATYPE - тип данных (смотри #Список точек учета для дома)
Ответ:
... "DBData": [ { "PARAM":10, "NAMEPARAM":"Mпод", "PARAMUNIT":"т", "RVALUES":20.889, "TTTIME":"2020-09-30T11:00:00.000Z", "VMIN":-100000, "VMAX":100000, "FULLNAME":"Масса подающая", "ALLOWRITE":0, "WRITEMIN":null, "WRITEMAX":null } , { "PARAM":11, "NAMEPARAM":"Mобр", "PARAMUNIT":"т", "RVALUES":20.886, "TTTIME":"2020-09-30T11:00:00.000Z", "VMIN":-100000, "VMAX":100000, "FULLNAME":"Масса обратная", "ALLOWRITE":0, "WRITEMIN":null, "WRITEMAX":null } ...
где,
- VMIN, VMAX - граничные значения для данного параметра
- ALLOWRITE - [0, 1] разрешено ли обновление данного параметра из системы учета
- WRITEMIN, WRITEMAX - допустимые значения параметра при записи из системы учета
- RVALUES - значение параметра
- TTTIME - время
Сортировка: код параметра.
Запрос показаний по типу системы учета для выбранного дома
Это сводный запрос, который отобразит все (текущие + архивные) последние полученные значения для приборов учета выбранного типа ресурса
http://host:port/rest/api/ASKUE/LastValuesForHouse/HID/SID
Параметры:
- HID - идентификатор дома
- SID - идентификатор системы учета (ХВС, ГВС и т.п.)
Ответ:
... "DBData": [ { "FLAT":0, "UIN":1234567, "INFO":"", "PARAM":10, "RVALUE":28.258, "RDATE":"2020-09-30T10:00:00.000Z" } , { "FLAT":0, "UIN":1234567, "INFO":"", "PARAM":11, "RVALUE":28.233, "RDATE":"2020-09-30T10:00:00.000Z" } , ...
Сортировка: квартира, серийный номер, код параметра
Запрос показаний указанного параметра по типу системы учета для выбранного дома
Это сводный запрос, который отобразит последние полученное значения указанного параметра для приборов учета выбранного типа ресурса
http://host:port/rest/api/ASKUE/LastValuesForHouseParam/HID/SID/PARAM
Параметры:
- HID - идентификатор дома
- SID - идентификатор системы учета (ХВС, ГВС и т.п.)
- PARAM - код запрашиваемого параметра, например:
- 11001 - текущее значение объем падающий нарастающим итогом
- 101 - значение расхода объема подающего за сутки
Ответ:
... "DBData": [ { "FLAT":0, "UIN":1234567, "INFO":"", "RVALUE":28, "RDATE":"2020-09-30T10:00:00.000Z" } , { "FLAT":1, "UIN":1234569, "INFO":"", "RVALUE":281, "RDATE":"2020-09-30T10:00:00.000Z" } , ...
Сортировка: квартира, серийный номер.
Запрос архивных показаний параметра для точки учета на выбранном интервале
http://host:port/rest/api/ASKUE/ARCValues/CID/PARAM/DATESTART/DATESTOP
Параметры:
- CID - идентификатор точки учета
- PARAM - код запрашиваемого параметра
- Значение PARAM должно быть < 10000
- Для параметров с кодом > 10000 - значения в БД не аккумулируются (архив не ведется)
- DATESTART, DATESTOP - левая/правая границы интервала в формате ISO8601
Для того, чтобы определить можно ли по тому или иному параметру запрашивать архивные данные, следует сформирвать запрос #Запрос показаний по идентификатору точки учета расширенный с указанным DATATYPE, например: часовой архив DATATYPE = 2, и если параметр присуствует в списке - по нему можно запрашивать архиваные данные.
Пример запроса архивных значений параметра "масса подающая" нарастающим итогом: код параметра 1010 (почасовой расход) на интервале с 30.09.2020 по 01.10.2020 (включительно)
http://host:port/rest/api/ASKUE/ARCValues/8370/1010/2020-09-30T00:00:00.000Z/2020-10-01T00:00:00.000Z
Ответ:
... { "DBData": [ { "RVALUE":1274953.243, "RDATE":"2020-09-30T00:00:00.000Z" } , { "RVALUE":1274974.443, "RDATE":"2020-09-30T01:00:00.000Z" } , ...
Сортировка: по времени.
Коммандные запросы
Следующие запросы позволяют инициировать внеочередной опрос указанного прибора учета ПО АСУД.