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

Материал из TekonWiki
Перейти к навигацииПерейти к поиску
← Предыдущая правкаСледующая правка →
ВизуальныйВики-текст
Нет описания правки
Нет описания правки
Строка 161: Строка 161:
<pre>{"sessionid":"22339217-FEF1-45B4-BB59-70177BB2997A"}
<pre>{"sessionid":"22339217-FEF1-45B4-BB59-70177BB2997A"}
</pre>
</pre>




Строка 170: Строка 171:
, где
, где


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


Ответ: json-массив следующего вида
Ответ: json-массив следующего вида
Строка 212: Строка 213:
, где:
, где:


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


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


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


Tekon OPC-сервер не использует функционал обновления свойств элементов. Обновленяются только значения элементов.
Tekon OPC-сервер не использует функционал обновления свойств элементов.&nbsp;Обновленяются только значения элементов.<br/> Соответственно, если система настроена, в ОРС-сервер не добавляется нового оборудования, то его адресное пространство - неизменно.
 
В случае, если произойдет запуск конфигуратора ОРС-сервера в режиме настройки, HTTP-сервер автоматически закроет все активные сессии обмена данными.


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


{| border="1" cellpadding="1" cellspacing="1" class="wikitable" style="width: 700px;"
{| border="1" cellpadding="1" cellspacing="1" class="wikitable" style="width: 700px;"
Строка 255: Строка 258:
| style="width: 312px;" | Адрес установки оборудования
| style="width: 312px;" | Адрес установки оборудования
| style="width: 380px;" | строка
| style="width: 380px;" | строка
|-
| style="width: 33px;" | 6003
| style="width: 312px;" | Минимальное значение канала Status устройства
| style="width: 380px;" | если отсутствует, то 0
|-
| style="width: 33px;" | 6004
| style="width: 312px;" | Максимальное значение канала Status устройства
| style="width: 380px;" | определениет максимальное значение оценки опроса
|-
|-
| style="width: 33px;" | 7000
| style="width: 33px;" | 7000
Строка 263: Строка 274:
| style="width: 312px;" | Описание неисправности
| style="width: 312px;" | Описание неисправности
| style="width: 380px;" | строка. Определяет за что конкретно отвечает этот элемент
| style="width: 380px;" | строка. Определяет за что конкретно отвечает этот элемент
|-
| style="width: 33px;" | 9002
| style="width: 312px;" | Регистрационный номер
| style="width: 380px;" | строка, может быть использована для внешней идентификации канала
|}
|}


Возможные типы данных, которые хранит элемент
Возможные типы данных канала


{| border="1" cellpadding="1" cellspacing="1" class="wikitable" style="width: 700px;"
{| border="1" cellpadding="1" cellspacing="1" class="wikitable" style="width: 700px;"
Строка 295: Строка 310:


Для включения / выключения канала со стороны АРМ, следует записать:<br/> 0 - для выключения канала<br/> 1 - для включения канала
Для включения / выключения канала со стороны АРМ, следует записать:<br/> 0 - для выключения канала<br/> 1 - для включения канала
|-
| 3005
| style="width: 170px;" | Канал статуса
| style="width: 528px;" |
Канал присутствует у любого устройства.<br/> Определяет корректность обмена данными с устройством.<br/> Если устройство постоянно отвечает на запросы, то значение канала статуса = значению свойства 6004.<br/> Если с устройством потеряна связь, значение канала&nbsp; = 0.


|-
|-

Версия от 11:38, 30 октября 2024



ВВЕДЕНИЕ

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

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

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

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

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

21-10-2024

  • Добавлен вызов ServerInformation
  • Добавлен параметр readID в вызовы GetUpdates

03-05-2024

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

27-03-2024

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


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

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

  • открытие сессии
  • получение адресного пространства OPC-сервера (не обязательно)
  • подписка на обновление определенных элементов адресного пространства
  • периодическая проверка обновлений данных в подписке 
  • выборочное чтение значений элементов 
  • выборочная запись новых значений элементов 
  • закрытие сессии

Активная сессия будет автоматически закрыта сервером в случае отстуствия запросов со стороны клиента в течение 120 секунд.

В текущей версии API-не реализует callback-механизма. Для получения обновлений в подписке, клиент должен выполнять периодические запросы к серверу. 

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

Каждый канал идентифицируется полным именем, например:  Controller1.Device1.Channel4

Каждое устройство или контроллер имеют специальный канал  .Status - определяющий происходит ли обмен данными с устройством.
Если значение канала .Status контроллера не валидно, то соответственно нет обмена данными (не актуальны значения) всех устройств (и всех датчиков устройств), подключенных на данный контроллер.
Анализируя свойства канала 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 - имя канала

Если конфигурация 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 Дискретный сигнал

Для интерпретации следует анализировать младший бит значения: 
Сигнал = Значение && $01
0 - норма
1 - сигнальное состояние

Подробнее см. Дискретный сигнал (OPC-сервер)

3001 Канал переговорной связи

Для интерпретации следует анализировать младший бит значения: 
Сигнал = Значение && $01
0 - норма
1 - вызов

Для инициализации вызова со стороны АРМ, следует записать значение 1.

3002 Канал управления

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