WEB OPC HTTP API
ВВЕДЕНИЕ
Данное API позволяет получить доступ к данными диспетчеризации, циркулирующим в ПО АСУД.SCADA, посредством выполнения запросов по HTTP(S) протоколу к специализированному WEB-сервису.
WEB-сервис реализован в приложении .. \ tools-server \ opcconnector.exe
По-сути API является OPC-HTTP шлюзом для OPC DA - сервера.
Если вам необходим доступ к данным подсистемы учета ресурсов смотри WEB REST API
История версий:
21-10-2024
- Добавлен вызов ServerInformation
- Добавлен параметр readID в вызовы GetUpdates
03-05-2024
- Добавлены вызов, не требующий открытия сессии
- ZabbixNS
27-03-2024
- Обновление API
- Возможность подключение к любому OPC DA серверу (не только к Tekon OPC DA).
ОБЩИЕ СВЕДЕНИЯ
Взаимодействие реализуется по следующей схеме:
- открытие сессии
- получение адресного пространства OPC-сервера (не обязательно)
- подписка на обновление определенных элементов адресного пространства
- периодическая проверка обновлений данных в подписке
- выборочное чтение значений элементов
- выборочная запись новых значений элементов
- закрытие сессии
Активная сессия будет автоматически закрыта сервером в случае отстуствия запросов со стороны клиента в течение пяти минут.
В текущей версии API-не реализует callback-механизма. Для получения обновлений в подписке, клиент должен выполнять периодические запросы к серверу.
ДОСТУП К ДАННЫМ
Доступ осуществляется с помощью HTTP-запросов: GET и POST.
Признаком кооректной обработки запроса является HTTP Responce status code = 200
Коды ошибок WEB-сервиса
В случае ошибки обоработки запроса, WEB-сервис формирует следующие коды ошибок
| HTTP Responce status code | Описание ошибки | Комментарий |
|---|---|---|
| 400 | В запросе не указан идентификатор сессии | |
| 403 | Соединение с данного IP-адреса запрещено | Список допустимых IP-адресов может быть указан в настройках WEB-сервиса |
| 404 | Запрашиваемый ресурс не найден |
|
| 409 | Указанный идентификатор сессии не найден | Следует переоткрыть сессию |
| 415 | В запросе должны быть, но отсутствуют даннные, передаваемые методом POST | |
| 503 | OPC-сервер не доступен |
Вероятно осуществляется перезапуск OPC-сервера Следует выполнить переоткрытие сессии и заново оформить подписку на элементы |
Специальные запросы, не требующие открытия сессии
Несколько запросов, которые можно выполнять без открытия сессии.
ServerInformation
(доступно в версии API 2.0)
GET http://host:port/ServerInformation
В ответ будет получена информация о текущей версии сервера
{"starttime":"21.10.2024 14:42:35","currenttime":"22.10.2024 11:47:08","version":"2.0"}
Zabbix
GET http://host:port/Zabbix
В ответ будет получен массив текущих состояний статусов всех подключенных устройств.
Ответ: json следующего вида
[
{
"UpTime": "2024-05-02 10:36:06",
"V": "10",
"ItemName": "OPC шлюз.OPC HTTP - 0.КУН-IP4 - 0.Status",
"Qual": 192
},{
"UpTime": "2024-05-02 10:36:06",
"V": "10",
"ItemName": "OPC шлюз.OPC HTTP - 0.КУН-IP8 - 2.Status",
"Qual": 192
}
]
Если устройство опрашивается нормально, параметр Qual = 192 и V > 0.
Следует отметить, что максимальное значение параметра V разное для разных типов устройств.
Запрос открытия сессии - NewSession
Это первый запрос, который следует выполнять при подключении к серверу.
GET http://host:port/NewSession?alldata=0
, где
- alldata - определяет механизм обновления данных в подписке
- 0 - обычно, предоставлять только последнее обновление значения элемента между запросами обновления данных
- 1 - предоставлять все изменения значений элемента между двумя запросами обновления данных
Ответ: json следующего вида
{"sessionid":"22339217-FEF1-45B4-BB59-70177BB2997A"}
Запрос адресного пространства OPC-сервера - GetAddressSpace
GET http://host:port/GetAddressSpace?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A
, где
- sessionid - идентификатор сессии полученный в ответ на запрос открытия сессии
Ответ: json-массив следующего вида
[
{
"ItemProps": [
{
"Datatype": 18,
"ID": 1,
"Value": "19",
"Error": 0,
"Desc": "Тип данных"
},{
"Datatype": 19,
"ID": 5,
"Value": "3",
"Error": 0,
"Desc": "Права доступа"
}],
"ItemID": 0,
"ItemName": "DBMonitoring.ConnectFailDevices"
},{
"ItemProps": [
{
"Datatype": 18,
"ID": 1,
"Value": "19",
"Error": 0,
"Desc": "Тип данных"
},{
"Datatype": 19,
"ID": 5,
"Value": "3",
"Error": 0,
"Desc": "Права доступа"
}],
"ItemID": 1,
"ItemName": "DBMonitoring.KIR_BatteryFail"
}]
, где:
- ItemProps - набор свойств элемента Tekon OPC-сервера
- ItemID - идентификатор элемента. Используется далее при обмене данным с сервером
- ItemName - имя элемента
Если конфигурация Tekon OPC-сервера не изменяется, на запрос адресного пространства приходит один и тот же ответ.
Однако, если в Tekon OPC-сервере появятся новые элементы, например: в результате регистрации нового оборудования, то идентификация его элементов может измениться. Это следует учитывать при подписке на обновления данных.
Tekon OPC-сервер не использует функционал обновления свойств элементов. Обновленяются только значения элементов.
Анализ элементов адресного пространства.
| ID | Описание | Комментарий |
| 1 | Определяет OleVariant тип значения элемента | например: Value = 19 соответсвует значению vt_ui4, беззнаковый целый 4 байтный |
| 3 | Права доступа к элементу | read = 1 write = 2 read / write = 3 |
| 5001 | Тип данных, которые хранит элемент |
подробнее см. далее |
| 5003 | Комментарий | строка |
| 6000 | IP-адрес устройства | строка |
| 6001 | Адрес установки оборудования | строка |
| 7000 | Категория описания неисправности | строка |
| 7001 | Описание неисправности | строка. Определяет за что конкретно отвечает этот элемент |
Возможные типы данных, которые хранит элемент
| Тип | Описание | Коментарий |
| 3000 | Дискретный сигнал |
Для интерпретации следует анализировать младший бит значения: Подробнее см. Дискретный сигнал (OPC-сервер) |
| 3001 | Канал переговорной связи |
Для интерпретации следует анализировать младший бит значения: Для инициализации вызова со стороны АРМ, следует записать значение 1. |
| 3002 | Канал управления |
Для интерпретации следует анализировать младший бит значения: Для включения / выключения канала со стороны АРМ, следует записать: |
| 3060 | Числовое значение | Любое числовое значение |
| 3061 | Строка | Любая строка |
| 3070 | Состояние лифта |
Информация о состоянии лифта, представляет собой xml следующего вида:
|
Запрос закрытия сессии - CloseSession
Не обязательный запрос. Все "забытые" сессии, автоматически закроются сервером.
GET http://host:port/CloseSession?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A
Ответ: json следующего вида
{"result":"ok"}
Запрос подписки на обновление данных - Subscriber
POST http://host:port/Subscriber?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A
, где
- sessionid - идентификатор сессии полученный в ответ на запрос открытия сессии
В POST запросе также передается массив идентификаторов элементов ItemIndex адресного пространства, на обновление данных которых необходимо подписаться, например:
{"items":[0,1,2,3,4,5,6,7,8,9]}
Ответ: json следующего вида
{"result":10}
, где
- result - число элементов, которые были добавлены в подписку
Для добавления элементов в подписку следует повторно выполнить запрос с указанием новых (добавляемых) идентификаторов элементов.
Запрос числа элементов в подписке - SubscriberCount
GET http://host:port/SubscriberCount?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A
, где
- sessionid - идентификатор сессии полученный в ответ на запрос открытия сессии
Ответ: json следующего вида
{"result":10}
, где
- result - число элементов, которые были добавлены в подписку
Запрос Id элементов в подписке - SubscribersIdList
GET http://host:port/SubscribersIdList?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A
, где
- sessionid - идентификатор сессии полученный в ответ на запрос открытия сессии
Ответ: json следующего вида
{"items":[6,20,18,22,16,21,15,17,8,9,24,10,5,23,19,7,14,13,11,12]}
, где
- items - массив идентификаторов элементов, которые были добавлены в подписку
Запрос имен элементов в подписке - SubscribersTextList
GET http://host:port/SubscribersTextList?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A
, где
- sessionid - идентификатор сессии полученный в ответ на запрос открытия сессии
Ответ: json следующего вида
{"itemstext":["numeric.saw.int8","numeric.sin.int32","numeric.sin.int16","numeric.sin.int64","numeric.sin.int8","numeric.sin.uint64","numeric.sin.uint8","numeric.sin.uint16","numeric.saw.int16","numeric.saw.uint32","numeric.sin.double","numeric.saw.int32","numeric.saw.uint8","numeric.sin.float","numeric.sin.uint32","numeric.saw.uint16","numeric.saw.double","numeric.saw.float","numeric.saw.uint64","numeric.saw.int64"]}
, где
- itemstext - массив имен элементов, которые были добавлены в подписку
Запрос элементов в подписке - SubscribersText
GET http://host:port/SubscriberTextList?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A
, где
- sessionid - идентификатор сессии полученный в ответ на запрос открытия сессии
Ответ:text/plain следующего вида
ItemID1. Имя элемента 1 ItemID2. Имя элемента 2 ...
, где
- ItemID- ID элемента
- Имя элемента - имя Item в адресном пространстве OPC-сервера
Запрос отмены подписки на обновление данных - UnSubscriber
POST http://host:port/UnSubscriber?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A
, где
- sessionid - идентификатор сессии полученный в ответ на запрос открытия сессии
В POST запросе также передается массив идентификаторов элементов ItemIndex адресного пространства, на обновление данных которых следует отписаться, например:
{"items":[0,1,2,3,4,5,6,7,8,9]}
Ответ: json следующего вида
{"result":10}
, где
- result - число элементов, подписка на которые была отменена
Запрос проверки новых данных в подписке - GetUpdates
Запрос следует выполнять периодически, для полученя новых данных, на которые ранее была выполнена подписка .
В ответе присуствуют только те данные, которые обновились с момента предыдущего запроса.
GET http://host:port/GetUpdates?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A&rid=1
, где
- rid (параметр введен в API 2.0) - целое число, идентификатор транзации чтения, должен увеличиваться после каждого удачного запроса
Ответ: json-массив
[{
"UpTime": "2023-04-28 17:54:55",
"V": "0",
"ItemID": 3,
"Qual": 192
}]
, где
- UpTime - время обновления
- V - значение элемента
- ItemID - идентификатор элемента, который был указан в подписке
- Qual - качество значения
- 192 - значение валидно
- любое другое - значение не валидно
Возможные значения параметра Qual:
- DA_QUALITY_UNCKNOWN = 0x0;
- DA_QUALITY_UNCERTAIN = 0x40;
- DA_QUALITY_CONFIG_ERROR = 0x4;
- DA_QUALITY_NOT_CONNECTED = 0x8;
- DA_QUALITY_DEVICE_FAILURE = 0xc;
- DA_QUALITY_SENSOR_FAILURE = 0x10;
- DA_QUALITY_LAST_KNOWN = 0x14;
- DA_QUALITY_COMM_FAILURE = 0x18;
- DA_QUALITY_OUT_OF_SERVICE = 0x1c;
- DA_QUALITY_WAITING_FOR_INITIAL_DATA = 0x20;
- DA_QUALITY_LAST_USABLE = 0x44;
- DA_QUALITY_SENSOR_CAL = 0x50;
- DA_QUALITY_EGU_EXCEEDED = 0x54;
- DA_QUALITY_SUB_NORMAL = 0x58;
- DA_QUALITY_GOOD = 0xc0;
- DA_QUALITY_LOCAL_OVERRIDE = 0xd8;
Запрос проверки новых данных в подписке - GetUpdatesText
Запрос следует выполнять периодически, например: раз в секунду, для полученя новых данных, на которые ранее была выполнена подписка .
GET http://host:port/GetUpdatesText?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A&rid=1
, где
- rid (параметр введен в API 2.0) - целое число, идентификатор транзации чтения, должен увеличиваться после каждого удачного запроса
Ответ: json-массив
[{
"UpTime": "2023-04-28 17:54:55",
"V": "0",
"ItemName": "numeric.saw.int8",
"Qual": 192
}]
, где
- UpTime - время обновления
- V - значение элемента
- ImteName - имя элемента, который был указан в подписке
- Qual - качество значения
Внимание! В ответе присуствуют только те данные, которые обновились с момента прошлого запроса.
Запрос принудительного чтения значения элемента подписки - ReadItemValue
GET http://host:port/ReadItemValue?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A&item=1
, где
- item - идентификатор элемента адресного пространства ОРС-сервера
(если элемент отсутствует в подписке, он будет в нее добавлен)
Ответ: json следующего вида
{"result":1}
, где
- result
- 0 - ошибка, некорректный идентификтор
- 1 - ok
Для получения текущего значения элемента следует выполнить Запрос проверки новых данных (GetUpdates).
Запрос принудительного чтения значения элемента подписки - ReadItemValueSync
GET http://host:port/ReadItemValueSync?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A&item=1
, где
- item - идентификатор элемента адресного пространства ОРС-сервера
Ответ: json следующего вида
[
{
"UpTime": "2024-03-27 15:11:23",
"V": "0,05",
"ItemID": 1,
"Qual": 192
}]
Запрос принудительного чтения значений всех элементов подписки - ReadAllItemsValues
GET http://host:port/ReadAllItemsValues?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A
Ответ: json следующего вида
{"result":10}
, где
- result
- 0 - ошибка, отсутствуют элементы в подписке
- > 0 - ok, будет обновлено указанное число элементов
Для получения текущих значений элементов следует выполнить Запрос проверки новых данных (GetUpdates).
Запрос записи нового значения элемента подписки - WriteItemsValues
POST http://host:port/WriteItemsValues?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A
В POST запросе также передается массив идентификаторов элементов адресного пространства OPC-сервера:
[{
"ItemID": 1,
"Value": "0"
}]
Для возможности записи значения в ItemID, необходимо чтобы он был ранее добавлен в подписку.
Ответ: json следующего вида
{"result":1}
- 1 - количество успешно обновленных элементов
