REST API в U‑PROX: приклади керування реле та онлайн-інтеграція

ПЗ U-PROX (воно ж U-PROX IP , воно ж U-PROX Web) – має 2 користувацькі інтерфейси (класичний Windowsінтерфейс, та веб-інтерфейс), використовує СУБД MSSQL, та працює на сімействі ОС Windows.

Використання API – після встановлення компоненти Web-сервер, до основної компоненти – Сервер U-PROX.

Дивіться опис нижче, та “підсвічені” кольором елементи.

В описі API (нижче Блок Б.) – скористайтеся такими пунктами для налаштування власних реакцій:

Documentation\html\Authenticate.html – приклад аутентифікації і підключення до сервера

Documentation\html\EventGetList.html – приклад отримання подій і їх відображення в режимі реального часу “Soft Real-Time”

Documentation\html\DoorControl.html – приклад управління дверима

У системі U-PROX не передбачено довільного механізму реакцій. Реакції реалізуються виключно через визначені передустановки, що пов’язані або з режимом вільного проходу (тобто реле, які керують замками), або з роботою датчика дверей (активація тривожного реле).

Усі інші сценарії поведінки можуть бути реалізовані лише через API-інтеграцію, з використанням відповідного інструментарію.

Окремо існує можливість керування реле за розкладом, але це є іншим функціональним механізмом і не належить до довільних реакцій.

Для роботи з API рекомендується використовувати версію U-PROX IP не нижче v3.057.7988.iso (посилання доступне в описі API), а також скористатися наведеними нижче прикладами реалізації.

Використовуйте один із двох підходів:

• АБО налаштуйте керування відповідними реле за розкладом, вказавши для них режим «Програмований», з типом дії «Старт-Стоп», «Імпульс» або «Тригер»;
• АБО реалізуйте керування цими реле через API.

Наприклад, у разі настання події «вільний прохід» на певному контролері або за допомогою окремої зовнішньої команди, може бути задіяний механізм керування через API. У результаті цього активується реле контролера IP400, яке попередньо налаштоване як «програмоване», та виконує відкриття технологічного проходу.

Детальні приклади реалізації дивіться у нижченаведених описах: Блок А та Блок Б.

Блок А

Додаткові реле мають бути з типом використання “Програмований”, – для можливості їх задіяти через API для зовнішнього керування.

В описі API (нижче Блок Б.) – скористайтеся пунктом:

Documentation\html\DoorControl.html – приклад управління дверима

Який містить відповідну функцію “DeviceOutputCommand“

function DeviceOutputCommand(command, output) {          if (!output) {
         return
       }          // command:
       //   DeviceOutputActivate – увімкнути релейний чи транзисторний вихід контролера
       //   DeviceOutputDeactivate – вимкнути релейний чи транзисторний вихід контролера
       var url = ‘http://localhost:40001/json/’ + command
       var payload = {
         UserSID: $scope.UserSID,
         DeviceToken: output.DeviceToken,
         OutputIndex: output.DeviceIndex
       }
       $http.post(url, payload).then(
         LogResponse,
         LogError
       )
     }
 
// варіанти використання виходів контролера
 const DOU_UNUSED                     =  0  // вихід не використовується
 const DOU_LOCK                       =  1  // вихід використовується для керування замком
 const DOU_BELL                       =  2  // вихід використовується для керування пристроєм прихованої індикації тривоги
 const DOU_ALARM                      =  3  // вихід використовується для керування сиреною
 const DOU_TURNSTILE                  =  4  // вихід використовується для відключення живлення турнікетів декотрих типів, та автоматичного опускання їх штанги в режимі вільного проходу
 const DOU_SOFTWARE_CONTROLLED        =  5  // вихід під керуванням прикладного програмного забезпечення за допомогою API-запитів DeviceOutputActivate/DeviceOutputDeactivate
 const DOU_CARD_COLLECTOR_PASS        =  6  // вихід використовується для видачі сигналу “Пропустити картку” для пристрою збору RFID-карток
 const DOU_CARD_COLLECTOR_GET_CARD    =  7  // вихід використовується для видачі сигналу “Забрати картку” для пристрою збору RFID-карток
 const DOU_CARD_COLLECTOR_RETURN_CARD =  8  // вихід використовується для видачі сигналу “Повернути картку” для пристрою збору RFID-карток
 const DOU_TURNSTILE_EMERGENCY_EXIT   =  9  // вихід використовується для переведення турнікета з імпульсним керуванням в режим вільного проходу
 const DOU_TURNSTILE_BLOCKING         = 10  // вихід використовується для переведення турнікета з імпульсним керуванням в режим блокування
 
 
<div ng-app=”exampleApp” ng-controller=”exampleController”>
<form novalidate class=”simple-form”>
 <label>Login:    <input type=”text” ng-model=”login”    /></label><br />
 <label>Password: <input type=”text” ng-model=”password” /></label><br />
 <div ng-if=”UserSID == ””>
   <hr>
   <label>Disconnected</label><br />
   <hr>
   <input type=”button” ng-click=”Authenticate(login, password)” value=”Authenticate” />
 </div>
 <div ng-if=”UserSID != ””>
   <hr>
   <label>Connected</label><br />
   <hr>
   <label>Door: </label><select ng-model=”door” ng-options=”x.Name for x in doors” ></select><br />
   <input type=”button” ng-click=”DoorCommand(‘DoorAccessIn’,  door)” value=”DoorAccessIn”  /><label>Unlock door for single entrance</label><br />
   <input type=”button” ng-click=”DoorCommand(‘DoorAccessOut’, door)” value=”DoorAccessOut” /><label>Unlock door for single exit</label><br />
   <input type=”button” ng-click=”DoorCommand(‘DoorUnlock’,    door)” value=”DoorUnlock”    /><label>Unlock door for multiple entrances and exits (free pass mode)</label><br />
   <input type=”button” ng-click=”DoorCommand(‘DoorBlock’ ,    door)” value=”DoorBlock”     /><label>Lock door and grant access to security service only</label><br />
   <input type=”button” ng-click=”DoorCommand(‘DoorLock’,      door)” value=”DoorLock”      /><label>Lock door and grant access to enabled cards (default door mode)</label><br />
   <hr>
<label>Software controlled device output: </label><select ng-model=”output” ng-options=”GetDeviceOutputName(x) for x in outputs | softwareControlledOutputs” ></select><br />
<input type=”button” ng-click=”DeviceOutputCommand(‘DeviceOutputActivate’, output)”   value=”DeviceOutputActivate”   /><label>Activate software-controlled device output</label><br />
<input type=”button” ng-click=”DeviceOutputCommand(‘DeviceOutputDeactivate’, output)” value=”DeviceOutputDeactivate” /><label>Deactivate software-controlled device output</label><br />
   <br />
   <input type=”button” ng-click=”Logout()” value=”Logout” />
 </div>988
</form>

Блок Б

Система U-Prox містить інструменти для інтеграції зі стороннім програмним забезпеченням через API з підтримкою протоколів SOAP, REST, JSON, XML.

Програмне забезпечення U-PROX є безкоштовним, як і інструментарій REST API.

Для використання REST API у ПЗ U-PROX при взаємодії зі сторонніми системами необхідно:

• Встановити компоненти ПЗ U-PROX:
  Сервер, Клієнт, Веб-сервер, Десктоп-сервер.
• Дотримуватись логіки роботи:
  Обладнання U-PROX ⇄ ПЗ U-PROX ⇄ Стороннє програмне забезпечення

Доступні такі варіанти взаємодії:

• Двостороння інтеграція через API веб-протоколів із будь-яким іншим ПЗ (повноцінна API-інтеграція).
• Експорт даних зі звітів ПЗ U-PROX стандартними засобами програми та операційної системи з подальшим імпортом у стороннє ПЗ.
• Пряма вибірка даних з бази даних ПЗ U-PROX за допомогою SQL-запитів мовою Transact-SQL (T-SQL) — без необхідності авторизації з боку бази.

ПЗ “U-Prox IP” (воно ж “U-Prox WEB”) має 2 інтерфейси – класичний Windows інтерфейс, та веб-інтерфейс:

• в класичному інтерфейсі експорт звітів може бути в текстовому форматі *.CSV (ручний та автоматичний експорт), та в форматі Excel (тільки ручний експорт), за умови що Excel встановлено на ПК
• у веб-інтерфейсі – створення та експорт звітів вручну, у форматі *.PDF , або через API (PDF чи JSON).

Рекомендована до використання версія ПЗ v3.057.7988:

Завантажте ISO-образ 3.57.7988 версії ПЗ U-PROX, та встановіть/оновіть наявну в себе версію

ISO-образ 3.57.7988 версії ПЗ U-Prox:
–  https://drive.google.com/file/d/14kt60eWtgMPhV5VQMBS1jq5MN7l47uxy/view

Поновлювати в послідовності – Сервер, Клієнт, Веб-Сервер, Десктоп-Сервер – на сервері програми;
та Клієнт і Десктоп-Сервер на віддалених клієнтських робочих місцях.

• Десктоп-Сервер – там де використовується Веб-Клієнт та USB зчитувач U-PROX Desktop.

– та що вказана нижче в описі API

Оновлення сторінки в бравзері після переходу на новіші версії – “Ctrl+F5”, щоб перевантажити із очисткою кешу.

Загальний опис API

Перегляньте наявну інформацію на сторінці “API інтеграції”, нашого сайту: 

–  https://u-prox.systems/software/

Перегляньте довідник по функціях (доступно після встановлення комплексу U-PROX): 

–  http://127.0.0.1:40001/json/help (Eng)

Також на встановленій системі U-PROX, в браузері, за допомогою вікна розробника (F12), можна переглядати взаємодію U-PROX WEB з API

Якщо мало інформації – задайте питання на електронну пошту support@itvsystems.com.ua з темою API інтеграція.

U-PROX WEB Server REST API

Останні версії прикладів і документації U-PROX WEB API містяться в хмарній папці:

–  https://drive.google.com/drive/folders/1QpNENLEwYwjy_uOeFmjNmlSlIoVTf33b

У зазначеній папці містяться такі файли:

U-Prox IP.v3.057.7988.iso – образ дистрибутивного диска. З цього образу необхідно встановити або оновити “U-PROX IP Сервер”, “U-PROX IP Клієнт”, “U-PROX Web Сервер” і “U-PROX Desktop Сервер”.

Documentation\AcsWebService.doc – попередня версія опису Web-сервісу, яка містить опис операцій для підключення до сервісу, отримання повідомлень про події і створення співробітників та інших операцій

Documentation\html\*.html – приклади на мові JavaScript з використанням бібліотеки AngularJS

Documentation\html\Authenticate.html – приклад аутентифікації і підключення до сервера

Documentation\html\DoorControl.html – приклад управління дверима

Documentation\html\DoorUnlockAll.html – приклад пожежного розблокування всіх дверей системи

Documentation\html\AdditionalEventFields.html – приклад отримання та створення пристроїв (контролерів), додаткових полів подій та самих подій (записів про проходи)

Documentation\html\Employees.html – приклад отримання списку пристроїв (контролерів), дверей, рівнів доступу, відділів (департаментів), співробітників (користувачів), карток, їх створення, звільнення співробітників і видалення створених об’єктів

Documentation\html\EventGetList.html – приклад отримання подій і їх відображення в режимі реального часу “Soft Real-Time”

Documentation\html\EventsReport.html – приклад отримання звіту про події у вигляді PDF і у вигляді JSON

Documentation\html\TimeAttendanceReport.html – приклад отримання звіту про відпрацьований час у вигляді PDF і у вигляді JSON

Documentation\html\Visitors.html – приклад отримання списку пристроїв, дверей, тимчасових рівнів доступу, відвідувачів, створення карток і видалення створених об’єктів

Documentation\html\js\*.js – використані бібліотеки JavaScript

Для демонстрації роботи web-додатків DoorControl.html, Employees.html, Visitors.html та ін. необхідно виконати наступні дії:

1. Завантажити образ дистрибутивного диска U-Prox IP.v3.057.7988.iso з папки в хмарі:

–  https://drive.google.com/open?id=1QpNENLEwYwjy_uOeFmjNmlSlIoVTf33b

2. Встановити або оновити U-PROX IP Сервер.

3. Встановити або оновити U-PROX IP Клієнт.

4. Встановити або оновити U-PROX IP Web Сервер.

5. Встановити або оновити U-PROX IP Desktop Сервер.

6. Відкрити відповідний html-файл в браузері Chrome і переглянути перелік запитів та відповідей на запити.

Онлайн режим (короткий опис)

Підтримку режимів зовнішнього керування доступом контролера було додана в ПЗ “U-PROX IP” версії 3.052.6722. Необхідно, що б була встановлена така, чи більш пізня версія.

“Вхід дозволено“:

POST http://localhost:40001/json/DoorAccessIn

{

“UserSID”: 1234567890123456,            // ідентифікатор сеансу, отриманий в результаті запиту Authenticate

“Token”: 12345,                                   // токен дверей чи токен напрямку проходу (Двері – вхід, Двері – вихід), для яких подається команда

“CardCode: “1234567890”                    // код картки, який буде збережено в журналі для події “Вхід дозволено”.

}

“Вихід дозволено“:

POST http://localhost:40001/json/DoorAccessOut

{

“UserSID”: 1234567890123456,            // ідентифікатор сеансу, отриманий в результаті запиту Authenticate

“Token”: 12345,                                   // токен дверей чи токен напрямку проходу (Двері – вхід, Двері – вихід), для яких подається команда

“CardCode: “1234567890”                    // код картки, який буде збережено в журналі для події “Вихід дозволено”

}

“Вхід заборонено“:

POST http://localhost:40001/json/DoorDenyAccessIn

{

“UserSID”: 1234567890123456,            // ідентифікатор сеансу, отриманий в результаті запиту Authenticate

“Token”: 12345,                                   // токен дверей чи токен напрямку проходу (Двері – вхід, Двері – вихід), для яких подається команда

“CardCode: “1234567890”                    // код картки, який буде збережено в журналі для події “Вхід заборонено”

}

“Вихід заборонено“:

POST http://localhost:40001/json/DoorDenyAccessOut

{

“UserSID”: 1234567890123456,            // ідентифікатор сеансу, отриманий в результаті запиту Authenticate

“Token”: 12345,                                   // токен дверей чи токен напрямку проходу (Двері – вхід, Двері – вихід), для яких подається команда

“CardCode: “1234567890”                    // код картки, який буде збережено в журналі для події “Вихід заборонено”

}

Онлайн режим (детальний опис)

Далі наведено додаткові відомості про режим зовнішнього керування доступом контролера U-PROX IP400 та його підтримку в програмному забезпеченні “U-Prox IP”.

Режим зовнішнього керування доступом, при якому рішення про надання доступу приймаються сервером за командою оператора, або по запиту REST API, доступний в “U-PROX IP” із версії v.3.052.6833, та в пізніших версіях.

Є два режими зовнішнього керування доступом:

1. “Оператор забороняє та дозволяє доступ” – у цьому режимі контролер передає інформацію про будь-яку піднесену картку на сервер, і надає доступ, або видає заборонний сигнал, тільки після відповіді сервера.

2. “Оператор підтверджує надання доступу – у цьому режимі піднесення забороненої карти контролер обробляє самостійно, видаючи сигнал заборони, а інформацію про піднесення дозволеної карти передає на сервер, і протягом кількох секунд чекає від сервера команди на надання чи заборону доступу. В разі відсутності такої команди, після закінчення встановленого часу, контролер надає доступ для піднесеної дозволеної карти.

Для коректної роботи другого режиму (оператор підтверджує надання доступу) необхідно наявність, чи оновлення, мікропрограми контролерів U-Prox IP400 версії не нижче 7.23/8.23 .

Налаштування режиму зовнішнього керування доступу в ПЗ “U-PROX WEB Клієнт”, що доступний за адресою http://localhost:40001/ , після встановлення ПЗ “U-PROX IP Сервер” та ПЗ “U-PROX WEB Сервер”, показано на скріншотах:

чи в класичному клієнті

чи в класичному клієнті

Після завантаження нової конфігурації в контролер, інформація про піднесення карти може бути отримана за REST API у вигляді події:

{

“Event”:[

{

“Device”:{

“Name”:”Турнікет”,

“Token”:23880

},

“Message”:{

“Code”:65555,                          // код події: 65554 – запит на вхід, 65555 – запит на вихід

“Name”:”Запит на вихід”,

},

“Sender”:{

“Name”:”Турнікет – вихід”,

“Token”:23902

},

“User”:{

“EmployeeNumber”:””,

“Post”:””,

“AdditionalFields”:[

],

“Name”:”Петренко”,

“Token”:6580

},

“Department”:{

“Name”:”Адміністрація”,

“Token”:6566

},

“PhotoToken”:23678,

“IconToken”:23679,

“CardCode”:”0B0016B189″,

“Issued”:”\/Date(1591793191053)\/”,

“FaceMaskDetected”:false,

“Temperature”:0,

“AdditionalFields”:[

],

“Token”:34106,

}

]

}

З прикладом отримання подій у режимі Soft Real Time можна ознайомитись у файлах Documentation\html\EventGetList.html та Documentation\html\Photoverification.html у хмарній папці з прикладами REST API:

–  https://drive.google.com/drive/u/0/folders/1yyYWg8pPimNbYoG1XeOhFfIOMLg6Y2ug

Для дозволу проходу необхідно надіслати запит:

POST http://localhost:40001/json/DoorAccessIn чи http://localhost:40001/json/DoorAccessOut

{

“UserSID”:”830730959685833″,            // ідентифікатор сеансу підключення до сервера

“Token”:23902,                                    // Event[i].Sender.Token – токен точки доступу, вказаний в події

“CardCode”:”0B00123456″                   // код карти, якій надано доступ

}

Для заборони проходу необхідно надіслати запит:

POST http://localhost:40001/json/DoorDenyAccessIn чи http://localhost:40001/json/DoorDenyAccessOut

{

“UserSID”:”830730959685833″,            // ідентифікатор сеансу підключення до сервера

“Token”:23902,                                    // Event[i].Sender.Token – токен точки доступу, вказаний в події

“CardCode”:”0B00123456″                   // код карти, якій надано доступ

}