WEB OPC HTTP API
ВВЕДЕНИЕ
Данное API позволяет получить доступ к данными диспетчеризации, циркулирующим в ПО АСУД.SCADA, посредством выполнения запросов по HTTP(S) протоколу к специализированному WEB-сервису.
WEB-сервис реализован в приложении .. \ tools-server \ opcconnector.exe
По-сути API является OPC-HTTP шлюзом для OPC DA - сервера.
Если вам необходим доступ к данным подсистемы учета ресурсов смотри WEB REST API
Вы можете выполнить взаимодействие с API, даже если у вас нет реально подключенного оборудования, подробнее см. Тестовая работа с HTTP API
История версий:
05-02-2025
- Версия API 2.1
21-10-2024
- Добавлен вызов ServerInformation
- Добавлен параметр readID в вызовы GetUpdates
03-05-2024
- Добавлены вызов, не требующий открытия сессии
- Zabbix
27-03-2024
- Обновление API
- Возможность подключение к любому OPC DA серверу (не только к Tekon OPC DA).
ОБЩИЕ СВЕДЕНИЯ
Взаимодействие c Tekon OPC-сервер, используя API, реализуется, например по следующей схеме:
Без открытия сессиии
- выполнение запроса
С открытием сессиии и подпиской на обвновления данных
- открытие сессии
- получение хэша адресного пространства, сравнение хэша с полученным ранее значеним
- получение обновленного адресного пространства OPC-сервера
(или чтение локальной копии в случае совпадения хэшей) - подписка на обновление определенных элементов адресного пространства
- периодическая проверка обновлений данных в подписке
- выборочное чтение значений элементов
- выборочная запись значений элементов
- закрытие сессии
Активная сессия будет автоматически закрыта сервером в случае отстуствия запросов со стороны клиента в течение 120 секунд.
В текущей версии API-не реализует callback-механизма. Для получения обновлений в подписке, клиент должен выполнять периодические запросы к серверу.
Адресное пространство ОРС-сервера представляет собой иерархическую структуру следующего вида
Каждый канал (информационный сигнал) идентифицируется полным именем, например:
Controller1.Device1.Channel4 Controller1.Device1.Status Controller1.Status
Каждый канал, содержит набор свойств, описывающих настройки канала (подробнее описание свойств см. далее). Например:
- ID = 6001 содержит адресную информацию в текстовом виде,
- ID = 9002 регистрационную информацию, которая может быть использована для идентификации точки в сторонней информационной системе.
Каждое устройство или контроллер всегда имеют специальный канал .Status (статус или оценка), определяющий происходит ли обмен данными Tekon OPC-сервер с устройством или нет.
Если значение канала .Status = 0 и/или не валидно, то соответственно нет обмена данными, не актуальны значения всех устройств (и всех датчиков устройств), подключенных на данное устройство или контроллер.
Анализируя свойства канала Status устройства вы можете определить:
- идентификацинные данные устройства
- адрес установки
- IP-адрес
- и т.п.
Описание свойств каналов адресного пространства.
| ID | Описание | Комментарий |
| 1 | Определяет тип значения элемента | например: Value = 19 соответсвует значению vt_ui4, беззнаковый целый 4 байтный |
| 3 | Права доступа к элементу | read = 1 write = 2 read / write = 3 |
| 5001 | Тип данных, которые хранит элемент |
подробнее см. далее |
| 5003 | Комментарий | строка |
| 6000 | IP-адрес устройства | строка |
| 6001 | Адрес установки оборудования | строка |
| 6003 | Минимальное значение канала Status устройства | если отсутствует, то 0 |
| 6004 | Максимальное значение канала Status устройства | определениет максимальное значение оценки опроса |
| 7000 | Категория описания неисправности | строка |
| 7001 | Описание неисправности | строка. Определяет за что конкретно отвечает этот элемент |
| 9002 | Регистрационный номер | строка, может быть использована для внешней идентификации канала |
Возможные типы данных канала
| Тип | Описание | Коментарий |
| 3000 | Дискретный сигнал |
Для интерпретации следует анализировать младший бит значения: Подробнее см. Дискретный сигнал (OPC-сервер) |
| 3001 | Канал переговорной связи |
Для интерпретации следует анализировать младший бит значения: Для инициализации вызова со стороны АРМ, следует записать значение 1. |
| 3002 | Канал управления |
Для интерпретации следует анализировать младший бит значения: Для включения / выключения канала со стороны АРМ, следует записать: |
| 3005 | Канал статуса |
Канал присутствует у любого устройства. |
| 3060 | Числовое значение | Любое числовое значение |
| 3061 | Строка | Любая строка |
| 3070 | Состояние лифта |
Информация о состоянии лифта, представляет собой xml следующего вида:
|
ДОСТУП К ДАННЫМ
Доступ осуществляется с помощью 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"}
, где
- starttime - время запуска приложения OPCONNECTOR.EXE
- currenttime - текущее время устройства
- version - версия API
- opconn_version - версия приложения OPCONNECTOR.EXE
Zabbix
GET http://host:port/Zabbix
В ответ будет получен массив текущих состояний статусов (.Status) всех подключенных устройств.
Ответ: 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
}
]
, где
- UpTime - время последнего обновления данных
- ItemName - имя тэга Tekon OPC-сервер
- V - значение - целое число
- Qual - качество значения, в терминах стандарта OPC DA.
Если устройство опрашивается нормально, параметр 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 - набор свойств канала OPC-сервера
- ItemID - внутренний идентификатор канала. Используется далее при обмене данными с сервером
- ItemName - имя канала, имя тэга
Пример полного JSON-файла конфигурации для АРМ на базе USB-Пульта.
Если конфигурация OPC-сервера не изменяется, то на запрос адресного пространства приходит один и тот же ответ.
Поэтому при повторных запросах, можно сначала запрашивать хэш значение.
Однако, если в Tekon OPC-сервере появятся новые элементы, например:
- в результате регистрации в конфигурации нового оборудования,
- в результате обновления ПО АСУД.SCADA
то идентификация его элементов (соответствие ItemID - ItemName) может измениться. Это следует учитывать при подписке на обновления данных.
Tekon OPC-сервер не использует функционал обновления свойств каналов. Обновленяются только значения каналов.
Соответственно, если система настроена, в ОРС-сервер не добавляется нового оборудования, то его адресное пространство - неизменно.
В случае, если произойдет запуск конфигуратора ОРС-сервера в режиме настройки, OPCONNECTOR.EXE автоматически закроет все активные сессии обмена данными. Необходимо будет переоткрыть сессию и проверить адресное пространство.
Описание свойств каналов адресного пространства.
| ID | Описание | Комментарий |
| 1 | Определяет тип значения элемента | например: Value = 19 соответсвует значению vt_ui4, беззнаковый целый 4 байтный |
| 3 | Права доступа к элементу | read = 1 write = 2 read / write = 3 |
| 5001 | Тип данных, которые хранит элемент |
подробнее см. далее |
| 5003 | Комментарий | строка |
| 6000 | IP-адрес устройства | строка |
| 6001 | Адрес установки оборудования | строка |
| 6003 | Минимальное значение канала Status устройства | если отсутствует, то 0 |
| 6004 | Максимальное значение канала Status устройства | определениет максимальное значение оценки опроса |
| 7000 | Категория описания неисправности | строка |
| 7001 | Описание неисправности | строка. Определяет за что конкретно отвечает этот элемент |
| 9002 | Регистрационный номер | строка, может быть использована для внешней идентификации канала |
Возможные типы данных канала
| Тип | Описание | Коментарий |
| 3000 | Дискретный сигнал |
Для интерпретации следует анализировать младший бит значения: Подробнее см. Дискретный сигнал (OPC-сервер) |
| 3001 | Канал переговорной связи |
Для интерпретации следует анализировать младший бит значения: Для инициализации вызова со стороны АРМ, следует записать значение 1. |
| 3002 | Канал управления |
Для интерпретации следует анализировать младший бит значения: Для включения / выключения канала со стороны АРМ, следует записать: |
| 3005 | Канал статуса |
Канал присутствует у любого устройства. |
| 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 - количество успешно обновленных элементов
