WEB OPC HTTP API

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


ВВЕДЕНИЕ

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

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

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

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

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

27-03-2024

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

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

Взаимодействие реализуется по следующей схеме:

  • получение адресного пространства Tekon 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 Tekon OPC-сервер не доступен

Вероятно осуществляется перезапуск OPC-сервера

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

 

Запрос адресного пространства Tekon OPC-сервера

Это первый запрос, который следует выполнять при подключении к серверу. 

GET http://host:port/GetAddressSpace

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

 [
 {
  "ItemProps": [
   {
    "Datatype": 18,
    "ID": 1,
    "Value": "19",
    "Error": 0,
    "Desc": "Тип данных"
   },{
    "Datatype": 19,
    "ID": 5,
    "Value": "3",
    "Error": 0,
    "Desc": "Права доступа"
   }],
  "ItemIndex": 0,
  "ItemName": "DBMonitoring.ConnectFailDevices"
 },{
  "ItemProps": [
   {
    "Datatype": 18,
    "ID": 1,
    "Value": "19",
    "Error": 0,
    "Desc": "Тип данных"
   },{
    "Datatype": 19,
    "ID": 5,
    "Value": "3",
    "Error": 0,
    "Desc": "Права доступа"
   }],
  "ItemIndex": 1,
  "ItemName": "DBMonitoring.KIR_BatteryFail"
 }]

, где:

  • ItemProps - набор свойств элемента Tekon OPC-сервера
  • ItemIndex - идентификатор элемента. Используется далее при обмене данным с сервером
  • ItemName - имя элемента

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


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

GET http://host:port/NewSession?alldata=0

, где

  • alldata - определяет механизм обновления данных в подписке 
    • 0 - обычно, предоставлять только последнее обновление значения элемента между запросами данных
    • 1 - предоставлять все изменения значений элемента между  двумя запросами данных

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

{"sessionid":"22339217-FEF1-45B4-BB59-70177BB2997A"}


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

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

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

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

{"result":"ok"}

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

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

, где

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

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

{"items":[0,1,2,3,4,5,6,7,8,9]}

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

{"result":10}

, где

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

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


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

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

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 - идентификатор элемента, который был указан в подписке (и получен из адресного пространства Tekon OPC-сервера)
  • Qual - качество значения 

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

Запрос принудительного чтения значения элемента подписки

GET http://host:port/ReadItemValue?sessionid=22339217-FEF1-45B4-BB59-70177BB2997A&item=1

, где 

  • item  - идентификатор элемента, который был указан в подписке (и получен из адресного пространства Tekon OPC-сервера)

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

{"result":1}

, где

  • result
    • 0 - ошибка, запрашиваемый идентификатор отсутствует в подписке 
    • 1 - ok

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

Запрос принудительного чтения значений всех элементов подписки

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

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

{"result":10}

, где

  • result
    • 0 - ошибка, отсутствуют элементы в подписке
    • > 0  - ok, 

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


Запрос записи нового значения элемента подписки

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

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

[{
  "ItemID": 1,
  "Value": "0"
 }]

Для возможности записи значения в ItemID, необходимо чтобы он был ранее добавлен в подписку.

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

 {"result":1}
  • 1 - количество успешно обновленных элементов
Источник — https://wiki.tekon.ru/index.php?title=WEB_OPC_HTTP_API&oldid=9211