WEB OPC HTTP API

ВВЕДЕНИЕ

Данное 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). 

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

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

• открытие сессии
• получение адресного пространства 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-сервера Следует выполнить переоткрытие сессии и заново оформить подписку на элементы

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

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

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