RestAPI backend-сервера ЭНТЕК
Содержание
1. Протокол
2. Доступ к API
7. Мнемосхемы
8. Данные АСКУЭ
9. Данные SCADA
Сервер REST API работает по открытому и защищенному протоколу SSL/TLS. Настройка портов производится в конфигурационном файле, также необходимо указать путь до сертификата при использовании HTTPs и часовой пояс в переменной UTC. В переменной Threads задается количество потоков REST сервера, по умолчанию значение равно 10.
[Server]
Port=8849
UTC=3
Threads=10
[DispatcherFields]
FieldsUSPD=435, 407
FieldsTU=431, 429
FieldsPotr=
[HTTPs]
Port=8848
Path=C:\ENTEK\cert\server.pem
;Password=
Для расширения лога необходимо произвести запуск с ключом -dl.
Запрашиваемый ресурс API задается одним или несколькими уровнями URL, следующими после неизменяемой части начала запроса /entek/api/…. Ресурс допускает использование пробелов и символов кириллицы. Некоторые ресурсы API допускают или требуют применение параметров запроса (следующих после символа '?' значений или пар имя=значение, разделенных символом '&').
Общий вид запроса: https://<IP-адрес_или_домен>:<порт>/entek/api/<запрашиваемый_ресурс> [?<параметр_запроса_1>&<параметр_запроса_2>&...]
Также доступна HTML страница для диагностики работы сервера (https://<IP-адрес_или_домен>: <порт>/entek/api/start).
Запрошенный ресурс API возвращает данные в формате JSON. О наличии в ответе данных запрошенного ресурса свидетельствует статус HTTP ответа 200 (ОК). Отсутствие данных при корректном запросе и штатном функционировании сервера обозначается статусом 404 (Not Found). При ошибке авторизации возвращается ошибка 401 (Unauthorized).
запрос: entek/api/login
Запрос содержит параметры Basic-аутентификации - имя и пароль пользователя проекта (например, 'admin' и '123'). В случае успеха ответ содержит токен ("token") - идентификатор для пользователя сессии. Также в ответе присутствует стартовая мнемохсема startMnemoGuid и навигационная мнемосхема naviMnemoGuid, если она присутствует в визуализации.
Пример ответа:
{
"token": "e5111278-e1ce-4a68-80e5-7154b86e79b1",
"name": "admin",
"group": "",
"fullname": "Admin Adminov",
"result": "true",
"startMnemoGuid": "21D1D68D-86F4-4F69-B254-543D215FF6C4",
"naviMnemoGuid": "C7C1699C-2F7B-41DE-A875-B5B382E3007B"
}
Последующие запросы ресурсов API должны содержать заголовок Pragma с параметром
dssession=token
Например,
Pragma=dssession=e5111278-e1ce-4a68-80e5-7154b86e79b1
В каждом ответе на запрос заголовок Pragma передает параметр dssessionexpires со значением времени (в миллисекундах), оставшегося до окончания сессии. В случае, если следующий запрос в рамках данный сессии подается по истечении этого времени, ответ имеет статус HTTP 401 (Unauthorized), что означает необходимость повторной авторизации пользователя. Время жизни неактивной сессии 5 минут, после чего она закрывается. Информация о текущих сессиях доступна на веб-страницы диагностики, а также отображается в логе сервера.
Для поддержания сессии может использоваться следующий запрос: entek/api/ping
Ответ содержит текущее время сервера:
{"ping":"2020-09-24T14:27:21.465+03:00"}
Для закрытия сессии служит запрос: entek/api/logout
Ответ содержит сообщение об успешном закрытии сессии:
{"session":"terminated e5111278-e1ce-4a68-80e5-7154b86e79b1"}
или о неудаче:
{"session":"not terminated"}
запрос: entek/api/info
Проверка доступности API содержит в ответе информация о сервере в формате JSON. Запрос не требует аутентификации.
Пример ответа:
{
"info": {
"project": "WEB SCADA",
"authentication": "Basic",
"system": "SCADA ENTEK (tm)",
"company": "Энергоресурс, Энтелс 2020-2021гг.",
"version": "1.0/win32",
"date": "2024-01-19T08:51:24.364"
}
}
Ответы выдаются в формате JSON. Пустые поля в значении параметра (value) содержат null.
Выдаваемые поля настраиваются в конфигурационном файле и указываются в виде целого числа соответствующего системному названию поля.
Пример настройки полей в конфигурационном файле:
[DispatcherFields]
FieldsUSPD=435, 407
FieldsTU=431, 429
FieldsPotr=...
запрос: entek/api/docs/objects/ascue_set
Запрос списка объектов и их точек учета. Ответ содержит в себе информацию о названии объекта, серийный номер точки учета, идентификаторы в базе данных объекта и каждой точки учета, настройки аскуэ. Также есть возможность запроса с применением фильтров, которые описываются в теле запроса в формате JSON. Значение переменной field является кодом столбца, который можно посмотреть в настройках таблицы в модуле Справочники. Все фильтры объединяются через логическое И. Если field или value отсутствуют или переданы с пустым значением, то фильтр не применяется. Если объекты не найдены, ответ будет содержать пустой массив objects.
-
Настройки АСКУЭ объекта могут содержать следующие переменные: uspd_type, psw, ip1, port1, ip2, port2, link_type, timeout. Если Каких-то настроек нет, то значение переменной - пустая строка.
-
Настройки АСКУЭ точки учета могут содержать следующие переменные: tu_type, use_sn, res_type, addr, psw1, psw2, dev_id. Переменные tu_type, use_sn являются обязательными и всегда содержатся в ответе, остальные могут отсутствовать, если не заданы в базе данных.
Пример фильтра, передаваемого в теле запроса:
{
"filters": [
{
"field": "F406",
"value": "ТП"
},
{
"field": "F412",
"value": "Ивановский"
}
]
}
Пример ответа:
{
"objects": [
{
"id": 27722,
"name": "Меркурий 204",
"ascue": {
"uspd_type": "7",
"psw": "",
"port1": "4002",
"ip2": "",
"port2": "30292",
"link_type": "2",
"timeout": "3000"
},
"tus": [
{
"id": 27723,
"serial": "",
"tu_id": "",
"ascue": {
"tu_type": "94",
"use_sn": "True",
"res_type": "1",
"addr": "80",
"psw1": "111111",
"psw2": "2222222222222222"
}
}
]
}
]
}
запрос: entek/api/ascue/save
Запрос для сохранения данных по точкам учета. Показания передаются в теле запроса, поддержан вариант передачи одной записи или массива с несколькими. Тело запроса состоит из следующих переменных:
-
id - идентификатор точки учета в базе данных (можно получить в запросах информации о точках учета)
-
serial - серийный номер точки учета
-
timestamp - временная метка показаний
-
data - массив показаний
-
data - массив показаний
-
id - идентификатор параметра (информация предоставляется по запросу)
-
v - значение с типом float
Показания, которые сохраняются таким способом не отображаются в модуле Энергоанализ. Для просмотра и мониторинга есть html формы, стартовая страница находится по запросу entek/api/ascue_html
Пример запроса с массивом:
[
{
"id": 72924,
"serial": "23232003105",
"timestamp": "2024-08-26T10:55:17",
"data": [
{
"id": 10,
"v": 122.0
}
]
},
{
"id": 72924,
"serial": "2323200ac3105",
"timestamp": "2024-08-27T11:00:17",
"data": [
{
"id": 10,
"v": 122.0
},
{
"id": 75,
"v": 1.0
}
]
}
]
запрос: entek/api/docs/meters/serialno/<номер>
номер - серийный номер счетчика. Поля, являющиеся ссылкой на запись другого журнала, содержат в себе идентификатор этой записи в БД.
Пример ответа:
{
"TU": {
"id": "27393",
"fields": [
{
"fieldName": "F303",
"value": "25626254",
"userName": "№ сч."
},
{
"fieldName": "F438",
"value": "null",
"userName": "Ктт"
},
{
"fieldName": "F439",
"value": "null",
"userName": "Ктн"
},
{
"fieldName": "F345",
"value": "M233-25626254",
"userName": "Назначение/место установки"
},
{
"fieldName": "F408",
"value": "27391",
"userName": "Объект"
},
{
"fieldName": "F429",
"value": "2022-12-20T00:00:00",
"userName": "Дата наладки"
},
{
"fieldName": "F431",
"value": "Нет",
"userName": "Замечания"
},
{
"fieldName": "F452",
"value": "27397",
"userName": "Потребитель"
}
]
}
}
запрос: entek/api/docs/meters/id/<идентификатор>
<идентификатор> - идентификатор счетчика в БД.
запрос: entek/api/docs/meters/<идентификатор>/object
идентификатор - идентификатор счетчика в БД.
Пример ответа:
{
"Object": [
{
"fieldName": "F406",
"value": "Контроллер Офис",
"userName": "Объект"
},
{
"fieldName": "F407",
"value": "Группа 1",
"userName": "Группа"
},
{
"fieldName": "F435",
"value": "Киевское шоссе",
"userName": "Адрес"
}
]
}
запрос: entek/api/docs/meters/<идентификатор>/consumer
идентификатор - идентификатор счетчика в БД.
Пример ответа:
{
"Consumer": [
{
"fieldName": "F446",
"value": "ООО \"Энтелс\"",
"userName": "Потребитель"
},
{
"fieldName": "F447",
"value": "111111111",
"userName": "Договор"
},
{
"fieldName": "F448",
"value": "222222222",
"userName": "ИНН"
}
]
}
запрос: entek/api/docs/objects/<идентификатор>/meters
идентификатор - идентификатор объекта в БД.
Пример ответа:
{
"TUs": [
{
"id": "27392",
"fields": [
{
"fieldName": "F303",
"value": "40737447",
"userName": "№ сч."
},
{
"fieldName": "F438",
"value": "10",
"userName": "Ктт"
},
{
"fieldName": "F439",
"value": "10",
"userName": "Ктн"
},
{
"fieldName": "F345",
"value": "M233-40737447",
"userName": "Назначение/место установки"
},
{
"fieldName": "F408",
"value": "27391",
"userName": "Объект"
},
{
"fieldName": "F429",
"value": "2022-12-20T00:00:00",
"userName": "Дата наладки"
},
{
"fieldName": "F431",
"value": "null",
"userName": "Замечания"
},
{
"fieldName": "F452",
"value": "27396",
"userName": "Потребитель"
}
]
}
]
}
запрос: entek/api/docs/consumers/<идентификатор>/meters
идентификатор - идентификатор потребителя в БД.
запрос: entek/api/docs/meters/all
Ответ содержит список всех счетчиков с их идентификатором и серийным номером.
Пример ответа:
{
"TUs": [
{
"id": "27392",
"fields": [
{
"fieldName": "F303",
"value": "40737447",
"userName": "№ сч."
}
]
},
{
"id": "27393",
"fields": [
{
"fieldName": "F303",
"value": "25626254",
"userName": "№ сч."
}
]
},
{
"id": "27394",
"fields": [
{
"fieldName": "F303",
"value": "44622236",
"userName": "№ сч."
}
]
},
{
"id": "27395",
"fields": [
{
"fieldName": "F303",
"value": "12279137487044",
"userName": "№ сч."
}
]
}
]
}
запрос: entek/api/mnemos/ltools_dialogs
Запрос возвращает ответ в формате json, в котором содержатся названия классов и guid шаблонной мнемосхемы из файла KVision/Extensions/lTools.xml.
Пример ответа:
[
{
"class_name": "TRosseti_breaker",
"mnemo_templ_id": "{F6D19E3A-6CCB-43D2-ACF9-25AE3E4F5171}"
},
{
"class_name": "TGroundDisconnector",
"mnemo_templ_id": "{EB8838CE-91C8-4CC2-94A0-C08C8C74FA70}"
}
]
запрос: entek/api/mnemos/<мнемосхема>
мнемосхема - может принимать следующие значения:
1. 0 или entry - ответ содержит стартовую мнемосхему.
2. GUID или Id - идентификатор мнемосхемы.
3. Пустое значение – перечень всех мнемосхем.
Пример ответа:
{
"schemes": [
{
"id": 25,
"name": "START",
"guid": "{21D1D68D-86F4-4F69-B254-543D215FF6C4}"
}
]
}
запрос: entek/api/mnemos/<мнемосхема>/scheme?<параметр>=<значение_1>,...
мнемосхема - может принимать следующие значения:
1. 0 или entry - ответ содержит стартовую мнемосхему.
2. GUID или Id - идентификатор мнемосхемы.
Параметры запроса:
|
имя параметра
|
описание
|
|
include
|
включает в ответ только указанные разделы мнемосхемы
|
|
exclude
|
исключает из ответа указанные разделы мнемосхемы
|
параметры include и exclude не могут присутствовать в запросе одновременно Допустимые значения параметров запроса: name, guid, settings, controls (через ',' или ';').
Пример ответа:
{
"mnemo": {
"id": 25,
"name": "START",
"guid": "{21D1D68D-86F4-4F69-B254-543D215FF6C4}",
"settings": {
"ID": "{21D1D68D-86F4-4F69-B254-543D215FF6C4}",
"Name": "START",
"Comments": "",
"BkColor": "#000000",
"Width": 1300,
"Height": 700
},
"Controls": [
{
"ClassName": "TBBRotateLabel",
"ID": "{6CB72DEA-AF09-4595-8FC3-C8DD621AA8D8}",
"Idx": 0,
"Left": 20,
"Top": 104,
"Width": 208,
"Height": 22,
"Obj": {
"Text": "Элементы мнемосхем",
"Font": {
"Name": "Arial",
"Size": 14,
"Color": "#FFFFFF",
"Bold": true
}
}
}
]
}
}
запрос: /entek/api/mnemos/highlight_elements
Запрос предназначен для подсветки элементов подстанции на мнемосхеме, который должен содержать тело для дальнейшей передачи в EVP. При успешном запросе ответ содержит параметр infoCode равный 0, иначе - 1 и присутствует параметр infoString с описанием ошибки.
Пример ответа:
{
"infoCode": 1,
"infoString": "Подсветка элементов подстанции не разрешена"
}
запрос: entek/api/dialogs/<диалог>
диалог - может принимать следующие значения:
1. GUID или Id - идентификатор диалога.
2. Пустое значение – перечень всех диалогов.
Пример ответа:
{
"dialogs": [
{
"id": 51,
"name": "Основной сервер ССПИ",
"guid": "{45218BF4-B89E-4DCE-A790-8DE6E08728AD}"
}
]
}
запрос: entek/api/ dialogs/<мнемосхема>/scheme?< диалог>=<значение_1>,...
диалог - GUID или Id идентификатор диалога.
Параметры запроса:
|
имя параметра
|
описание
|
|
include
|
включает в ответ только указанные разделы мнемосхемы
|
|
exclude
|
исключает из ответа указанные разделы мнемосхемы
|
параметры include и exclude не могут присутствовать в запросе одновременно
Допустимые значения параметров запроса: name, guid, settings, controls (через ',' или ';').
Пример ответа:
{
"dialog": [
{
"id": 51,
"name": "Основной сервер ССПИ",
"guid": "{45218BF4-B89E-4DCE-A790-8DE6E08728AD}",
"settings": {
"ID": "{45218BF4-B89E-4DCE-A790-8DE6E08728AD}",
"Name": "Основной сервер ССПИ",
"Comments": "",
"BkColor": "#D5D6D1",
"Width": 720,
"Height": 670
},
"Controls": [
{
"ClassName": "TRemShapes",
"ID": "{05D9B156-73EC-464A-9545-F76106CCF0C2}",
"Idx": -1,
"Left": 353,
"Top": 56,
"Width": 300,
"Height": 50,
"Obj": {
"Shape": "jstRectangle",
"Border": {
"Style": "psSolid",
"Color": "#000000",
"Width": 1
},
"Brush": {
"Style": "bsSolid",
"Color": "#FFFFFF"
},
"UseGradient": false
}
}
]
}
]
}
запрос: entek/api/meters/<идентификатор>/readings?<параметр>=<значение_1>,...
идентификатор - идентификатор потребителя в БД.
|
имя
параметра
|
описание
|
допустимые значения
|
|
date
|
дата-время начала поиска показаний
|
запрос возвращает ближайшие показания к началу заданного интервала
от указанного даты-времени до текущего времени.
|
|
since
|
включает в ответ только указанные значения
|
запрос возвращает ближайшие показания к концу заданного интервала от указанного даты-времени до текущего времени.
|
|
include
|
исключает из ответа указанные поля
|
'active', 'reactive' - активная и/или реактивная энергия для электроэнергии и их аналоги для неэлектрических ресурсов, 'direct', 'reverse' - прямое и обратное направление учета (через ',' или ';'). По умолчанию используется параметр &include=active;direct;reverse
|
|
exclude
|
исключает из ответа указанные поля
|
аналогично параметру include
|
|
tarifs
|
номера тарифов счетчика
|
номера тарифов: целые числа 0..8 (0 - круглосуточный) через ','. По умолчанию используется параметр &tarifs=0
|
-
запрос должен содержать один из параметров date или since, формат даты ISO8601 (пример: 2014-12-01T00:00:00.000Z)
-
параметры include и exclude не могут присутствовать в запросе одновременно
Пример ответа:
{
"readings": {
"active": {
"direct": {
"tarif0": {
"value": "14805.400085",
"units": "кВтч",
"timestamp": "2022-12-20T00:00:17.0Z"
}
},
"reverse": {
"tarif0": {
"value": "61.799997",
"units": "кВтч",
"timestamp": "2022-12-20T00:00:17.0Z"
}
}
},
"reactive": {
"direct": {
"tarif0": {
"value": "369.000006",
"units": "кВАрч",
"timestamp": "2022-12-20T00:00:17.0Z"
}
},
"reverse": {
"tarif0": {
"value": "43323.599243",
"units": "кВАрч",
"timestamp": "2022-12-20T00:00:17.0Z"
}
}
}
}
}
запрос: entek/api/meters/<идентификатор>/graph/hourly?<параметр>=<значение_1>,...
идентификатор - идентификатор потребителя в БД.
|
имя параметра
|
описание
|
допустимые значения
|
|
since
|
дата-время начала графика
|
формат даты ISO8601 (пример: 2014-12-01T00:00:00.000Z)
|
|
till
|
дата- время конца графика
|
аналогично параметру since
|
|
include
|
включает в ответ только указанные значения
|
'active', 'reactive' - активная и/или реактивная энергия для электроэнергии и их аналоги для неэлектрических ресурсов, 'direct', 'reverse' - прямое и обратное направление учета (через ',' или ';'). По умолчанию используется параметр &include=active;direct;reverse
|
-
запрос должен содержать оба параметра since и till
-
если параметр include не содержит значений 'direct' и 'reverse', результатом является разность значений прямого и обратного направления учета (если какое-либо направление учета отсутствует, его величина считается равной 0). Если параметр include содержит оба значения 'direct' и 'reverse', ответ содержит оба значения, дополненные знаками '+' и '-', например:
"active+":"3296.2148",
"active-":"0.0000",
"reactive+":"188.0654",
"reactive-":"0.0000"
Пример ответа:
{
"graph": [
{
"from": "2022-12-18T10:00:00.000Z",
"to": "2022-12-18T11:00:00.000Z",
"active+": "2.800000",
"active-": "0.000000",
"reactive+": "0.200000",
"reactive-": "0.500000"
},
{
"from": "2022-12-18T11:00:00.000Z",
"to": "2022-12-18T12:00:00.000Z",
"active+": "2.800000",
"active-": "0.000000",
"reactive+": "0.200000",
"reactive-": "0.500000"
},
{
"from": "2022-12-18T12:00:00.000Z",
"to": "2022-12-18T13:00:00.000Z",
"active+": "2.800000",
"active-": "0.000000",
"reactive+": "0.100000",
"reactive-": "0.400000"
},
{
"from": "2022-12-18T13:00:00.000Z",
"to": "2022-12-18T14:00:00.000Z",
"active+": "2.800000",
"active-": "0.000000",
"reactive+": "0.100000",
"reactive-": "0.400000"
}
],
"legend": {
"active": {
"units": "кВтч",
"title": "электроэнергия активная"
},
"reactive": {
"units": "кВАрч",
"title": "электроэнергия реактивная"
}
}
}
запрос: entek/api/meters/<идентификатор>/graph/half-hourly?<параметр>=<значение_1>,...
запрос применим только к счетчикам электроэнергии
запрос: entek/api/meters/<идентификатор>/graph/daily?<параметр>=<значение_1>,...
запрос: entek/api/meters/<идентификатор>/graph/monthly?<параметр>=<значение_1>,...
запрос: entek/api/meters/<идентификатор>/values?<параметр>=<значение_1>,...
|
имя параметра
|
описание
|
допустимые значения
|
|
since
|
дата-время начала поиска значений
|
запрос возвращает последние (текущие) значения мгновенных параметров после указанного даты-времени
|
|
include
|
включает в ответ только указанные значения
|
список мгновенных параметров (перечисляется через ',' или ';'): P, Pa, Pb, Pc, Q, Qa, Qb, Qc, S, Sa, Sb, Sc - мощности активная, реактивная и полная (линейный и фазные); Ua, Ub, Uc, Ia, Ib, Ic - фазные напряжения и токи;
CosFi, CosFia, CosFib, CosFic - коэффициенты мощности (линейный и фазные); F - частота; dT - расхождение часов счетчика и сервера; по умолчанию используется полный набор параметров, применимый к типу ресурса данного счетчика
|
-
параметр since обязателен; формат даты параметра ISO8601 (пример: 2014-12- 01T00:00:00.000Z)
Пример ответа:
{
"values": {
"P": {
"title": "Мощность активная суммарная",
"units": "кВт",
"value": "29.080000",
"timestamp": "2022-12-20T00:04:14.0Z"
},
"Pa": {
"title": "Мощность активная, фаза A",
"units": "кВт",
"value": "29.080000",
"timestamp": "2022-12-20T00:04:14.0Z"
},
"Pb": {
"title": "Мощность активная, фаза B",
"units": "кВт",
"value": "0.000000",
"timestamp": "2022-12-20T00:04:14.0Z"
},
"Pc": {
"title": "Мощность активная, фаза C",
"units": "кВт",
"value": "0.000000",
"timestamp": "2022-12-20T00:04:14.0Z"
}
}
}
запрос: entek/api/meters/<идентификатор>/value/<измерение>?<параметр>=<значение>,...
-
идентификатор - идентификатор потребителя в БД. измерение - один из мгновенных параметров: P, Pa, Pb, Pc, Q, Qa, Qb, Qc, S, Sa, Sb, Sc - мощности активная, реактивная и полная (линейный и фазные);
-
Ua, Ub, Uc, Ia, Ib, Ic - фазные напряжения и токи;
-
CosFi, CosFia, CosFib, CosFic - коэффициенты мощности (линейный и фазные);
-
F - частота;
-
dT - расхождение часов счетчика и сервера.
|
имя параметра
|
описание
|
допустимые значения
|
|
since
|
дата-время начала графика
|
формат даты ISO8601 (пример: 2014-12-01T00:00:00.000Z)
|
|
include
|
дата-время конца графика
|
аналогично параметру since
|
-
запрос должен содержать оба параметра since и till
Пример ответа:
{
"data": [
{
"value": "238.039993",
"timestamp": "2022-12-20T00:01:56.0Z"
}
],
"legend": {
"units": "В",
"title": "Фазное напряжение, фаза A"
}
}
запрос: entek/api/meters/<идентификатор>/reading/<измерение>?<параметр>=<значение>,…
идентификатор - идентификатор потребителя в БД.
измерение - один из мгновенных параметров:
-
A+, A-, R+, R- - активная электроэнергия (прямая и обратная), реактивная электроэнергия (прямая и обратная);
-
An+, An-, Rn+, Rn- - активная электроэнергия (прямая и обратная), реактивная электроэнергия (прямая и обратная) по тарифу n (номер 1..8).
|
имя параметра
|
описание
|
допустимые значения
|
|
since
|
дата-время начала графика
|
формат даты ISO8601 (пример: 2014-12-01T00:00:00.000Z)
|
|
till
|
дата-время конца графика
|
аналогично параметру since
|
-
запрос должен содержать оба параметра since и till
Пример ответа:
{
"data": [
{
"value": "14805.400085",
"timestamp": "2022-12-20T00:00:17.0Z"
}
],
"legend": {
"units": "кВтч",
"title": "Энергия активная прямая со сброса (показания)"
}
}
запрос: /entek/api/stations
Ответ содержит в себе список всех баз данных станций.
Пример ответа:
{
"stations": [
{
"name": "WEB SCADA SRV",
"id": 1,
"dbs": [
{
"dbname": "Новая БД 1",
"fileName": "/home/db/kdb.fdb",
"serverName": "localhost"
},
{
"dbname": "Новая БД 2",
"fileName": "/home/db/kdb2.fdb",
"serverName": "localhost"
}
]
}
]
}
запрос: entek/api/saving-params/<идентификатор>
Пример ответа:
{
"params": [
{
"dbname": "Новая БД 1",
"paramCode": "EnLogic.St1.T222.Grp0.Id271",
"paramId": 1
},
{
"dbname": "Новая БД 1",
"paramCode": "EnLogic.St1.T222.Grp0.Id272",
"paramId": 2
}
]
}
запрос: entek/api/signal/<канал>?<параметр>=<значение_1>,...
Формат кода: EnLogic.St<номер станции>.T<тип параметра>.Grp<номер группы>.Id<номер параметра>.
Для запроса нескольких параметров формат запроса будет без номера параметра: EnLogic.St<номер станции>.T<тип параметра>.Grp<номер группы>.
Вместо этого необходимые идентификаторы передаются в параметрах запроса в переменной ids разделенные ';' (ids=1;2;3.). При этом не будет использовано прореживание точек.
|
имя параметра
|
описание
|
допустимые значения
|
|
since
|
дата-время начал запрашиваемых данных
|
дата-время в формате ISO8601. Если присутствует только параметр date, запрашиваются данные с указанного момента времени до конца суток. Если присутствует только параметр till, запрашиваются данные с начала суток до указанного момента времени. Если отсутствуют оба параметра, выполняется запрос с параметром till, равным текущему моменту времени. Допускается указание только времени (начиная с 'T'), в этом случае дата
считается равной текущей (если дата отсутствует в обоих параметрах) либо равной дате, указанной явно в одном из параметров
|
|
till
|
дата-время конца запрашиваемых данных
|
аналогично параметру since
|
|
point
|
количество требуемых записей
|
При передачи параметра запрашиваемый интервал разбивается на малые и на каждом производится поиск максимального и
минимального значения. Если параметр не передавать, то будет возвращено количество записей ограниченное лимитом
|
|
utс
|
сдвиг времени относительно нулевого меридиана
|
вещественное число в диапазоне -12...+12, определяет часовой пояс времени, указанного в параметрах date и till; если utc равен 0, в запросе и ответе сервера используется единое время UTC; если параметр utc отсутствует, в запросе и ответе используется часовой пояс, указанный в конфигурационном файле.
|
|
ids
|
идентификаторы параметров
|
целое положительное число, перечисляются через ';'
|
Пример ответа с одним параметром:
{
"data": [
{
"v": 7054.796875,
"t": "2023-01-09T08:28:58.990Z",
"q": 255
},
{
"v": 7054.796875,
"t": "2023-01-09T08:28:59.0Z"
},
{
"v": 7126.419434,
"t": "2023-01-09T08:29:09.0Z"
},
{
"v": 7271.118652,
"t": "2023-01-09T08:29:20.0Z"
}
]
}
Пример ответа с несколькими параметрами:
{
"params": [
{
"channel": "EnLogic.St0.T222.Grp0.Id61",
"data": [
{
"t": "2024-10-11T08:39:58.9",
"v": 0.519001
},
{
"t": "2024-10-11T08:39:59.0",
"v": 3.563999
},
{
"t": "2024-10-11T08:40:00.0",
"v": 6.575998
}
]
},
{
"channel": "EnLogic.St0.T222.Grp0.Id63",
"data": [
{
"q": 255,
"t": "2024-10-11T08:39:15.990",
"v": 0
},
{
"q": 43,
"t": "2024-10-11T08:39:46.12",
"v": 0
},
{
"t": "2024-10-11T08:39:47.0",
"v": 0.5015
}
]
}
]
}
q это quality — признак качества, может принимать следующие значения:
-
0 — достоверное значение в нормальном диапазоне.
-
1, 2, 3, 4 — достоверное значение в диапазонах выхода за границы аварийных и предаварийных уставок
Если значение q < 5, то оно достоверное, если q >=5 — такое значение недостоверное.
запрос: /entek/api/events/config
GET запрос для получения содержания файла KEvents.json из проекта.
запрос: /entek/api/events/groups
GET запрос, в ответе на который передается список всех категорий и групп событий.
Пример ответа:
{
"categories": [
{
"name": "Сервер",
"BkColor": "#050000",
"Font": {
"Italic": false,
"Bold": false,
"Underline": false,
"Color": "#080000"
},
"groups": [
{
"name": "STARTSTOPGROUP",
"descrp": "СДД - запуск/останов",
"BkColor": "#ff8080",
"Font": {
"Italic": false,
"Bold": false,
"Underline": false,
"Color": "#080000"
}
},
{
"name": "DASERVERGROUP",
"descrp": "СДД - лог работы",
"BkColor": "#050000",
"Font": {
"Italic": false,
"Bold": false,
"Underline": false,
"Color": "#080000"
}
},
{
"name": "ENLOGICMNGR-IEC",
"descrp": "Библиотека EnLogicMngr - ПУ МЭК",
"BkColor": "#050000",
"Font": {
"Italic": false,
"Bold": true,
"Underline": false,
"Color": "#000080"
}
}
]
}
]
}
запрос: entek/api/events/<идентификатор>?<параметр>=<значение_1>,...
GET запрос для получения событий по названию группы событий.
В качестве идентификатора в строке запроса передается название группы событий, которое содержится в ответе на запрос всех групп событий.
Также в запросе передаются query-параметры:
|
имя параметра
|
описание
|
|
date
|
время начала интервала запрашиваемых данных
|
|
till
|
время окончания интервала запрашиваемых данных
|
Пример ответа:
{
"events": [
{
"groupId": 3,
"eventTimestamp": "2022-12-21T11:11:46.778Z",
"eventText": "Запуск модуля настройки баз данных технологических параметров",
"number": 710,
"userName": "admin",
"eventType": 0
},
{
"groupId": 3,
"eventTimestamp": "2022-12-21T11:11:52.213Z",
"eventText": "Закрытие модуля настройки баз данных технологических параметров",
"number": 711,
"userName": "admin",
"eventType": 0
}
]
}
запрос: /entek/api/events_filtered
Запрос для получения событий по фильтрам, которые передаются в теле запроса в формате JSON. Тело запроса может содержать следующие параметры:
|
параметр
|
назначение
|
приоритет
|
|
db_guids
|
guid БД, из которой будут запрашиваться события
|
при отсутствии параметра или указании неверного guid данные берутся из БД назначенной по умолчанию
|
|
groups
|
массив с названиями групп событий
|
обязательно задать
|
|
station_id
|
номер станции
|
необязательный параметр
|
|
controllers
|
массив целочисленных идентификаторов контроллеров
|
необязательный параметр
|
|
time_begin
|
время начала запрашиваемого интервала
|
при отсутствии интервала задать last_evt_count
|
|
time_end
|
время окончания запрашиваемого интервала
|
при отсутствии интервала задать last_evt_count
|
|
last_evt_count
|
количество последних событий
|
необязательный параметр
|
|
sort_mode_asc
|
логический параметр использования сортировки
|
необязательный параметр
|
|
actual_alarms
|
логический параметр передачи актуальных алармов
|
необязательный параметр
|
|
filters
|
массив идентификаторов пользовательских фильтров из БД параметров
|
необязательный параметр
|
|
columns
|
список названий стандартных полей, которые должны содержаться в ответе
|
При отсутствии параметра предаются все допустимые параметры
|
|
attr_columns
|
идентификаторы аттрибутов из БД параметров
|
необязательный параметр
|
|
evt_types
|
массив целочисленных идентификаторов типов событий
|
необязательный параметр
|
Допустимые значения для параметра columns и их соответствие полям БД:
group_name -> from GROUP_ID JOIN GROUP_LIST.GROUP_NAME client_id -> CLIENT_ID
event_time -> EVENT_DATE_UTC + EVENT_TIME_UTC event_text -> EVENT_TEXT
event_number -> NUMBER
event_type -> EVENT_TYPE
comment -> COMMNENTS
user -> USER_NAME
station_id -> STATIONID
group_id -> GROUPID
passp_type -> PASSPTYPE
passp_id -> PASSPID
passp_time -> PASSPTIME
passp_val -> ALARM_VAL
alarm_priority -> ALARM_PRIORITY
alarm_ack -> ALARM_ACK
alarm_ack_user -> ALARM_ACK_USER
alarm_ack_time -> ALARM_ACK_TIME
alarm_end_time -> ALARM_END_TIME
alarm_set_val -> ALARM_SETTINGS_VALUE
passp_cipher -> DB Params или из xml конфигурации
passp_name -> DB Params или из xml конфигурации
object_name -> DB Params или из xml конфигурации
Ответ содержит параметр events, в котором передается массив с событиями.
Также может содержаться параметр params, в котором передается массив с описанием параметров, заданными полями passp_cipher, passp_name, object_name и значения переданных атрибутов, название переменных атрибутов имеет форму "attr_<идентификатор атрибута>".
Примеры тела запроса:
{
"db_guids": ["1111"],
"groups": ["ALARMSMEDIUMHIGH", "DASERVERGROUP"],
"station_id": 0,
"controllers": [0],
"time_begin": "2023-12-29T00:00:00.000Z",
"time_end": "2023-12-29T17:00:00.000Z"
}
{
"db_guids": ["1111"],
"groups": ["ALARMSMEDIUMHIGH", "DASERVERGROUP"],
"station_id": 0,
"controllers": [0],
"last_evt_count": 10,
"columns": ["group_name", "event_time", "event_text"]
}
Пример ответов:
{
"events": [
{
"group_name": "DASERVERGROUP",
"event_time": "2024-01-09T06:01:32",
"event_text": "StopMessagesAntraks",
"event_number": "701",
"event_type": "0",
"station_id": "0",
"passp_type": "222",
"group_id": "0",
"passp_id": "0"
},
{
"group_name": "DASERVERGROUP",
"event_time": "2024-01-09T06:01:32",
"event_text": "RTP - SUCCESSFULLY call STOPPROCESS",
"event_number": "696",
"event_type": "0",
"station_id": "0",
"passp_type": "222",
"group_id": "0",
"passp_id": "0"
}
]
}
{
"events": [
{
"event_time": "2023-12-29T11:50:58",
"event_text": "Переключение аларм выше среднего - Отключено",
"passp_time": "2023-12-29T11:50:58"
},
{
"event_time": "2023-12-29T11:50:50",
"event_text": "Переключение аларм выше среднего - Включено",
"passp_time": "2023-12-29T11:50:50"
}
],
"params": [
{
"station_id": 0,
"group_id": 0,
"passp_id": 4,
"passp_type": 2,
"passp_cipher": "ТС аларм выше среднего",
"object_name": "Генератор демо-данных",
"passp_name": "Генератор демо-данных.Задача 1.Для тестирования алармов.ТС аларм выше среднего",
"attr_1": "Тестовое значение"
}
]
}
запрос: entek/api/params_db/param_info
Запрос для получения информации о параметре из БД параметров. Необходимо передать тело, которе будет перенаправлено в EVP для получения структуры адреса параметра и последующей запросе в БД для получения информации. При успешном запросе ответ содержит параметр infoCode равный 0, иначе - 1 и присутствует параметр infoString с описанием ошибки.
Пример ответа:
{
"infoCode": 0,
"station_name": "local",
"group_name": "group",
"full_path": "path",
"value_type": 0,
"param_type": 1,
"cipher": "cipher",
"name": "name",
"unit": "kVt",
"vpu": "90",
"npu": "10",
"vau": "80",
"nau": "20",
"up_border": "100",
"down_border": "0",
"user_attr_list": [
{
"name": "name",
"value": "value"
}
]
}
запрос: entek/api/params_db/update_setpoints
Запрос для обновления уставок параметра. Необходимо передать тело, которе будет перенаправлено в EVP для обновления уставок. При успешном запросе ответ содержит параметр infoCode равный 0, иначе - 1 и присутствует параметр infoString с описанием ошибки. Также для записи уставок пользователю необходимы права для аналогового управления.
Пример ответа:
{
"infoCode": 0
}
запрос: entek/api/params_db/attr_name/<_id>
Запрос для получения имени пользовательского атрибута. В качестве _id передается идентификатор атрибута.
Пример ответа:
{
"attr_name": "Пользовательский атр"
}
запрос: entek/api/params_db/user_tree
Запрос для получения пользовательского дерева для дальнейшей работы с фильтрами.
Пример ответа:
[
{
"id": 1,
"name": "Корень",
"filter": false
},
{
"id": 5,
"name": "фывф",
"filter": false,
"items": [
{
"id": 6,
"name": "ааааа",
"filter": false,
"items": [
{
"id": 2,
"name": "Контроллер 0",
"filter": true
},
{
"id": 3,
"name": "Контроллер 3",
"filter": true
}
]
},
{
"id": 4,
"name": "РЗА",
"filter": true
}
]
}
]
запрос: entek/api/dcontrol?level=<num>
Запрос для дискретного управления, передается с параметром level - уровень управления. Для выполнения команды у пользователя должны быть права для дискретного управления необходимого уровня.
При успешном запросе ответ содержит параметр infoCode равный 0, иначе - 1 и присутствует параметр infoString с описанием ошибки.
Пример ответа:
{
"infoCode": 1,
"infoString": "Управление не разрешено"
}
запрос: entek/api/acontrol
Запрос для аналогового управления. Для выполнения команды у пользователя должны быть права для аналогового управления.
При успешном запросе ответ содержит параметр infoCode равный 0, иначе - 1 и присутствует параметр infoString с описанием ошибки.
Пример ответа:
{
"infoCode": 0
}
запрос: entek/api/alarms/config/priority/
Запрос для получения информации о настройке алармов по их приоритету, который передается последним значением в запросе (num). В переменной sound_data содержится звуковой файл в кодировке Base64.
Пример ответа:
{
"sound_type": 2,
"sound_name": "alarm_001.wav",
"sound_data": "data",
"sound_repeat": 10,
"sound_pause": 10,
"back_color": "#808080"
}
запрос: entek/api/alarms/ack_all
Запрос для квитирования всех алармов, который должен содержать тело для дальнейшей передачи в EVP. При успешном запросе ответ содержит параметр infoCode равный 0, иначе - 1 и присутствует параметр infoString с описанием ошибки.
Пример ответа:
{
"infoCode": 0
}
запрос: entek/api/image/<image_name>
Запрос для получения изображений из папки проекта, название изображение передается последним параметром в запросе. Поиск производится в папке KVision/Images, если там нет, то в KVision/Animate. В ответе передается файл в кодировке Base64 и его название.
Пример ответа:
{
"file_name": "001.jpeg",
"data": "data"
}
запрос: entek/api/sign/get_list
Запрос для получения всех плакатов из папки проекта. Анализ производится в в файле KVision/Signs/Signs.xml. Ответ передается массивом в переменной signList, если файл не найден или плакатов нет, то массив будет пустой.
Пример ответа:
{
"signList": [
{
"autoSize": true,
"fileName": "Rabota_Na_Linii.bmp",
"highPriority": true,
"id": "{B0D20A30-E99F-4BC1-B1C0-714C41CE7E98}",
"name": "1. Работа на линии",
"transp": false
},
{
"autoSize": true,
"fileName": "Rabotaut_Ludi.bmp",
"id": "{DFFA5C19-5C13-472F-8456-00910DC5EC1F}",
"name": "2. Работают люди",
"transp": false
}
]
}
запрос: entek/api/sign/get_image
Запрос для получения изображений из папки проекта по идентификатору плаката, который передается в теле запроса в переменной sign_id.
Поиск производится в папке KVision/Signs. В ответе передается файл в кодировке Base64 и идентификатор плаката.
Пример запроса:
{
"sign_id": "{B0D20A30-E99F-4BC1-B1C0-714C41CE7E98}"
}
Пример ответа:
{
"sign_id": "{B0D20A30-E99F-4BC1-B1C0-714C41CE7E98}",
"data":"<файл в кодировке Base64>"
}
запросы:
-
entek/api/sign/act_add
-
entek/api/sign/act_update
-
entek/api/sign/act_delete
Запросы предназначены для добавления, редактирования и удаления плакатов, которые должен содержать тело для дальнейшей передачи в EVP. При успешном запросе ответ содержит параметр infoCode равный 0, иначе - 1 и присутствует параметр infoString с описанием ошибки. Для данных запросов пользователь должен быть с правами администратора или иметь разрешение на работу с плакатами, которое можно установить в модуле Пользователи.
Пример ответа:
{
"infoCode": 1,
"infoString": "Добавление плаката не разрешено"
}
Для интеграции с сервисом NGW необходимо добавить конфигурационный файл ngwConfig.json в корень проекта в папку Dispatcher. Данные используются для синхронизации данных между базой данных проекта SCADA-ЭНТЕК и сервисом NGW, а также для отображения HTML форм.
Файл содержит следующие настройки:
-
ngwUrl - адрес для подключения к NGW
-
ngwUser/ngwPassword - параметры для подключения
-
attrTableWidth/valTableWidth - ширина столбцов для отображения таблицы
-
journals - массив с настройками журналов
Настройки журналов состоят из следующих полей:
-
info - название журнала
-
jrnlId - идентификатор журнала
-
gisIdFieldI - поле в журнале, которе содержит идентификатор NGW
-
objectNameFieldId - поле с названием записей в журнале
-
ngwWebMapId - идентификатор карты в NGW
-
ngwLayerId - идентификатор слоя в NGW
-
ngwGisIdFieldName - название поля GisId в NGW
-
ngwDispLinkField - поле в NGW для записи ссылки на информацию из базы данных
{
"ngwUrl": "",
"ngwUser": "",
"ngwPassword": "",
"attrTableWidth": 300,
"valTableWidth": 400,
"journals": [
{
"info" : "Объекты",
"jrnlId": 49,
"gisIdFieldId": 193,
"objectNameFieldId": 1,
"ngwWebMapId": 20,
"ngwLayerId": 185,
"ngwGisIdFieldName": "sid",
"ngwDispLinkField": "surl"
}
]
}
запрос: entek/api/ngw/config
Запрос возвращает HTML страницу со списком журналов (идентификатор и название), указанных в конфигурационном файле, а также их общее количество.
запрос: entek/api/ngw/journal/<journalId>
Запрос передается с идентификатором журнала и возвращает HTML страницу, которая отображает название журнала и таблицу с настройками из ngwConfig.json файла.
запрос: entek/api/ngw/sync/<journalId>
Запрос передается с идентификатором журнала. В процессе работы обновляются записи в NGW, добавляя к ним ссылки на информацию о записях в базе данных. По ходу выполнения будет отображаться результат синхронизации.
запрос: entek/api/dsp/<docId>/<objectId>
Запрос передается с идентификатором журнала и идентификатором объекта. Возвращает HTML страницу, которая отображает название записи и таблицу со всеми атрибутами и их значениями. А также ссылки на список зависимостей в других журналах и список файлов доступных к загрузке.
Для запроса по уникальному полю вместо objectId необходимо указать unique_field, а затем в параметрах запроса передать значение поля в переменной value. Поле, по которому будет производиться поиск, указывается в переменной gisIdFieldId в настройках журнала в конфигурационном файле ngwConfig.json. Значения уникальных полей не должны содержать кириллицы. Пример запроса: entek/api/dsp/<docId>/unique_field?value=<value>
запрос: entek/api/ngw/multilinks/<objectId>/<refToField>
Запрос передается идентификатором журнала и идентификатором на ссылаемое поле. Возвращает HTML страницу, которая отображает список связанных записей и название журнала, к которому они относятся.
запрос: entek/api/ngw/download/<fileId>
Запрос передается идентификатором файла и возвращает файл в байтовом предоставлении.
запрос: /entek/api/report/history
Запрос предназначен для формирования отчетов в фромате html из шаблона. Запрос должен содержать обязательные параметры запроса:
-
start_time - начало интервала отчета
-
end_time - конец интервала отчета
-
temp - полный путь до файла шаблона с расширением html
Шаблон должен быть валидным xml файлом, т.е. все открывающие ноды должны быть закрыты. Генерация данных происходит в элементе таблицы, вне этого элемента доступно два параметра начало и конец интервала отчета, которые можно указать подставив в текст переменные {@timeStart} и {@timeEnd} соответственно.
<br>Report interval from {@timeStart} to {@timeEnd}</br>
Таблица должна содержать два элемента thead для заголовка таблицы и tbody для тела, в котором будут генерироваться данные, также есть обязательный блок scada с настройками таблицы. В ноде scada указываются параметры, которые будут запрашиваться в базе данных, а также тип отчета, шаг, с которым отображаются данные, и количество знаков после запятой.
Атрибуты доступные для ноды scada:
-
type - тип отчета. Доступные значения: values - отчет из базы данных истории
-
step - шаг запроса данных. Доступные значения: указывается число секунды или минут, а после числа указывается s/sec или m/min соответственно.
-
decimal - количесвто знаков после запятой у значений, которые будут генерироваться.
Внутри ноды scada перечисляются параметры в нодах value с обязательными атрибутами name - пользовательское наименование переменной, которое будет подставляться в теле таблицы; addr - код параметра для запросов к базе данныъ. Также для параметров опционально можно задать доступные алгоритмы для обработки данных (sum - сумма, average-sum - среднее значение), для них предусмотрен атрибут algorithm, в котором можно перечислить, разделяя строго только запятой, все нобходимые алгоритмы для каждого параметра.
Пример ноды scada:
<scada type="values" step="1m" decimal="3">
<value name="V1P" addr="EnLogic.St0.T222.Grp0.Id91"></value>
<value name="V1Q" addr="EnLogic.St0.T222.Grp0.Id92" algorithm="sum,average- sum"></value>
<value name="V1I" addr="EnLogic.St0.T222.Grp0.Id93" algorithm="average-sum"> </value>
</scada>
Внутри ноды tbody в ноде tr с атрибутом gen="true" указываются параметры, которые будут генерироваться. Параметры указываются в фигурных скобках и перед пользовательским названием ставится символ @ (Пример: {@V1P}). Также достуны функция формирования метки интервала, для этого указывается переменная timestamp, а через точку указывается тип временной метки Date - для даты, Time - для времени, если ничего не указать то формат будет содержать дату и время. Функция genNum предназначена для подстановки номера строки таблицы.
А для вызова результата алгоритма в таблице надо указать его название из атрибута name и через точку указать название алгоритма (доступно только для статических строк без атрибута gen="true").
Пример ноды tbody:
<tbody>
<tr gen="true">
<td>{@timestamp.Date}</td>
<td>{@timestamp.Time}</td>
<td>{@V1P}</td>
<td>{@V1Q}</td>
<td>{@V1I}</td>
</tr>
</tbody>
Пример использования алгоритма в сроке таблицы:
<tr>
<td>Average</td>
<td></td>
<td></td>
<td>{@V1Q.average-sum}</td>
<td>{@V1I.average-sum}</td> </tr>
Пример полного шаблона отчета:
<html>
<body>
<br>SCADA report</br>
<br>from {@timeStart} to {@timeEnd}</br>
<table id="table1" cols="23" border="1" cellspacing="0" cellpadding="2" width="100%%">
<scada type="values" step="1m" decimal="3">
<value name="V1P" addr="EnLogic.St0.T222.Grp0.Id91"></value>
<value name="V1Q" addr="EnLogic.St0.T222.Grp0.Id92" algorithm="sum,average-sum"></value>
<value name="V1I" addr="EnLogic.St0.T222.Grp0.Id93" algorithm="average-sum"></value>
</scada>
<thead>
<tr align="center">
<th>Num</th>
<th>Date</th>
<th>Time</th>
<th>Q, kVA</th>
<th>I, A</th>
</tr>
</thead>
<tbody>
<tr gen="true">
<td>{@genNum}</td>
<td>{@timestamp.Date}</td>
<td>{@timestamp.Time}</td>
<td>{@V1P}</td>
<td>{@V1Q}</td>
<td>{@V1I}</td>
</tr>
<tr>
<td>Total</td>
<td></td>
<td></td>
<td>{@V1Q.sum}</td>
<td></td>
</tr>
<tr>
<td>Average</td>
<td></td>
<td></td>
<td>{@V1Q.average-sum}</td>
<td>{@V1I.average-sum}</td>
</tr>
</tbody>
</table>
</body>
</html>