WEB REST API — различия между версиями

Материал из TekonWiki
Перейти к: навигация, поиск
Строка 90: Строка 90:
 
Объект DBData представляет собой массив, значения которого зависят от выполняемого запроса.
 
Объект DBData представляет собой массив, значения которого зависят от выполняемого запроса.
  
====  Список параметров ====
 
  
Список идентификаторов параметров системы учета ресурсов.
+
==== Список параметров ====
  
http://host:port/rest/api/ASKUE/DirectoryParams
+
Список идентификаторов параметров системы учета ресурсов.
 +
<pre>http://host:port/rest/api/ASKUE/DirectoryParams</pre>
  
 
Ответ:
 
Ответ:
Строка 160: Строка 160:
 
| Код + 1000
 
| Код + 1000
 
| style="width: 174px;" | Значение параметра нарастающим итогом
 
| style="width: 174px;" | Значение параметра нарастающим итогом
| style="width: 189px;" | &nbsp;
+
| style="width: 189px;" |  
 +
Для нарастающих надо смотреть на время записи, поскольку запись на 00:00 часов одинакова по сути и для значения нарастающим итогом за час и за сутки, месяц
 +
 
 
| style="width: 307px;" |  
 
| style="width: 307px;" |  
 
код - 1060&nbsp;<br/> время -&nbsp;01.09.20 11:00&nbsp;&nbsp;<br/> значение - 15687
 
код - 1060&nbsp;<br/> время -&nbsp;01.09.20 11:00&nbsp;&nbsp;<br/> значение - 15687
Строка 169: Строка 171:
 
| Код + 10000
 
| Код + 10000
 
| style="width: 174px;" | Текущее значение параметра (на момент запроса или последнего измерения)
 
| style="width: 174px;" | Текущее значение параметра (на момент запроса или последнего измерения)
 +
| style="width: 189px;" | &nbsp;
 +
| style="width: 307px;" | &nbsp;
 +
|-
 +
|
 +
Код +&nbsp;
 +
 +
(Тариф&nbsp;– 1) * 2000
 +
 +
| style="width: 174px;" |
 +
Для электросчетчиков&nbsp;
 +
 +
значение параметра по тарифу 1, 2, 3 и т.д.
 +
 
| style="width: 189px;" | &nbsp;
 
| style="width: 189px;" | &nbsp;
 
| style="width: 307px;" | &nbsp;
 
| style="width: 307px;" | &nbsp;
Строка 175: Строка 190:
 
Форма представления параметра: значением расхода или нарастающим итогом, зависит от канала (устройства) измерения.
 
Форма представления параметра: значением расхода или нарастающим итогом, зависит от канала (устройства) измерения.
  
&nbsp;
+
Все параметры, связанные с конкретным устройством можно разделить на две большие группы:
 +
 
 +
*текущие - то, что измерено непосредственно сейчас и отображается на информационном табло прибора
 +
*архивные - результаты измерений аккумлированные в памяти прибора учета
 +
**часовой&nbsp;архив
 +
**посуточный архив
 +
**помесячный архив 
 +
 
 +
С каждого прибора учета, подключенного к системе учета, как правило читаются текущие значения и один или несколько архивов.
 +
 
 +
Алгоритм определение расшифровки кода параметра:
 +
 
 +
*Код меньше 10000 - это значение архивной записи&nbsp;
 +
**определить тарифную зону&nbsp;
 +
**определить тип параметра: нарастающий итог или значение расхода
 +
**определить тип архива: часовой, посуточный или помесячный
 +
**определить идентификатор параметра =&nbsp;&nbsp;Код параметра mod 100 
 +
*&nbsp;Код больше 10000 - это значение текущего измерения&nbsp;
 +
**определить тарифную зону&nbsp;
 +
**определить тип параметра: нарастающий итог или среднее значение
 +
**определить идентификатор параметра =&nbsp;&nbsp;Код параметра mod 100 
 +
 
 +
Пример расшифровки параметров:
 +
 
 +
*10&nbsp; - масса подающая, расход за час
 +
*110 – масса подающая, расход за сутки
 +
*210 – масса подающая, расход за месяц
 +
*1010 – масса подающая нарастающим итогом
 +
*1110 - масса подающая нарастающим итогом
 +
*1210 – масса подающая нарастающим итогом
 +
*10020 – мгновенное значение расхода
 +
*10120 – некорректно
 +
*10220 – некорректно
 +
*11010 – мгновенное значение массы подающей нарастающим итогом
 +
*271&nbsp; - расход за месяц 1 тариф, активная прямая
 +
*2271 – расход за месяц 2 тариф, активная прямая
 +
 
 +
Для приборов учета '''электрической энергии''', набор описателей идентификаторов параметров находится в диапазоне 401..499.<br/> Соответственно для определения по коду параметра смыслового значения следует выполнить преобразование&nbsp;&nbsp;&nbsp;Код параметра mod 100&nbsp; + 400.
 +
 
 +
'''Внимание!''' Важно.<br/> Для архивных параметров время архивной записи соответствует времени записи по часам прибора учета.<br/> Для результатов текущих измерений - время соответствует времени АРМ АСУД, и отражает время последнего опроса прибора учета.
 +
 
 +
Некоторые специальные типы параметров
 +
 
 +
{| border="1" cellpadding="1" cellspacing="1" style="width: 500px;"
 +
|-
 +
| style="width: 112px;" | Идентификатор
 +
| style="width: 375px;" | Описание
 +
| style="width: 375px;" | Примечаение
 +
|-
 +
| style="width: 112px;" | 69
 +
| style="width: 375px;" | Разница в минутах между показаниями часов АРМ и прибора учета
 +
| style="width: 375px;" | Параметр есть только в наборе текущих результатов измерений
 +
|-
 +
| style="width: 112px;" | 82
 +
| style="width: 375px;" |
 +
Оценка опроса.&nbsp;<br/> Значение больше 0 - прибор на&nbsp; связи.<br/> Значенеи равно 0 - нет связи с прибором учета
 +
 
 +
| style="width: 375px;" | Параметр есть только в наборе текущих результатов измерений
 +
|-
 +
| style="width: 112px;" | 83
 +
| style="width: 375px;" | Служебный
 +
| style="width: 375px;" | Параметр есть только в наборе текущих результатов измерений
 +
|-
 +
| style="width: 112px;" | 88
 +
| style="width: 375px;" | Состояние шлейфа подключения импульсных приборов учета
 +
| style="width: 375px;" | Имеет смысл только для приборов со схемой Намур. В остальных случаях отображает только состояние геркона: замкнут / разомкнут
 +
|}
 +
 
 +
==== &nbsp;Список систем учета ====
 +
 
 +
Список идентификаторов систем учета
 +
<pre>http://host:port/rest/api/ASKUE/DirectoryServices</pre>
 +
 
 +
Ответ:
 +
<pre>{
 +
... 
 +
&nbsp;"DBData":
 +
&nbsp; &nbsp; &nbsp; [
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; {
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; "SID":1,
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; "NAME":"ХВС"
 +
&nbsp; &nbsp; &nbsp; &nbsp; }
 +
&nbsp;    ...
 +
&nbsp;    ]
 +
...
 +
}</pre>
 +
 
 +
где,&nbsp;<br/> SID - идентификатор системы учета.
 +
 
 +
==== Список приборов учета ====
 +
 
 +
Список идентификаторов приборов учета, зарегистрированных в системе учета на данном объекте
 +
<pre>http://host:port/rest/api/ASKUE/DirectoryDevices</pre>
 +
 
 +
Ответ:
 +
<pre>{
 +
... 
 +
&nbsp;&nbsp;{
 +
&nbsp; &nbsp; &nbsp; "DBData":
 +
&nbsp; &nbsp; &nbsp; [
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; {
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; "DID":1,
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; "NAME":"ВП-10",
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; "FACTOR":0.01
 +
&nbsp; &nbsp; &nbsp; &nbsp; },
 +
&nbsp;    ...
 +
&nbsp;    ]
 +
...
 +
}</pre>
 +
 
 +
где,&nbsp;<br/> DID - идентификатор прибора учета
 +
 
 +
*< 1000 - импульсный прибор учета
 +
*иначе&nbsp; - цифровой прибор учета
 +
 
 +
FACTOR - коэффициент пересчета импульсов в единицу измеряемой величины. Имеет смысл только для импульсных приборов учета
 +
 
 +
==== Список приборов учета расширенный ====
 +
 
 +
Список всех&nbsp;идентификаторов приборов учета в БД. Отображает полный перечень устройств, которые могут быть подключены к системе учета.
 +
<pre>http://host:port/rest/api/ASKUE/DirectoryDevicesEx</pre>
 +
 
 +
Ответ аналогичен предыдущему запросу
 +
 
 +
==== Список домов ====
 +
 
 +
Список идентификаторов домов, зарегистрированных в системе учета
 +
<pre>http://host:port/rest/api/ASKUE/DirectoryHouses</pre>
 +
 
 +
Ответ:
 +
<pre>{
 +
... 
 +
&nbsp;"DBData":
 +
&nbsp; &nbsp; &nbsp; [
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; {
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; "HID":25,
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; "STREET":"ул. Бородинская",
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; "NUMBER":"1",
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; "BUILDING":"",
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; "KORPUS":""
 +
&nbsp; &nbsp; &nbsp; &nbsp; },
 +
&nbsp;    ...
 +
&nbsp;    ]
 +
...
 +
}</pre>
 +
 
 +
где,&nbsp;<br/> HID - идентификатор дома
  
 
[[Category:ДокументацияСКАДА]]
 
[[Category:ДокументацияСКАДА]]

Версия 13:59, 1 ноября 2020


Введение 

Данное API позволяет получить доступ к данными циркулирующим в ПО АСУД.SCADA посредством выполнения запросов по HTTP(S) протоколу к специализированному WEB-сервису.

WEB-сервис поставляется отдельно или может входить в дистрибутив ПО АСУД.SCADA

Для работы WEB-сервиса требуется отдельная лицензия записанная на USB-ключ защиты

WEB-сервис предоставляет доступ к данным:

  • Учета ресурсов (расход воды, тепла, электроэнергии и т.д.)  - данные аккумулированные в БД учета ресурсов
    WEB-сервис не предоставляет доступа непосредственно к прибору учета.

Общие сведения

Самый простой способ вызвать серверный метод - выполнить GET-запрос со следующим URL-адресом, без содержимого в теле сообщения:

http://host:port/rest/api/[ClassName]/[MethodName]/[ParamValue]

Регистр 

  • ClassName
  • MethodName

- не имеет значения.

Следующие параметры не являются обязательными:

  • port
  • ParamValue

ParamValue - представляет собой список значений параметров, разделенных косой чертой (/), которые соответствуют входным параметрам, необходимым для вызываемого метода сервера.

Если серверный метод не имеет входных параметров, ничего не должно следовать за именем метода в URL-адресе.

Две косые черты (//) в части URL-адреса, представляющей значения параметров, устанавливают значение параметра в этом индексе, как пустую строку.

Значения, передаваемые таким образом, должны быть закодированы, по правилам представления URL-адреса.

Значения являющиеся объектами JSON или массивами JSON должны быть переданы в теле HTTP(S)-запроса.  А тип запроса должен быть POST или PUT. 

Ответ, возвращаемый на запроса, будет содержать в тексте ответа строковое представление JSON-объекта :

{"result":["123456"]}

Если во время вызова на сервере возникает ошибка, такая как истекший сеанс, неавторизованный пользователь или недопустимые входные значения, то вместо свойства 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.572+03:00",
      "currenttime":"2020-11-01T13:33:03.604+03:00",
      "version":"1.0"
    }
  ]
}

starttime - время старта WEB-сервера
currenttime - текущее время WEB-сервера
version - версия ПО WEB-сервера

Данные справочников базы данных

Указанные ниже запросы позволяют получить информацию о конфигурации системы учета ресурсов.

Типовая форма ответа на запросы: 

{
  "result":
  [
        {
      "DBData":
      [
      ]
       }
 ]
}

Объект DBData представляет собой массив, значения которого зависят от выполняемого запроса.


Список параметров

Список идентификаторов параметров системы учета ресурсов.

http://host:port/rest/api/ASKUE/DirectoryParams

Ответ:

{
...  
 "DBData":
      [
                {
          "PARAM":60,
          "NAME":"Время наработки",
          "SMALLNAME":"tнар",
          "UNIT":"ч"
        },
      ...
     ]
...
}

где, 
PARAM - идентификатор учетного параметра.

При обработке запросов с показаниями, значение кода параметра должно интерпретироваться следующим образом.

Код параметра Описание Примечание Пример
1.99 Значение расхода или усредненного значения параметра за час Показание на 01.09.20 11:00 означает расход (или усреднение) параметра с 10:00 до 11:00

код - 60  (время наработки)
время - 01.09.20 11:00  
значение 1

Время наработки канала (устройства) с 10 до 11 часов составило 1 час

код - 31 (температура подающая)
время - 01.09.20 11:00  
значение 15,1

Средняя температура подающей трубы  с 10 до 11 часов составила 15,1 градуса цельсия

101..199 Значение расхода или усредненного значения параметра за сутки

Время всегда 00:00


Показание на 01.09.20 00:00 означает расход (или усреднение) параметра с 01.09.20 00:00 по 01.09.20 23:59

код - 60 
время - 01.09.20 00:00
значение 24

Время наработки канала (устройства) за 01.09.2020  составило 24 час

201..299

Значение расхода или усреднение параметра за месяц 

Дата всегда 01.хх.yy
Время всегда 00:00


Показание на 01.09.20 00:00 означает расход (или усредленени)  параметра с 01.09.20 00:00 по 30.09.20 23:59

 
Код + 1000 Значение параметра нарастающим итогом

Для нарастающих надо смотреть на время записи, поскольку запись на 00:00 часов одинакова по сути и для значения нарастающим итогом за час и за сутки, месяц

код - 1060 
время - 01.09.20 11:00  
значение - 15687

Время наработки канала (устройства) на  01.09.20 11:00 часов составило 15687 часов

Код + 10000 Текущее значение параметра (на момент запроса или последнего измерения)    

Код + 

(Тариф – 1) * 2000

Для электросчетчиков 

значение параметра по тарифу 1, 2, 3 и т.д.

   

Форма представления параметра: значением расхода или нарастающим итогом, зависит от канала (устройства) измерения.

Все параметры, связанные с конкретным устройством можно разделить на две большие группы:

  • текущие - то, что измерено непосредственно сейчас и отображается на информационном табло прибора
  • архивные - результаты измерений аккумлированные в памяти прибора учета
    • часовой архив
    • посуточный архив
    • помесячный архив

С каждого прибора учета, подключенного к системе учета, как правило читаются текущие значения и один или несколько архивов.

Алгоритм определение расшифровки кода параметра:

  • Код меньше 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

Оценка опроса. 
Значение больше 0 - прибор на  связи.
Значенеи равно 0 - нет связи с прибором учета

Параметр есть только в наборе текущих результатов измерений
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
        },
      ...
     ]
...
}

где, 
DID - идентификатор прибора учета

  • < 1000 - импульсный прибор учета
  • иначе  - цифровой прибор учета

FACTOR - коэффициент пересчета импульсов в единицу измеряемой величины. Имеет смысл только для импульсных приборов учета

Список приборов учета расширенный

Список всех идентификаторов приборов учета в БД. Отображает полный перечень устройств, которые могут быть подключены к системе учета.

http://host:port/rest/api/ASKUE/DirectoryDevicesEx

Ответ аналогичен предыдущему запросу

Список домов

Список идентификаторов домов, зарегистрированных в системе учета

http://host:port/rest/api/ASKUE/DirectoryHouses

Ответ:

{
...  
  "DBData":
      [
                {
          "HID":25,
          "STREET":"ул. Бородинская",
          "NUMBER":"1",
          "BUILDING":"",
          "KORPUS":""
        },
      ...
     ]
...
}

где, 
HID - идентификатор дома