WEB OPC HTTP API

ВВЕДЕНИЕ

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

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

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

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

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

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

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

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

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

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

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