ALGO RESTful API

Produktaj Informoj: RESTful API-Gvidilo

La Algo RESTful API permesas al uzantoj aliri, manipuli kaj ekigi agojn pri Algo IP Endpoints en ilia reto per HTTP/HTTPS-petoj. Ĉi tiu dokumento provizas unuforman kaj antaŭdifinitan aron de sennaciaj operacioj, kiuj povas esti uzataj por interagi kun Algo-aparatoj. La API subtenas HTTP/HTTPS GET, POST, kaj PUT petojn kun JSON-utilaj ŝarĝoj.

Aŭtentikigo

Estas tri specoj de aŭtentikigoj disponeblaj kun la Algo RESTful API:

• Norma aŭtentigo (aktivigita defaŭlte)
• Baza aŭtentigo (laŭvola)
• Neniu aŭtentikigmetodo (ne rekomendita; nur por testaj celoj)

Instrukcioj pri Uzado de Produktoj: RESTful API

Antaŭkondiĉoj

Antaŭ ol ebligi la RESTful-API, certigu, ke la aparato havas interretan konekton por atingi la antaŭkonfiguritajn NTP-servilojn. Se neniu interreta konekto disponeblas, agordu lokan NTP-servilon kaj enigu ĝian IP-adreson.

Ebligante la RESTful API

1. Ensalutu en la aparaton web interfaco kaj navigu al la langeto Administranto de Altnivelaj Agordoj.
2. Rulumu malsupren al la sekcio de Subteno de API kaj ebligu la RESTful API.
3. Agordu la deziratan pasvorton (defaŭlta pasvorto: algo). Notu, ke norma aŭtentigo estas ebligita defaŭlte.

Ebligi Bazan Aŭtentigon (Laŭvola)

1. En la web interfaco, navigu al la langeto Sistemo Prizorgado kaj elŝutu la agordon file.
2. Malfermu la agordon file per iu ajn tekstredaktilo kaj aldonu la jenan linion: api.auth.basic = 1
3. Konservu kaj alŝutu la modifitan agordon file reen al la aparato uzante la Restarigi Agordon File funkcio en la langeto Sistemo Prizorgado.

Ebligi Neniun Aŭtentigan Metodon (Laŭvola)

Por ebligi la sen-aŭtentikigmetodon, lasu la kampon de RESTful API Pasvorto malplena. Ĉi tiu metodo ne estas rekomendita kaj devus esti uzata nur por testaj celoj ĉar ĝi ne provizas sekurecon.

Ebligi Simplan Kontrolan Interfacon (Laŭvola)

1. Sur la web interfaco, navigu al la langeto Sistemo Prizorgado kaj elŝutu la agordon file.
2. Malfermu la agordon file uzante tekstredaktilon kaj aldonu du liniojn. Ŝanĝu la pasvorton al via dezirata.
3. Admin.web.sci = 1
4. Sci.admin.pwd =
5. Konservu kaj alŝutu la modifitan agordon file reen al la aparato uzante la Restarigi Agordon File funkcio en la langeto Sistemo Prizorgado.

Aŭtentikigo Sample Kodo

Bonvolu retpoŝti support@algosolutions.com se vi ŝatus norman aŭ bazan aŭtentikigon sample kodo.
Por plia subteno, voku 604-454-3792 aŭ retpoŝto support@algosolutions.com

Informaj Notoj

Notu
Noto indikas utilajn ĝisdatigojn, informojn kaj instrukciojn, kiujn oni devas sekvi

Malgarantio

La informoj enhavitaj en ĉi tiu dokumento estas kredita esti preciza en ĉiuj rilatoj sed ne estas garantiita de Algo. La informoj estas ŝanĝeblaj sen avizo kaj ne devus esti iel ajn konsiderataj kiel devontigo de Algo aŭ iu ajn el ĝiaj filioj aŭ filioj. Algo kaj ĝiaj filioj kaj filioj prenas neniun respondecon pri iuj eraroj aŭ preterlasoj en ĉi tiu dokumento. Revizioj de ĉi tiu dokumento aŭ novaj eldonoj de ĝi povas esti eldonitaj por enkorpigi tiajn ŝanĝojn. Algo supozas neniun respondecon por damaĝoj aŭ asertoj rezultantaj de iu ajn uzo de ĉi tiu manlibro aŭ tiaj produktoj, programaro, firmvaro kaj/aŭ aparataro. Neniu parto de ĉi tiu dokumento povas esti reproduktita aŭ transdonita en ajna formo aŭ per iu ajn rimedo - elektronika aŭ mekanika - por ajna celo sen skriba permeso de Algo.
Por pliaj informoj aŭ teknika helpo en Nordameriko, bonvolu kontakti la subtenan teamon de Algo:

Algo Teknika Subteno
1-604-454-3792
support@algosolutions.com

©2022 Algo estas registrita varmarko de Algo Communication Products Ltd.
Ĉiuj rajtoj rezervitaj. Ĉiuj aliaj varmarkoj estas la posedaĵo de siaj respektivaj posedantoj. Ĉiuj specifoj povas ŝanĝi sen avizo.

 ĜENERALA

Enkonduko

Ĉi tiu dokumento priskribas kiel Algo RESTful API povas esti uzata por aliri, manipuli kaj ekigi agojn sur Algo IP Endpoints en via reto per HTTP/HTTPS-petoj, kaj ankaŭ kelkajn malsamajn aŭtentigajn metodojn kun diversaj niveloj de sekureco. Petantaj sistemoj povas interagi kun Algo-aparatoj per unuforma kaj antaŭdifinita aro de sennaciaj operacioj difinitaj en ĉi tiu dokumento. Petoj estas faritaj al la URI de rimedo kun JSON-utila ŝarĝo kaj ellogas JSON-respondon. HTTP/HTTPS GET, POST, kaj PUT petoj estas faritaj al rimedo URI kune kun la JSON-utila ŝarĝo (vidu komandsekcion por listo de utilaj ŝarĝoj).

 Aŭtentikigo

Estas tri specoj de aŭtentikigoj:

•  Normo (rekomendita)
•  Baza
•  Neniu (ne rekomendita)

La Norma konfirmo uzas Hash-bazitan Message Authentication Code (HMAC) kun SHA-256 kodita digesto. Baza aŭtentikigo uzas Base64-kodigon kaj devus esti uzata nur per HTTPS. Neniu aŭtentikigo devas esti uzata nur kun ekstrema zorgo ĉar ĝi ne provizas aŭtentikigon. Vidu la sekcion de Aŭtentigaj Postuloj por pliaj detaloj.

AJRO KAJ AGRAGO

Antaŭkondiĉoj

•  Ĉi tiu dokumento supozas, ke la finpunkto de Algo funkcias firmware-versio 3.3 aŭ pli alta.
•  La tempodiferenco inter la petanto kaj la Algo-aparatoj devus esti malpli ol 30 sekundoj por uzi norman aŭtentikigon.
• Certigu ke NTP (Network Time Protocol) estas uzata. La adresoj de kutimaj NTP-serviloj povas esti agorditaj en la langeto Altnivelaj Agordoj → Tempo.

Notu
La antaŭkonfiguritaj NTP-serviloj estas publike gastigitaj, tial interreta konekto estas postulata por atingi ĝin. Se neniu interreta konekto disponeblas, agordu lokan NTP-servilon kaj enigu ĝian IP-adreson.

• Certigu, ke la tempo de la sistemo de la aparato Algo estas ĝustigita al la ĝusta horzono. Ĉi tio povas esti farita navigante al la Altnivelaj Agordoj → Tempo langeto.

 Ebligante la RESTful API

1. Ensalutu en la web interfaco kaj navigu al la Altnivelaj Agordoj → Admin langeto.
2. Rulumu malsupren al la sekcio de Subteno de API, ebligu la RESTful API kaj agordu la Pasvorton laŭdezire (defaŭlta pasvorto: algo)
   Notu
   Norma aŭtentigo estas ebligita defaŭlte.

Ebligu Bazan Aŭtentigon (Laŭvola)

1. En la web interfaco, navigu al la langeto Sistemo → Prizorgado kaj elŝutu la agordon file.
2. Malfermu la agordon file per iu ajn tekstredaktilo kaj aldonu la jenan linion: api.auth.basic = 1
3.  Konservu kaj alŝutu la modifitan agordon file reen al la aparato uzante la Restarigi Agordon File funkcio en la langeto Sistemo → Prizorgado.

Neniu Aŭtentikiga Metodo (Laŭvola)

Por ebligi la sen-aŭtentikigmetodon, lasu la kampon de RESTful API Pasvorto malplena. Ĉi tiu metodo ne estas rekomendita kaj devus esti uzata nur por testaj celoj ĉar ĝi ne provizas sekurecon.

Ebligi Simplan Kontrolan Interfacon (Laŭvola)

1. Sur la web interfaco, navigu al la langeto Sistemo → Prizorgado kaj elŝutu la agordon file.
2.  Malfermu la agordon file uzante tekstredaktilon kaj aldonu du liniojn. Ŝanĝu la al via dezirata pasvorto. Admin.web.sci = 1
   Sci.admin.pwd =
3.  Konservu kaj alŝutu la modifitan agordon file reen al la aparato uzante la Restarigi Agordon File funkcio en la langeto Sistemo → Prizorgado.

AUTENTIKAJ POSTULOJ

Bonvolu retpoŝti support@algosolutions.com se vi ŝatus norman aŭ bazan aŭtentikigon sample kodo.

Norma Aŭtentiga Peto kun JSON Utila Ŝarĝo

Bezonataj kaplinioj en HTTP/HTTPS-peto
> Enhavo-Tipo: "aplikaĵo/json"
> Enhavo-MD5: [content_md5] Ekzample
Content-MD5: 74362cc86588b2b3c5a4491baf80375b

Rajtigo: hmac admin:[nonce]:[hmac_output]
La rajtigaj kaplinioj konsistas el:

1. La ĉeno 'hmac admin' sekvata de dupunkto ':'.
2. Nonce – Hazarda aŭ ne-ripetanta valoro, sekvata de dupunkto ':'.
3. Hmac_output - generita de la RESTful API Pasvorto (sekreta ŝlosilo) agordita en via aparato kaj la HMAC-enigo, kiel sube:
   [request_method]:[request_uri]:[content_md5]:[content_type]:[tempoplejamp]:[neniu]

HMAC-enigo ekzample: (uzante 'algo' kiel la sekretan ŝlosilon)
POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 Generu HMAC kun pasvorto kaj HMAC-eniga ĉeno kiel digesto uzante SHA-256:
HMAC-eligo ekzample: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

Dato: tago, dato monato, jaro hr:min:sec GMT
Example
Dato: ĵaŭ, 22 septembro 2022 02:33:07 GMT
Norma aŭtentigo kun utila ŝarĝo ekzample:

 Norma Peto de Aŭtentigo Sen JSON-Utilŝarĝo

Identa al 3.1 kun enhavo rilataj kaplinioj/hmac-enigo preterlasita.
HMAC-enigo: [request_method]:[request_uri]:[timestamp]:[neniu] HMAC-enigo ekzample: (uzante 'algo' kiel la sekretan ŝlosilon)
GET:/api/settings/audio.page.vol:1601312252:49936
Generu HMAC per pasvorto kaj HMAC-eniga ĉeno uzante SHA-256:
HMAC-eligo ekzample: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8
Norma aŭtentigo sen utila ŝarĝo ekzample:

 Baza Aŭtentiga Peto

Ĉi tiu metodo de aŭtentigo devas esti uzata zorge ĉar ĝi estas malpli sekura ol la norma metodo.

Rajtigo: Baza [bazo64]
Example:
Rajtigo: Baza YWRtaW46YWxnbwo=
Baza aŭtentigo ekzample:

KOMANDOJ

 RESTfulaj API-Komandoj

Malsupre estas listo de ĉiuj subtenataj API-komandoj.

Notu
PUT-peto ŝanĝas aŭ kreas konstantan rimedon, kiu postvivas rekomencon, dum POST-peto nur kontrolas la aparaton por la nuna sesio.

Priskribo	Metodo	URI	Utila ŝarĝo Parametroj	Revenu Example	Produkto	FW
Prenu la valoron de specifa parametro.	GET	/api/settings/[ŝlosilnomo] Ekz./api/settings/audio.page.vol	N/A	{“audio.page.vol”: “-18dB”}	Ĉiuj	> 3.3
Redonu la ĉirkaŭan brunivelon mezurita en decibeloj. Ĉirkaŭa Brua Kompenso devas esti ebligita en Bazaj Agordoj -> Trajtoj langeto.	GET	/api/info/audio.noise.level	N/A	{“audio.noise.level”: 72}	Parolantoj Montru Parolantoj	> 3.3
Eltiru la staton de la relajsa eniga terminalo.	GET	/api/info/input.relay.status	N/A	{“input.relay.status”: “neaktiva”} aŭ {“input.relay.status”: “aktiva”}	Ĉiuj produktoj kun relajsa enigo, krom la 8063. Vidu sube.	> 4.1
Eltiru la staton de Enigo 1 aŭ Enigo 2-terminaloj.	GET	/api/info/input.relay1.status aŭ /api/info/input.relay2.status	N/A	{“input.relay1.status”: “neaktiva”} aŭ {“input.relay1.status”: “aktiva”}	8063	> 4.1
Prenu la liston de tonoj files nuntempe instalitaj.	GET	/api/info/tonelist	N/A	{“tonelist”:[“sonorilo-na.wav”,”sonorilo uk.wav”,”buzzer.wav”,…]}	Ĉiuj	> 5.0
Reakiru la aparatajn informojn, kiuj estas montrataj sur la paĝo de Statuso.	GET	/api/info/status	N/A	Plena listo de informoj de la langeto Statuso.	Ĉiuj	> 5.4

Prenu la produktajn informojn, kiuj estas montrataj sur la paĝo Pri.	GET	/api/info/pri	N/A	Ĉiuj informoj ĉeestas sur la langeto Pri.	Ĉiuj	> 5.4
Aktivigu la stroboskopon per dezirataj koloraj kaj ŝablono-parametroj.	POST	/api/controls/strobe/start	ŝablono: {0 – 15} koloro1: {blua, ruĝa, sukcena, verda} koloro2: {blua, ruĝa, sukcena, verda} ledlvl: {1 – 255} restaĵo: {vera, malvera}	N/A	8128 (G2) 8138 8190S	> 3.3
Ĉesu la stroboskopon.	POST	/api/controls/strobe/stop	N/A	N/A	8128 (G2) 8138 8190S	> 3.3
Ludu tonon unufoje aŭ buklo ĝin.	POST	/api/controls/tone/start	vojo: {tono} t.e. sonorilo.wav buklo: {vera, malvera} aŭ {0, 1} ekz. {“pado”:”chime.wav”, “buklo”:vera}	N/A	Parolantoj 8301 8373 8028 (G2) 8201 8039	> 3.3
Ĉesu la tonon.	POST	/api/controls/tone/stop	N/A	N/A	Parolantoj 8301 8373 8028 (G2) 8201 8039	> 3.3
Voku telefonan etendon kun antaŭregistrita mesaĝo.	POST	/api/controls/call/start	{“etendo”:”2099″, “tono”:”gong.wav”, “intervalo”:”0″, “maxdur”:”10″}	N/A	Parolantoj 8301 8410 8420	> 3.3
Finu la vokon.	POST	/api/controls/call/stop	N/A	N/A	Parolantoj 8301 8410 8420	> 3.3

Komencu unudirektan paĝan vokon. La aparato ricevos la sonfluon de cela etendo.	POST	/api/controls/call/page	{“etendo”:” ”}	N/A	Parolantoj 8410 8420	> 5.3.4
Rekomencu la celan finpunkton.	POST	/api/controls/reboot	N/A	N/A	Ĉiuj	> 3.3
Malŝlosu la pordon. "loka" regas la lokan relajson "netdc1" regas la malproksiman retan pordoregilon (8063)	POST	/api/controls/door/unlock	pordo: {loka, netdc1} * Nedeviga	N/A	8039 8028 (G2) 8201 8063	> 3.3
Ŝlosu la pordon.	POST	/api/controls/door/lock	pordo: {loka, netdc1} * Nedeviga	N/A	8039 8028 (G2) 8201 8063	> 3.3
Ebligu la 24v aux-elira relajso.	POST	api/controls/24v/enable	N/A	N/A	8063	> 5.0
Malŝaltu la 24v-aŭkson ekstere relajso.	POST	api/controls/24v/disable	N/A	N/A	8063	> 5.0
Ebligu la eligan relajson.	POST	/api/controls/relay/enable	N/A	N/A	8063	> 5.0
Malebligu la eligan relajson.	POST	/api/controls/relay/disable	N/A	N/A	8063	> 5.0
Kontrolu la firmware-servilon de Algo por la plej nova firmware-versio.	POST	/api/controls/upgrade/check	N/A	{“versio”: “ĝisdatigita”} aŭ {“versio”: “ ”}	Ĉiuj	> 4.1
Kontrolu la firmware-servilon de Algo por la plej nova firmware-versio kaj ĝisdatigu al tiu versio.	POST	/api/controls/upgrade/start	N/A	{“stato”: “ĝisdatigita”} aŭ {“status”: “ĝisdatigo ", "url”: url>> aŭ {"statuso": " ”}	Ĉiuj	> 4.1
Montru bildon aŭ ŝablonon sur la ekrano.	POST	/api/controls/screen/start	Vidu malsupre	N/A	8410 8420	> 5.3.4
Haltu la ekranan ŝablonon kaj revenu al la defaŭlta ekrano.	POST	/api/controls/screen/stop	N/A	N/A	8410 8420	> 5.3.4

Rekomencu la ĉefan aplikaĵon.	POST	/api/controls/reload	N/A	N/A	Ĉiuj	> 5.3.4
Komencu aŭskulti rektan aŭdan fluon. Agordu la havenan numeron al kiu la fluo estas sendata.	POST	/api/controls/rx/start	{"haveno": }	N/A	Ĉiuj	> 5.3.4
Ĉesu aŭskulti rektan aŭdan fluon.	POST	/api/controls/rx/stop	N/A	N/A	Ĉiuj	> 5.3.4
Agordu la multielsendan reĝimon.	METU	/api/state/mcast/update/	{“reĝimo”:”sendinto”, “adreso”: , "haveno": , “tipo”:”rtp”} aŭ {“reĝimo”:”sendinto”, “adreso”: , "haveno": , "tipo":"poli", "grupo":1} **Noto**: Se kontroloj/tono/komenco estas uzataj antaŭ ĉi tiu komando, la tono ludos uzante nunajn agordojn sur la web UI.	N/A	8301	> 5.0
Enigu valoron al specifa parametro de JSON-utila ŝarĝo.	METU	/api/settings	parametro: {valoro} ekz. {“audio.page.vol”: “-3dB”}	N/A	8180 (G2) 8186 8190 8190S 8301 8373	> 3.3

 Simplaj Kontrolaj Interfaco (SCI) Komandoj

Ĉiuj SCI-komandoj estas GET-petoj kaj havas la komunajn parametrojn "usi" kaj "admin" por aŭtentigo.
Example:
AKIU http:// /sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local

Priskribo	URI	Pliaj Utila ŝarĝo Parametroj	Produktoj	FW
Malŝlosu la pordon. "loka" regas la lokan relajson "netdc1" regas la malproksiman retan pordoregilon (8063)	/sci/controls/do aŭ/malŝlosu	pordo: {loka, netdc1} * Nedeviga	8039 8028 (G2) 8201 8063	> 3.3
Ŝlosu la pordon.	/sci/controls/do aŭ/ŝlosu	pordo: {loka, netdc1} * Nedeviga	8039 8028 (G2) 8201 8063	> 3.3
Ludu tonon unufoje aŭ buklo ĝin.	/sci/controls/to ne/komenci	vojo: {tono} t.e. sonorilo.wav buklo: {vera, malvera} aŭ {0, 1}	Ĉiuj	> 3.3
Ĉesu la tonon.	/sci/controls/to ne/halti	N/A	Ĉiuj	> 3.3
Aktivigu la stroboskopon per dezirataj koloraj kaj ŝablono-parametroj.	/sci/controls/strobe/start	ŝablono: {0 – 15} koloro1: {blua, ruĝa, sukcena, verda} koloro2: {blua, ruĝa, sukcena, verda} ledlvl: {1 – 255} restaĵo: {vera, malvera}	8128 (G2) 8138 8190S	> 3.3
Ĉesu la stroboskopon.	/sci/controls/strobe/stop	N/A	8128 (G2) 8138 8190S	> 3.3

Dokumentoj/Rimedoj

	ALGO RESTful API [pdf] Uzantogvidilo AL061-GU-GF000API-001-R0, AL061-GU-CP00TEAM-001-R0, RESTful API, RESTful, API
	ALGO RESTful API [pdf] Uzantogvidilo AL061-GU-CP000API-230717, RESTful API, RESTful, API

Referencoj

• Uzanto Manlibro