ALGO RESTful API

Інфармацыя пра прадукт: Кіраўніцтва па RESTful API

Algo RESTful API дазваляе карыстальнікам атрымліваць доступ, маніпуляваць і запускаць дзеянні на Algo IP Endpoints у сваёй сетцы праз запыты HTTP/HTTPS. У гэтым дакуменце прадстаўлены адзіны і загадзя вызначаны набор аперацый без захавання стану, якія можна выкарыстоўваць для ўзаемадзеяння з прыладамі Algo. API падтрымлівае запыты HTTP/HTTPS GET, POST і PUT з карыснай нагрузкай JSON.

Аўтэнтыфікацыя

З Algo RESTful API даступныя тры тыпы аўтэнтыфікацыі:

• Стандартная аўтэнтыфікацыя (уключана па змаўчанні)
• Базавая аўтэнтыфікацыя (неабавязкова)
• Няма метаду аўтэнтыфікацыі (не рэкамендуецца; толькі ў мэтах тэставання)

Інструкцыі па выкарыстанні прадукту: RESTful API

Перадумовы

Перш чым уключыць RESTful API, пераканайцеся, што прылада мае падключэнне да Інтэрнэту для доступу да папярэдне сканфігураваных сервераў NTP. Калі інтэрнэт-злучэнне адсутнічае, наладзьце лакальны сервер NTP і ўвядзіце яго IP-адрас.

Уключэнне RESTful API

1. Увайдзіце ў сістэму прылады web інтэрфейс і перайдзіце на ўкладку Адміністратар Дадатковыя налады.
2. Пракруціце ўніз да раздзела падтрымкі API і ўключыце RESTful API.
3. Усталюйце патрэбны пароль (пароль па змаўчанні: algo). Звярніце ўвагу, што стандартная аўтэнтыфікацыя ўключана па змаўчанні.

Уключэнне базавай аўтэнтыфікацыі (неабавязкова)

1. У ст web інтэрфейс, перайдзіце на ўкладку System Maintenance і загрузіце канфігурацыю file.
2. Адкрыйце канфігурацыю file любым тэкставым рэдактарам і дадайце наступны радок: api.auth.basic = 1
3. Захавайце і загрузіце змененую канфігурацыю file назад на прыладу з дапамогай Аднавіць канфігурацыю File функцыя на ўкладцы Абслугоўванне сістэмы.

Уключэнне без метаду аўтэнтыфікацыі (неабавязкова)

Каб уключыць метад без аўтэнтыфікацыі, пакіньце поле RESTful API Password пустым. Гэты метад не рэкамендуецца і павінен выкарыстоўвацца толькі ў мэтах тэставання, паколькі ён не забяспечвае бяспекі.

Уключэнне простага інтэрфейсу кіравання (неабавязкова)

1. На ст web інтэрфейс, перайдзіце на ўкладку System Maintenance і загрузіце канфігурацыю file.
2. Адкрыйце канфігурацыю file з дапамогай тэкставага рэдактара і дадаць два радкі. Зменіце пароль на свой.
3. Адмін.web.sci = 1
4. Sci.admin.pwd =
5. Захавайце і загрузіце змененую канфігурацыю file назад на прыладу з дапамогай Аднавіць канфігурацыю File функцыя на ўкладцы Абслугоўванне сістэмы.

Аўтэнтыфікацыя СampКодэкс

Калі ласка, па электроннай пошце support@algosolutions.com калі вы хочаце стандартную або базавую аўтэнтыфікацыю sampкод.
Для атрымання дадатковай падтрымкі тэлефануйце 604-454-3792 або па электроннай пошце support@algosolutions.com

Інфармацыйныя апавяшчэнні

Заўвага
Заўвага паказвае на карысныя абнаўленні, інфармацыю і інструкцыі, якіх трэба прытрымлівацца

Адмова ад адказнасці

Інфармацыя, якая змяшчаецца ў гэтым дакуменце, лічыцца дакладнай ва ўсіх адносінах, але Algo не гарантуе яе. Інфармацыя можа быць зменена без папярэдняга паведамлення і ні ў якім разе не павінна тлумачыцца як абавязацельства Algo або любога з яго філіялаў або даччыных кампаній. Algo і яе філіялы і даччыныя кампаніі не нясуць ніякай адказнасці за любыя памылкі або недагляды ў гэтым дакуменце. Перагляды гэтага дакумента або яго новыя выданні могуць быць выдадзены з улікам такіх змяненняў. Algo не нясе адказнасці за шкоду або прэтэнзіі ў выніку любога выкарыстання гэтага кіраўніцтва або такіх прадуктаў, праграмнага забеспячэння, прашыўкі і/або абсталявання. Ніякая частка гэтага дакумента не можа быць прайграная або перададзена ў любой форме або любымі сродкамі - электроннымі або механічнымі - для любых мэт без пісьмовага дазволу Algo.
Для атрымання дадатковай інфармацыі або тэхнічнай дапамогі ў Паўночнай Амерыцы, калі ласка, звярніцеся ў службу падтрымкі Algo:

Тэхнічная падтрымка Algo
1-604-454-3792
support@algosolutions.com

©2022 Algo з'яўляецца зарэгістраванай гандлёвай маркай Algo Communication Products Ltd.
Усе правы абаронены. Усе іншыя гандлёвыя маркі з'яўляюцца ўласнасцю іх адпаведных уладальнікаў. Усе характарыстыкі могуць быць зменены без папярэдняга паведамлення.

 АГУЛЬНЫЯ

Уводзіны

У гэтым дакуменце апісваецца, як Algo RESTful API можа быць выкарыстаны для доступу, маніпулявання і запуску дзеянняў на Algo IP Endpoints у вашай сетцы праз HTTP/HTTPS запыты, а таксама некалькі розных метадаў аўтэнтыфікацыі з рознымі ўзроўнямі бяспекі. Сістэмы, якія адпраўляюць запыты, могуць узаемадзейнічаць з прыладамі Algo праз аднастайны і загадзя вызначаны набор аперацый без захавання стану, вызначаных у гэтым дакуменце. Запыты робяцца да URI рэсурсу з карыснай нагрузкай JSON і выклікаюць адказ JSON. Запыты HTTP/HTTPS GET, POST і PUT выконваюцца да URI рэсурсу разам з карыснай нагрузкай JSON (спіс карысных нагрузак глядзіце ў раздзеле каманд).

 Аўтэнтыфікацыя

Ёсць тры тыпу аўтэнтыфікацыі:

•  Стандарт (рэкамендуецца)
•  Базавы
•  Няма (не рэкамендуецца)

Стандартная аўтэнтыфікацыя выкарыстоўвае код аўтэнтыфікацыі паведамлення на аснове хэша (HMAC) з дайджэстам у кадзіроўцы SHA-256. Базавая аўтэнтыфікацыя выкарыстоўвае кадзіроўку Base64 і павінна выкарыстоўвацца толькі праз HTTPS. Без аўтэнтыфікацыі варта выкарыстоўваць толькі з асаблівай асцярожнасцю, бо яна не забяспечвае аўтэнтыфікацыі. Больш падрабязную інфармацыю глядзіце ў раздзеле "Патрабаванні да аўтэнтыфікацыі".

НАЛАДКА І КАНФІГУРАЦЫЯ

Перадумовы

•  У гэтым дакуменце мяркуецца, што канчатковая кропка Algo працуе пад кіраваннем прашыўкі версіі 3.3 або вышэй.
•  Для выкарыстання стандартнай аўтэнтыфікацыі розніца ў часе паміж запытам і прыладамі Algo павінна быць менш за 30 секунд.
• Пераканайцеся, што NTP (пратакол сеткавага часу) выкарыстоўваецца. Адрасы карыстальніцкіх сервераў NTP можна наладзіць ва ўкладцы Дадатковыя налады → Час.

Заўвага
Папярэдне сканфігураваныя NTP-серверы знаходзяцца ў адкрытым доступе, таму для доступу да іх патрабуецца падключэнне да Інтэрнэту. Калі інтэрнэт-злучэнне адсутнічае, наладзьце лакальны сервер NTP і ўвядзіце яго IP-адрас.

• Пераканайцеся, што сістэмны час прылады Algo настроены на правільны часавы пояс. Гэта можна зрабіць, перайшоўшы на ўкладку Дадатковыя налады → Час.

 Уключэнне RESTful API

1. Увайдзіце ў web інтэрфейс і перайдзіце на ўкладку Дадатковыя налады → Адміністратар.
2. Пракруціце ўніз да раздзела падтрымкі API, уключыце RESTful API і ўсталюйце пароль па жаданні (пароль па змаўчанні: algo)
   Заўвага
   Стандартная аўтэнтыфікацыя ўключана па змаўчанні.

Уключыць базавую аўтэнтыфікацыю (неабавязкова)

1. У ст web інтэрфейс, перайдзіце на ўкладку Сістэма → Абслугоўванне і загрузіце канфігурацыю file.
2. Адкрыйце канфігурацыю file любым тэкставым рэдактарам і дадайце наступны радок: api.auth.basic = 1
3.  Захавайце і загрузіце змененую канфігурацыю file назад на прыладу з дапамогай Аднавіць канфігурацыю File функцыя на ўкладцы Сістэма → Абслугоўванне.

Без метаду аўтэнтыфікацыі (неабавязкова)

Каб уключыць метад без аўтэнтыфікацыі, пакіньце поле RESTful API Password пустым. Гэты метад не рэкамендуецца і павінен выкарыстоўвацца толькі ў мэтах тэставання, паколькі ён не забяспечвае бяспекі.

Уключэнне простага інтэрфейсу кіравання (неабавязкова)

1. На ст web інтэрфейс, перайдзіце на ўкладку Сістэма → Абслугоўванне і загрузіце канфігурацыю file.
2.  Адкрыйце канфігурацыю file з дапамогай тэкставага рэдактара і дадаць два радкі. Змяніць на ваш жаданы пароль. Адмін.web.sci = 1
   Sci.admin.pwd =
3.  Захавайце і загрузіце змененую канфігурацыю file назад на прыладу з дапамогай Аднавіць канфігурацыю File функцыя на ўкладцы Сістэма → Абслугоўванне.

ПАТРАБАВАННІ ДА аўтэнтыфікацыі

Калі ласка, па электроннай пошце support@algosolutions.com калі вы хочаце стандартную або базавую аўтэнтыфікацыю sampкод.

Стандартны запыт аўтэнтыфікацыі з карыснай нагрузкай JSON

Абавязковыя загалоўкі ў запыце HTTP/HTTPS
> Тып кантэнту: «прыкладанне/json»
> Content-MD5: [content_md5] Example
Content-MD5: 74362cc86588b2b3c5a4491baf80375b

Аўтарызацыя: hmac admin:[nonce]:[hmac_output]
Загалоўкі аўтарызацыі складаюцца з:

1. Радок «hmac admin», за якім ідзе двукроп'е «:».
2. Nonce – выпадковае або непаўтаральнае значэнне, за якім ідзе двукроп'е ":".
3. Hmac_output – генеруецца паролем RESTful API (сакрэтным ключом), настроеным на вашай прыладзе, і ўваходам HMAC, як паказана ніжэй:
   [request_method]:[request_uri]:[content_md5]:[content_type]:[часamp]:[разавы раз]

Уваход HMAC напрample: (з выкарыстаннем «algo» у якасці сакрэтнага ключа)
POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 Стварыце HMAC з паролем і ўваходным радком HMAC у выглядзе дайджэста з выкарыстаннем SHA-256:
Вывад HMAC напрample: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

Дата: дзень, дата, месяц, год гадзіна:хв.:сек. па Грынвічы
Example
Дата: чацвер, 22 верасня 2022 г. 02:33:07 GMT
Стандартная аўтэнтыфікацыя з карыснай нагрузкай напрampль:

 Стандартны запыт аўтэнтыфікацыі без карыснай нагрузкі JSON

Ідэнтычны 3.1 з апушчанымі загалоўкамі, звязанымі са змесцівам/уводам hmac.
Уваход HMAC: [request_method]:[request_uri]:[timestamp]:[nonce] увод HMAC напрample: (з выкарыстаннем «algo» у якасці сакрэтнага ключа)
GET:/api/settings/audio.page.vol:1601312252:49936
Стварыце HMAC з паролем і радком уводу HMAC з дапамогай SHA-256:
Вывад HMAC напрample: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8
Стандартная аўтэнтыфікацыя без карыснай нагрузкі, напрampль:

 Базавы запыт аўтэнтыфікацыі

Гэты метад аўтэнтыфікацыі трэба выкарыстоўваць асцярожна, бо ён менш бяспечны, чым стандартны метад.

Аўтарызацыя: базавая [base64]
Exampль:
Аўтарызацыя: базавая YWRtaW46YWxnbwo=
Базавая аўтэнтыфікацыя напрampль:

КАМАНДЫ

 Каманды RESTful API

Ніжэй прыведзены спіс усіх падтрымоўваных каманд API.

Заўвага
Запыт PUT змяняе або стварае пастаянны рэсурс, які захоўваецца пасля перазагрузкі, у той час як запыт POST кіруе прыладай толькі на працягу бягучага сеансу.

Апісанне	Метад	URI	Карысная нагрузка Параметры	Вярнуцца Example	Прадукт	FW
Атрымаць значэнне пэўнага параметра.	АТРЫМАЦЬ	/api/settings/[імя-ключа] Напрыклад/api/settings/audio.page.vol	Н/Д	{“audio.page.vol”: “-18 дБ”}	Усе	> 3.3
Вярнуць узровень навакольнага шуму, вымераны ў дэцыбелах. Кампенсацыя навакольнага шуму павінна быць уключана ва ўкладцы "Асноўныя налады" -> "Функцыі".	АТРЫМАЦЬ	/api/info/audio.noise.level	Н/Д	{“audio.noise.level”: 72}	Дынамікі Дысплей Дынамікі	> 3.3
Атрымайце стан рэлейнай уваходнай клемы.	АТРЫМАЦЬ	/api/info/input.relay.status	Н/Д	{“input.relay.status”: “прастой”} або {“input.relay.status”: “актыўны”}	Усе прадукты з рэлейным уваходам, акрамя 8063. Гл. ніжэй.	> 4.1
Атрымлівайце статус клеммаў Уваход 1 або Уваход 2.	АТРЫМАЦЬ	/api/info/input.relay1.status або /api/info/input.relay2.status	Н/Д	{“input.relay1.status”: “прастой”} або {“input.relay1.status”: “актыўны”}	8063	> 4.1
Атрымаць спіс тонаў files усталяваны ў цяперашні час.	АТРЫМАЦЬ	/api/info/tonelist	Н/Д	{“tonelist”:[“bell-na.wav”,”bell uk.wav”,”buzzer.wav”,…]}	Усе	> 5.0
Атрымаць інфармацыю аб прыладзе, якая адлюстроўваецца на старонцы стану.	АТРЫМАЦЬ	/api/інфармацыя/статус	Н/Д	Поўны спіс інфармацыі з укладкі "Стан".	Усе	> 5.4

Атрымаць інфармацыю аб прадукце, якая адлюстроўваецца на старонцы Аб.	АТРЫМАЦЬ	/api/інфармацыя/пра	Н/Д	Уся інфармацыя знаходзіцца на ўкладцы Аб.	Усе	> 5.4
Актывуйце страбаскоп з патрэбнымі параметрамі колеру і малюнка.	ПОСТ	/api/controls/strobe/start	узор: {0 - 15} color1: {сіні, чырвоны, бурштынавы, зялёны} color2: {сіні, чырвоны, бурштынавы, зялёны} ledlvl: {1 – 255} захаванне: {true, false}	Н/Д	8128(G2) 8138 8190S	> 3.3
Спыніць строб.	ПОСТ	/api/controls/strobe/stop	Н/Д	Н/Д	8128(G2) 8138 8190S	> 3.3
Прайграйце тон адзін раз або закруціце яго.	ПОСТ	/api/controls/tone/start	шлях: {тон} г. зн. перазвон.wav цыкл: {true, false} або {0, 1} напрыклад, {“path”:”chime.wav”, “loop”:true}	Н/Д	Дынамікі 8301 8373 8028(G2) 8201 8039	> 3.3
Спыніць тон.	ПОСТ	/api/controls/tone/stop	Н/Д	Н/Д	Дынамікі 8301 8373 8028(G2) 8201 8039	> 3.3
Патэлефануйце на дадатковы тэлефон з загадзя запісаным паведамленнем.	ПОСТ	/api/controls/call/start	{“пашырэнне”:”2099″, “tone”:”gong.wav”, “interval”:”0″, “maxdur”:”10″}	Н/Д	Дынамікі 8301 8410 8420	> 3.3
Скончыць размову.	ПОСТ	/api/controls/call/stop	Н/Д	Н/Д	Дынамікі 8301 8410 8420	> 3.3

Ініцыяваць аднабаковы выклік старонкі. Прылада атрымае аўдыёпаток ад мэтавага пашырэння.	ПОСТ	/api/controls/call/page	{“пашырэнне”:” ”}	Н/Д	Дынамікі 8410 8420	> 5.3.4
Перазагрузіце мэтавую канечную кропку.	ПОСТ	/api/controls/reboot	Н/Д	Н/Д	Усе	> 3.3
Адамкніце дзверы. «local» кіруе мясцовым рэле «netdc1» кіруе кантролерам дзвярэй аддаленай сеткі (8063)	ПОСТ	/api/controls/door/unlock	doorid: {лакальны, netdc1} * Неабавязкова	Н/Д	8039 8028(G2) 8201 8063	> 3.3
Замкнуць дзверы.	ПОСТ	/api/controls/door/lock	doorid: {лакальны, netdc1} * Неабавязкова	Н/Д	8039 8028(G2) 8201 8063	> 3.3
Уключыце рэле дапаможнага выхаду 24 В.	ПОСТ	API/кантроль/24v/уключыць	Н/Д	Н/Д	8063	> 5.0
Адключыце дапаможнае рэле выхаду 24 В.	ПОСТ	API/кантроль/24v/адключыць	Н/Д	Н/Д	8063	> 5.0
Уключыце выходнае рэле.	ПОСТ	/api/controls/relay/enable	Н/Д	Н/Д	8063	> 5.0
Адключыце выходнае рэле.	ПОСТ	/api/controls/relay/disable	Н/Д	Н/Д	8063	> 5.0
Праверце апошнюю версію прашыўкі на серверы прашыўкі Algo.	ПОСТ	/api/controls/upgrade/check	Н/Д	{“версія”: “абноўлена”} або {“версія”: “ ”}	Усе	> 4.1
Праверце на серверы прашыўкі Algo апошнюю версію прашыўкі і абнавіце яе да гэтай версіі.	ПОСТ	/api/controls/upgrade/start	Н/Д	{“статус”: “абноўлена”} або {“статус”: “абнаўленне ”, “url»: url>} або {“статус”: “ ”}	Усе	> 4.1
Паказаць малюнак або ўзор на экране.	ПОСТ	/api/controls/screen/start	Глядзіце ніжэй	Н/Д	8410 8420	> 5.3.4
Спыніць шаблон экрана і вярнуцца да экрана па змаўчанні.	ПОСТ	/api/controls/screen/stop	Н/Д	Н/Д	8410 8420	> 5.3.4

Перазапусціце галоўнае прыкладанне.	ПОСТ	/api/controls/reload	Н/Д	Н/Д	Усе	> 5.3.4
Пачніце праслухоўванне прамога аўдыёпатоку. Наладзьце нумар порта, на які адпраўляецца паток.	ПОСТ	/api/controls/rx/старт	{“порт”: }	Н/Д	Усе	> 5.3.4
Спыніце праслухоўванне прамога аўдыёпатоку.	ПОСТ	/api/controls/rx/stop	Н/Д	Н/Д	Усе	> 5.3.4
Усталюйце рэжым шматадраснай перадачы.	ПАСЛАДЗІЦЬ	/api/стан/mcast/абнаўленне/	{“mode”:”адпраўшчык”, “адрас”: , «порт»: , “type”:”rtp”} або {“mode”:”sender”, “address”: , «порт»: , “type”:”poly”, “group”:1} **Заўвага**: Калі перад гэтай камандай выкарыстоўваюцца элементы кіравання/тон/запуск, гук будзе прайгравацца з выкарыстаннем бягучых налад на web UI.	Н/Д	8301	> 5.0
Устаўце значэнне ў пэўны параметр з карыснай нагрузкі JSON.	ПАСЛАДЗІЦЬ	/api/налады	параметр: {значэнне} напрыклад, {“audio.page.vol”: “-3dB”}	Н/Д	8180(G2) 8186 8190 8190S 8301 8373	> 3.3

 Каманды простага інтэрфейсу кіравання (SCI).

Усе каманды SCI з'яўляюцца запытамі GET і маюць агульныя параметры «usi» і «admin» для аўтэнтыфікацыі.
Exampль:
АТРЫМАЦЬ http:// /sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local

Апісанне	URI	Дадатковы Карысная нагрузка Параметры	прадукты	FW
Адамкніце дзверы. «local» кіруе лакальным рэле «netdc1» кіруе кантролерам дзвярэй аддаленай сеткі (8063)	/sci/controls/do or/unlock	doorid: {лакальны, netdc1} * Неабавязкова	8039 8028(G2) 8201 8063	> 3.3
Замкнуць дзверы.	/sci/controls/do or/lock	doorid: {лакальны, netdc1} * Неабавязкова	8039 8028(G2) 8201 8063	> 3.3
Прайграйце тон адзін раз або закруціце яго.	/sci/controls/to ne/start	шлях: {тон} г. зн. перазвон.wav цыкл: {true, false} або {0, 1}	Усе	> 3.3
Спыніць тон.	/sci/controls/to ne/stop	Н/Д	Усе	> 3.3
Актывуйце страбаскоп з патрэбнымі параметрамі колеру і малюнка.	/sci/controls/strobe/start	узор: {0 – 15} колер1: {сіні, чырвоны, бурштынавы, зялёны} color2: {сіні, чырвоны, бурштынавы, зялёны} ledlvl: {1 – 255} захаванне: {ісціна, ілжыва}	8128(G2) 8138 8190S	> 3.3
Спыніць строб.	/sci/controls/strobe/stop	Н/Д	8128(G2) 8138 8190S	> 3.3

Дакументы / Рэсурсы

	ALGO RESTful API [pdfКіраўніцтва карыстальніка AL061-GU-GF000API-001-R0, AL061-GU-CP00TEAM-001-R0, RESTful API, RESTful, API
	ALGO RESTful API [pdfКіраўніцтва карыстальніка AL061-GU-CP000API-230717, RESTful API, RESTful, API

Спасылкі

• Кіраўніцтва карыстальніка