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
• Добавлены пояснения по взаимодействию с OPC-сервером
• Добавлены xxxText функции, позволяющие осуществить подписку по ItemName (вместо ItemID)

21-10-2024

• Добавлен вызов ServerInformation
• Добавлен параметр readID в вызовы GetUpdates

03-05-2024

• Добавлены вызов, не требующий открытия сессии
  • Zabbix

27-03-2024

• Обновление API
• Возможность подключение к любому OPC DA серверу (не только к Tekon OPC DA). 

ОБЩИЕ СВЕДЕНИЯ

Для идентификации сигналов системы диспетчеризации, необходимо получить и проанализровать адресное пространство Tekon OPC-сервер

Адресное пространство представляет собой иерархическую структуру, состояющую из: контроллеров / устройств, оконечных датчиков,  следующего вида

Opchttp space.PNG

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

Каждый канал характеризуется:

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

Текущее значение содержит:

• в явном виде значение измеряемой величины
  • тип значения (число, строка, массив и т.п.), определяется в свойствах канала
• признак качества / валидности значения (Qual) - в терминах OPC DA

Если значение корректное, 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;

Каждое устройство или контроллер всегда имеют специальный канал  .Status (статус или оценка), определяющий происходит ли обмен данными Tekon OPC-сервер с устройством или нет.
Если значение канала .Status = 0 и/или не валидно, то соответственно нет обмена данными, не актуальны значения всех устройств (и всех датчиков устройств), подключенных на данное устройство или контроллер.
Анализируя свойства канала .Status устройства  вы можете определить:

• идентификацинные данные контроллера / устройства
• адрес установки 
• IP-адрес 
• и т.п.

Каждый канал (информационный сигнал) идентифицируется полным именем (или тэгом в терминах SCADA), например: 

Controller1.Status
Controller1.Device1.Status
Controller1.Device1.Channel4

Описание некоторых свойств каналов:

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	Регистрационный номер	строка, может быть использована для внешней идентификации канала

Основные типы данных канала (значение свойства 5001)

Тип	Описание	Коментарий
3000	Дискретный сигнал	Для интерпретации следует анализировать младший бит значения:  Сигнал = Значение && 0х01 0 - норма 1 - сигнальное состояние Подробнее см. Дискретный сигнал (OPC-сервер)
3001	Канал переговорной связи	Для интерпретации следует анализировать младший бит значения:  Сигнал = Значение && 0х01 0 - норма 1 - вызов Для инициализации вызова со стороны АРМ, следует записать значение 1.
3002	Канал управления	Для интерпретации следует анализировать младший бит значения:  Сигнал = Значение && 0х01 0 - канал выключен 1 - канал включен Для включения / выключения канала со стороны АРМ, следует записать: 0 - для выключения канала 1 - для включения канала
3005	Канал статуса	Канал присутствует у любого устройства. Определяет корректность обмена данными с устройством. Если устройство постоянно отвечает на запросы, то значение канала статуса = значению свойства 6004. Если с устройством потеряна связь, значение канала  = 0 и/или не валидно
3060	Числовое значение	Любое числовое значение
3061	Строка	Любая строка
3070	Состояние лифта	Информация о состоянии лифта, представляет собой xml следующего вида: <?xml version="1.0" encoding="utf-16"?> <state type="ОТИС" floor="5" motion="1">     <error state="32769" code="11484" desc="Нет тока в цепи безопасности."/> </state> , где state type - тип станции управления лифтом flooк - текущий этаж кабины motion - признак движения (1 - движение) error state - признак аварии (анализировать младший бит) code - код ошибки desc - расшифровка ошибки

 

Взаимодействие c Tekon OPC-сервер, используя API, реализуется, например по следующей схеме:

Без открытия сессиии

• выполнение запроса, не требующего открытия сессии

С открытием сессиии и подпиской на обвновления данных

• открытие сессии
• получение хэша адресного пространства, сравнение хэша с полученным ранее значеним
• получение обновленного адресного пространства OPC-сервера
  (или чтение локальной копии в случае совпадения хэшей)
• подписка на обновление определенных элементов адресного пространства
• периодическая проверка обновлений данных в подписке 
• периодическая подача управлящих команд  
• закрытие сессии

В текущей версии API-не реализует callback-механизма. Для получения обновлений в подписке, клиент должен выполнять периодические запросы к серверу. 

Рассмотрим, пример, как подписаться на обновление определенного канала адресного пространства. 

Предположим, по запросу адрессного пространства получены следующие данные 

 [ { "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 - внутренний идентификатор канала (внимание, это не жесткий ID, подробнее см. далее)
• ItemName - имя канала, имя тэга

Исходя из полученных данных видим, что присуствуют два канала:

• "ItemID": 0, "ItemName": "DBMonitoring.ConnectFailDevices"
• "ItemID": 1, "ItemName": "DBMonitoring.KIR_BatteryFail"

Допустим,  нас интересует подписка на изменение значения канала "DBMonitoring.KIR_BatteryFail"

В текущей версии API вы можете для организации подписки использовать ItemID, как это было изначально, так и ItemName.

Разница при этом состоит в следующем: 

• при работе с ItemID - следует учитывать, что этот идентификатор не привязан жестко к ItemName. Если адресное пространство сервера изменится  ItemID могут быть сдвинуты относительно предыдущих ItemName.
• для обмена данными на основе ItemName, следует использовать вызовы xxxText
  Эти функции могут выполняться несколько медленнее, чем подписка на основе ItemID.

Адресное пространство сервера может измениться, если:

• в результате регистрации в конфигурации OPC-сервера нового оборудования, или перенастройки каналов существующего оборудования;
• в результате обновления ПО АСУД.SCADA

Факт запуска ОРС-сервера в режиме конфигурирования отслеживается утилитой OPCONNECTOR.EXE, и автоматически будут закрыты все активные сессии обмена данными.
Это является признаком того, что после возобновления подключения, вам следует проверить не изменилось ли адресное пространство сервера, например: сравнив хэш.    

Tekon OPC-сервер не поддерживает функционал обновления свойств каналов после перехода в рабочий режим. Обновленяются только значения каналов.
Соответственно, если система настроена, в ОРС-сервер не добавляется нового оборудования, то его адресное пространство остается неизменно.

Если вы используете подписку на основе ItemID: 

• вызываем функцию Subscriber с параметром {"items":[1]}
• переодически вызываем функцию проверки обновления данных GetUpdates

Если вы используете подписку на основе ItemName:

• вызываем функцию SubscriberText с параметром {"itemstext":[DBMonitoring.KIR_BatteryFail]}
• переодически вызываем функцию проверки обновления данных GetUpdatesText (или GetUpdates)

ДОСТУП К ДАННЫМ

Доступ осуществляется с помощью 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"}

После открытия сессии, следует выполнить запрос получения адресного пространстра или хэша адресного пространства.

Запрос закрытия сессии - CloseSession

Не обязательный запрос. Все "забытые" сессии, автоматически закроются сервером.

GET http://host:port/CloseSession?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A

, где

• • sessionid - идентификатор сессии, полученный в ответ на запрос открытия сессии

Ответ: json следующего вида 

{"result":"ok"}

Активная сессия будет автоматически закрыта сервером в случае отстуствия запросов со стороны клиента в течение 120 секунд.

Запрос хеша адресного пространства OPC-сервера - GetAddressSpaceHash

GET http://host:port/GetAddressSpaceHash?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A

, где

• • sessionid - идентификатор сессии, полученный в ответ на запрос открытия сессии

Ответ: json следующего вида

{"result":"37B885EC021D509DEE32C37A9129512F"}

Запрос адресного пространства 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-сервера не была изменена, то на запрос адресного пространства приходит один и тот  же ответ.
Поэтому при повторных подключениях (открытиях сессии), можно сначала запрашивать хэш значение.

Запрос подписки на обновление указанных данных - 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 - число элементов, которые были добавлены в подписку 

Если ItemID уже был в подписке, он будет проигнорирован.

Для добавления элементов в подписку следует повторно выполнить запрос с указанием новых (добавляемых) идентификаторов элементов.

Запрос подписки на обновление всех данных - SubscriberAll

POST http://host:port/SubscriberAll?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A

, где

• • sessionid - идентификатор сессии полученный в ответ на запрос открытия сессии

Ответ: json следующего вида

{"result":10}

, где

• • result - число элементов, которые были добавлены в подписку 

Этот запрос реализован, скорее для тестовых целей. Вместо него следует использовать запросы: Subscriber или SubscriberText

Запрос подписки на обновление указанных данных - SubscriberText

POST http://host:port/SubscriberText?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A

, где

• • sessionid - идентификатор сессии полученный в ответ на запрос открытия сессии

В POST запросе также передается массив имен элементов ItemName адресного пространства, на обновление данных которых необходимо подписаться, например:

{"itemstext":[""]}

Ответ: json следующего вида

{"result":1}

, где

• • result - число элементов, которые были добавлены в подписку 

Если указанный ItemName уже был в подписке, он будет проигнорирован.

Для добавления элементов в подписку следует повторно выполнить запрос с указанием имен новых (добавляемых) элементов.

Запрос числа элементов в подписке - 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 - количество успешно обновленных элементов