WEB OPC HTTP API: различия между версиями

Материал из TekonWiki
Перейти к навигацииПерейти к поиску
← Предыдущая правкаСледующая правка →
ВизуальныйВики-текст
Нет описания правки
Нет описания правки
Строка 40: Строка 40:
*Обновление API  
*Обновление API  
*Возможность подключение к любому OPC DA серверу (не только к Tekon OPC DA). 
*Возможность подключение к любому OPC DA серверу (не только к Tekon OPC DA). 


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


Взаимодействие реализуется по следующей схеме:
Взаимодействие c [[Tekon_OPC-сервер|Tekon OPC-сервер]], используя API, реализуется, например по следующей схеме:
 
Без открытия сессиии
 
*выполнение запроса
 
С открытием сессиии и подпиской на обвновления данных


*открытие сессии  
*открытие сессии  
*получение адресного пространства OPC-сервера (не обязательно)  
*получение хэша адресного пространства, сравнение хэша с полученным ранее значеним
*получение обновленного адресного пространства OPC-сервера<br/> (или чтение локальной копии в случае совпадения хэшей)  
*подписка на обновление определенных элементов адресного пространства  
*подписка на обновление определенных элементов адресного пространства  
*периодическая&nbsp;проверка обновлений&nbsp;данных в подписке&nbsp;  
*периодическая&nbsp;проверка обновлений&nbsp;данных в подписке&nbsp;  
*выборочное чтение&nbsp;значений элементов&nbsp;  
*выборочное чтение&nbsp;значений элементов&nbsp;  
*выборочная запись новых&nbsp;значений элементов&nbsp;  
*выборочная запись значений элементов&nbsp;  
*закрытие сессии  
*закрытие сессии  


Строка 59: Строка 67:
Адресное пространство ОРС-сервера представляет собой иерархическую структуру следующего вида
Адресное пространство ОРС-сервера представляет собой иерархическую структуру следующего вида


[[File:Opchttp space.PNG|center|350px|Opchttp space.PNG]]Каждый канал идентифицируется полным именем, например:&nbsp;
[[File:Opchttp space.PNG|center|350px|Opchttp space.PNG]]Каждый канал (информационный сигнал)&nbsp;идентифицируется полным именем, например:&nbsp;
<pre>Controller1.Device1.Channel4
<pre>Controller1.Device1.Channel4
Controller1.Device1.Status
Controller1.Device1.Status
Строка 65: Строка 73:
</pre>
</pre>


Каждый канал, содержит набор свойств, описывающих настройки канала (подробнее описание свойств см. далее).<br/> Например: свойство с ID = 6001 содержит адресную информацию в текстовом виде, а&nbsp;ID = 9002 регистрационную информацию, которая может быть использована для идентификации точки в сторонней информационной системе.<br/> <br/> Каждое&nbsp;устройство или контроллер имеют специальный канал&nbsp; .Status - определяющий происходит ли обмен данными с устройством.<br/> Если значение канала .Status контроллера не валидно, то соответственно нет обмена данными (не актуальны значения) всех устройств (и всех датчиков устройств), подключенных на данный контроллер.<br/> Анализируя свойства канала Status устройства&nbsp; вы можете определить:
Каждый канал, содержит набор свойств, описывающих настройки канала (подробнее описание свойств см. далее). Например:
 
*ID = 6001 содержит адресную информацию в текстовом виде,  
*ID = 9002 регистрационную информацию, которая может быть использована для идентификации точки в сторонней информационной системе.  
 
Каждое&nbsp;устройство или контроллер всегда имеют специальный канал&nbsp; .Status (статус или оценка), определяющий происходит ли обмен данными&nbsp;[[Tekon_OPC-сервер|Tekon OPC-сервер]] с устройством или нет.<br/> Если значение канала .Status = 0 и/или не валидно, то соответственно нет обмена данными, не актуальны значения всех устройств (и всех датчиков устройств), подключенных на данное&nbsp;устройство или контроллер.<br/> Анализируя свойства канала Status устройства&nbsp; вы можете определить:


*идентификацинные данные устройства  
*идентификацинные данные устройства  

Версия от 15:54, 6 февраля 2025





ВВЕДЕНИЕ

Данное 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-механизма. Для получения обновлений в подписке, клиент должен выполнять периодические запросы к серверу. 

Адресное пространство ОРС-сервера представляет собой иерархическую структуру следующего вида

Opchttp space.PNG
Opchttp space.PNG

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

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

Каждый канал, содержит набор свойств, описывающих настройки канала (подробнее описание свойств см. далее). Например:

  • ID = 6001 содержит адресную информацию в текстовом виде,
  • ID = 9002 регистрационную информацию, которая может быть использована для идентификации точки в сторонней информационной системе.

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

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

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

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

Пример полного JSON-файла конфигурации для АРМ на базе USB-Пульта.

Если конфигурация OPC-сервера не изменяется, то на запрос адресного пространства приходит один и тот  же ответ.
Поэтому при повторных запросах, можно сначала запрашивать хэш значение.

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

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

В случае, если произойдет запуск конфигуратора ОРС-сервера в режиме настройки, HTTP-сервер автоматически закроет все активные сессии обмена данными.

Описание свойств каналов адресного пространства.

ID Описание Комментарий
1 Определяет OleVariant тип значения элемента например: 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 Дискретный сигнал

Для интерпретации следует анализировать младший бит значения: 
Сигнал = Значение && 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 - расшифровка ошибки

 

Запрос закрытия сессии - 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 - количество успешно обновленных элементов
Источник — https://wiki.tekon.ru/index.php?title=WEB_OPC_HTTP_API&oldid=9793