WEB OPC HTTP API

Материал из TekonWiki
Перейти к навигацииПерейти к поиску


ВВЕДЕНИЕ

Данное API позволяет получить доступ к данными диспетчеризации, циркулирующим в ПО АСУД.SCADA, посредством выполнения запросов по HTTP(S) протоколу к специализированному WEB-сервису.

WEB-сервис реализован в приложении  .. \ tools-server \ opcconnector.exe

По-сути API является OPC-HTTP шлюзом для OPC DA - сервера.

Если вам необходим доступ к данным подсистемы учета ресурсов смотри WEB REST API 

История версий: 

03-05-2024

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

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-сервера

Следует выполнить переоткрытие сессии и заново оформить подписку на элементы


Специальные запросы, не требующие открытия сессии

Несколько запросов, которые можно выполнять без открытия сессии.

ZabbixNS

GET http://host:port/ZabbixNS

В ответ будет получен массив текущих состояний статусов всех подключенных устройств.

Ответ: 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 разное для разных типов устройств.

GetAddressSpaceNS

GET http://host:port/GetAddressSpaceNS

Подробнее смотри описание запроса GetAddressSpace

GetAddressSpaceHashNS

GET http://host:port/GetAddressSpaceHashNS

Подробнее смотри описание запроса GetAddressSpaceHash

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

Запрос закрытия сессии - 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

Ответ: json-массив 

 [{
  "UpTime": "2023-04-28 17:54:55",
  "V": "0",
  "ItemID": 3,
  "Qual": 192
 }]

, где 

  • UpTime - время обновления
  • V - значение элемента
  • ItemID - идентификатор элемента, который был указан в подписке
  • Qual - качество значения 

Внимание! В ответе присуствуют только те данные, которые обновились с момента прошлого запроса.

Запрос проверки новых данных в подписке - GetUpdatesText

Запрос следует выполнять периодически, например: раз в секунду, для полученя новых данных, на которые ранее была выполнена подписка . 

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

Ответ: 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=9286