API ALGO RESTful

Informazione di u produttu: RESTful API Guide

L'API Algo RESTful permette à l'utilizatori di accede, manipulà è attivà l'azzioni nantu à l'Algo IP Endpoints nantu à a so reta attraversu richieste HTTP / HTTPS. Stu documentu furnisce un inseme uniforme è predefinitu di operazioni senza statu chì ponu esse usatu per interagisce cù i dispositi Algo. L'API supporta richieste HTTP/HTTPS GET, POST è PUT cù carichi JSON.

Autentificazione

Ci sò trè tippi di autentificazione dispunibuli cù l'API Algo RESTful:

• Autentificazione standard (attivata per difettu)
• Autentificazione basica (opzionale)
• Nisun metudu di autentificazione (micca cunsigliatu; solu per scopi di prova)

Istruzzioni per l'usu di u produttu: API RESTful

Prerequisites

Prima di attivà l'API RESTful, assicuratevi chì u dispusitivu hà una cunnessione Internet per ghjunghje à i servitori NTP pre-configurati. Se ùn ci hè micca una cunnessione Internet dispunibule, cunfigurà un servitore NTP locale è inserite u so indirizzu IP.

Abilitazione di l'API RESTful

1. Entra in u dispusitivu web interfaccia è navigate à a tabulazione Admin Settings Advanced.
2. Scroll down to the API Support section and enable the RESTful API.
3. Definite a password desiderata (password predeterminata: algo). Nota chì l'autentificazione standard hè attivata per automaticamente.

Abilitazione di l'autentificazione basica (opcional)

1. In u web interfaccia, navigate à a tabulazione Mantenimentu di u Sistema è scaricate a cunfigurazione file.
2. Apri a cunfigurazione file cù qualsiasi editore di testu è aghjunghje a seguente linea: api.auth.basic = 1
3. Salvà è carica a cunfigurazione mudificata file torna à u dispusitivu utilizendu a Configurazione Risturà File funzione in a tabulazione Mantenimentu di u Sistema.

Abilitazione senza Metudu di Autentificazione (Opzionale)

Per attivà u metudu senza autentificazione, lasciate u campu RESTful API Password viotu. Stu metudu ùn hè micca cunsigliatu è deve esse usatu solu per scopi di prova solu perchè ùn furnisce micca sicurità.

Abilitazione di l'interfaccia di cuntrollu simplice (opcional)

1. Nantu à u web interfaccia, navigate à a tabulazione Mantenimentu di u Sistema è scaricate a cunfigurazione file.
2. Apri a cunfigurazione file usendu un editore di testu è aghjunghje duie linee. Cambia a password di u vostru desideriu.
3. Admin.web.sci = 1
4. Sci.admin.pwd =
5. Salvà è carica a cunfigurazione mudificata file torna à u dispusitivu utilizendu a Configurazione Risturà File funzione in a tabulazione Mantenimentu di u Sistema.

L'autenticazione Sampu codice

Per piacè email support@algosolutions.com se vulete una autenticazione standard o basica sampu codice.
Per supportu supplementu, chjamate 604-454-3792 o email support@algosolutions.com

Avvisi d'infurmazione

Nota
Nota indica l'aghjurnamenti utili, l'infurmazioni è l'istruzzioni chì deve esse seguitu

Disclaimer

L'infurmazione cuntenuta in stu documentu hè ritenuta precisa in tutti i rispetti, ma ùn hè micca garantita da Algo. L'infurmazione hè sottumessa à cambià senza avvisu è ùn deve esse interpretata in alcun modu cum'è un impegnu da Algo o qualsiasi di i so affiliati o filiali. Algo è i so affiliati è filiali ùn assumanu alcuna responsabilità per qualsiasi errore o omissioni in stu documentu. Rivisioni di stu documentu o edizioni novi di questu ponu esse emessi per incorpore tali cambiamenti. Algo ùn assume alcuna responsabilità per danni o rivendicazioni risultanti da qualsiasi usu di stu manuale o tali prudutti, software, firmware è / o hardware. Nisuna parte di stu documentu pò esse riproduce o trasmessa in alcuna forma o per qualsiasi mezzu - elettronicu o meccanicu - per qualsiasi scopu senza permessu scrittu da Algo.
Per informazioni supplementari o assistenza tecnica in l'America di u Nordu, cuntattate u squadra di supportu di Algo:

Assistenza tecnica Algo
1-604-454-3792
support@algosolutions.com

©2022 Algo hè una marca registrata di Algo Communication Products Ltd.
Tutti i diritti riservati. Tutti l'altri marchi sò a pruprietà di i so rispettivi pruprietarii. Tutte e specifiche sò sottumessi à cambià senza avvisu.

 GENERALI

Introduzione

Stu documentu descrive cumu l'API Algo RESTful pò esse aduprata per accede, manipulà è attivà l'azzioni nantu à l'Algo IP Endpoints in a vostra reta attraversu richieste HTTP / HTTPS, è ancu un coppiu di metudi di autentificazione diffirenti cù diversi livelli di sicurità. I sistemi di dumanda ponu interagisce cù i dispositi Algo attraversu un inseme uniforme è predefinitu di operazioni senza statu definite in stu documentu. E dumande sò fatte à l'URI di una risorsa cù una carica JSON è suscitanu una risposta JSON. E richieste HTTP / HTTPS GET, POST, è PUT sò fatte à l'URI di risorsa cù a carica JSON (vede a sezione di cumandamenti per una lista di carichi).

 Autentificazione

Ci sò trè tippi di autentificazione:

•  Standard (consigliatu)
•  Basic
•  Nisunu (micca cunsigliatu)

L'autentificazione Standard usa un Codice di Autentificazione di Messaghju basatu in Hash (HMAC) cun un digest codificato SHA-256. L'autentificazione basica usa a codificazione Base64 è deve esse usata solu nantu à HTTPS. Nisuna autentificazione ùn deve esse usata solu cun cura estrema perchè ùn furnisce micca autentificazione. Vede a sezione Requisiti di autenticazione per più dettagli.

SETUP È CONFIGURAZIONE

Prerequisites

•  Stu documentu assume chì l'endpoint Algo esegue a versione di firmware 3.3 o superiore.
•  A diffarenza di tempu trà u dumanda è i dispusitivi Algo deve esse menu cà 30 seconde à aduprà autentificazione standard.
• Assicuratevi chì NTP (Network Time Protocol) hè in usu. L'indirizzi di i servitori NTP persunalizati ponu esse cunfigurati in a tabulazione Advanced Settings → Time.

Nota
I servitori NTP pre-configurati sò pubblicamente ospitati, per quessa, a cunnessione Internet hè necessaria per ghjunghje. Se ùn ci hè micca una cunnessione Internet dispunibule, cunfigurà un servitore NTP locale è inserite u so indirizzu IP.

• Assicurà u tempu sistemu dispusitivu Algo hè aghjustatu à u fusu tempu currettu. Questu pò esse fattu navigendu à a tabulazione Advanced Settings → Time.

 Abilitazione di l'API RESTful

1. Entra in u web interfaccia è navigate à l'Configurazione Avanzata → Tabulazione Admin.
2. Scroll down to the API Support section, attivate l'API RESTful è stabilisce a Password cum'è desiderate (password predeterminata: algo)
   Nota
   L'autentificazione standard hè attivata per difettu.

Habilita l'autenticazione basica (opcional)

1. In u web interfaccia, navigate à a tabulazione Sistema → Mantenimentu è scaricate a cunfigurazione file.
2. Apri a cunfigurazione file cù qualsiasi editore di testu è aghjunghje a seguente linea: api.auth.basic = 1
3.  Salvà è carica a cunfigurazione mudificata file torna à u dispusitivu utilizendu a Configurazione Risturà File funzione in a tabulazione Sistema → Manutenzione.

Nisun Metudu di Autentificazione (Opzionale)

Per attivà u metudu senza autentificazione, lasciate u campu RESTful API Password viotu. Stu metudu ùn hè micca cunsigliatu è deve esse usatu solu per scopi di prova solu perchè ùn furnisce micca sicurità.

Abilitazione di l'interfaccia di cuntrollu simplice (opcional)

1. Nantu à u web interfaccia, navigate à a tabulazione Sistema → Mantenimentu è scaricate a cunfigurazione file.
2.  Apri a cunfigurazione file usendu un editore di testu è aghjunghje duie linee. Cambia u à a vostra password desiderata. Admin.web.sci = 1
   Sci.admin.pwd =
3.  Salvà è carica a cunfigurazione mudificata file torna à u dispusitivu utilizendu a Configurazione Risturà File funzione in a tabulazione Sistema → Manutenzione.

REQUISITI DI AUTENTICAZIONE

Per piacè email support@algosolutions.com se vulete una autenticazione standard o basica sampu codice.

Richiesta di Autentificazione Standard cù un Payload JSON

Intestazioni necessarie in a dumanda HTTP/HTTPS
> Tipu di cuntenutu: "applicazione/json"
> Content-MD5: [content_md5] Example
Content-MD5: 74362cc86588b2b3c5a4491baf80375b

Autorizazione: hmac admin:[nonce]:[hmac_output]
L'intestazione di l'autorizazione sò cumposti da:

1. A stringa 'hmac admin' seguita da un colon ':'.
2. Nonce - Un valore aleatoriu o micca ripetitivu, seguitu da i punti ":".
3. Hmac_output - generatu da a Password API RESTful (chiave secreta) cunfigurata in u vostru dispositivu è l'input HMAC, cum'è quì sottu:
   [request_method]:[request_uri]:[content_md5]:[content_type]:[timestamp]:[nonce]

Input HMAC example: (usendu 'algo' cum'è a chjave secreta)
POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 Genera HMAC cù password è stringa di input HMAC cum'è digest cù SHA-256:
output HMAC example: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

Data: ghjornu, data mese, annu hr:min:sec GMT
Example
Data: Ghjovi, 22 Settembre 2022 02:33:07 GMT
Autentificazione standard cù payload exampLe:

 Richiesta di autenticazione standard senza una carica JSON

Idèntica à 3.1 cù intestazioni di cuntenutu / input hmac omessi.
Input HMAC: [request_method]:[request_uri]:[timestamp]:[nonce] input HMAC example: (usendu 'algo' cum'è a chjave secreta)
GET:/api/settings/audio.page.vol:1601312252:49936
Generate HMAC cù password è stringa di input HMAC cù SHA-256:
output HMAC example: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8
Autentificazione standard senza payload exampLe:

 Richiesta di autentificazione di basa

Stu metudu di autentificazione deve esse utilizatu cun cura perchè hè menu sicuru ch'è u metudu standard.

Autorizazione: Basic [base64]
ExampLe:
Autorizazione: Basic YWRtaW46YWxnbwo=
Autentificazione basica exampLe:

CUMANDI

 Comandi API RESTful

Quì sottu hè una lista di tutti i cumandamenti API supportati.

Nota
Una dumanda PUT cambia o crea una risorsa permanente chì sopravvive à un reboot, mentri una dumanda POST cuntrola solu u dispusitivu per a sessione attuale.

Descrizzione	Metudu	URI	Payload Parametri	Ritorna Example	Pruduttu	FW
Ritruvà u valore di un paràmetru specificu.	GET	/api/settings/[key-name] Es./api/settings/audio.page.vol	N/A	{“audio.page.vol”: “-18dB”}	Tuttu	> 3.3
Ritorna u livellu di rumore ambientale misuratu in decibels. A compensazione di u rumore ambientale deve esse attivata in Settings Basic -> Features tab.	GET	/api/info/audio.noise.level	N/A	{"audio.noise.level": 72}	Speakers Display Speakers	> 3.3
Estrae u statutu di u terminal d'ingressu di relé.	GET	/api/info/input.relay.status	N/A	{"input.relay.status": "idle"} o {"input.relay.status": "attivu"}	Tutti i prudutti cù un input relay, eccettu u 8063. Vede quì sottu.	> 4.1
Estrae u statu di i terminali Input 1 o Input 2.	GET	/api/info/input.relay1.status o /api/info/input.relay2.status	N/A	{"input.relay1.status": "idle"} o {"input.relay1.status": "attivu"}	8063	> 4.1
Ritruvà a lista di u tonu files attualmente installatu.	GET	/api/info/tonelist	N/A	{“tonelist”:[“bell-na.wav”,”bell uk.wav”,”buzzer.wav”,…]}	Tuttu	> 5.0
Ritruvà l'infurmazione di u dispusitivu chì hè visualizata nantu à a pagina Status.	GET	/api/info/status	N/A	Lista cumpleta di l'infurmazioni da a tabulazione Status.	Tuttu	> 5.4

Recuperate l'infurmazioni di u produttu chì si vede nantu à a pagina About.	GET	/api/info/about	N/A	Tutte l'infurmazioni prisenti nantu à a tabulazione About.	Tuttu	> 5.4
Attivate u stroboscopiu cù i paràmetri di culore è mudellu desiderati.	POST	/api/controls/strobe/start	mudellu: {0 - 15} culore1: {blu, rossu, ambra, verde} culore2: {blu, rossu, ambra, verde} ledlvl: {1 - 255} holdover: {veru, falsu}	N/A	8128 (G2) 8138 8190S	> 3.3
Stop the strobe.	POST	/api/controls/strobe/stop	N/A	N/A	8128 (G2) 8138 8190S	> 3.3
Ghjucà un tonu una volta o loop it.	POST	/api/controls/tone/start	caminu : {tone} ie. chime.wav ciclu: {true, false} o {0, 1} per esempiu {"path":"chime.wav", "loop":true}	N/A	Speakers 8301 8373 8028 (G2) 8201 8039	> 3.3
Ferma u tonu.	POST	/api/controls/tone/stop	N/A	N/A	Speakers 8301 8373 8028 (G2) 8201 8039	> 3.3
Chjamate una estensione di u telefunu cù un missaghju preregistratu.	POST	/api/controls/call/start	{"estensione":"2099", “tone”:”gong.wav”, “interval”:”0″, “maxdur”:”10″}	N/A	Speakers 8301 8410 8420	> 3.3
Finisce a chjama.	POST	/api/controls/call/stop	N/A	N/A	Speakers 8301 8410 8420	> 3.3

Inizià una chjama di pagina unidirezionale. U dispusitivu riceverà u flussu audio da l'estensione di destinazione.	POST	/api/controls/call/page	{"estensione":" ”}	N/A	Speakers 8410 8420	> 5.3.4
Riavvia l'endpoint di destinazione.	POST	/api/controls/reboot	N/A	N/A	Tuttu	> 3.3
Sblocca a porta. "local" cuntrolla u relé locale "netdc1" cuntrolla u cuntrollu di a porta di a rete remota (8063)	POST	/api/controls/door/unlock	doorid: {local, netdc1} * Facultativu	N/A	8039 8028 (G2) 8201 8063	> 3.3
Chjode a porta.	POST	/api/controls/door/lock	doorid: {local, netdc1} * Facultativu	N/A	8039 8028 (G2) 8201 8063	> 3.3
Abilita u relè di uscita aux 24v.	POST	api/controls/24v/enable	N/A	N/A	8063	> 5.0
Disattiva u relè di uscita aux 24v.	POST	api/controls/24v/disable	N/A	N/A	8063	> 5.0
Abilita u relé di output.	POST	/api/controls/relay/enable	N/A	N/A	8063	> 5.0
Disattivate u relè di output.	POST	/api/controls/relay/disable	N/A	N/A	8063	> 5.0
Verificate u servitore di firmware di Algo per l'ultima versione di firmware.	POST	/api/controls/upgrade/check	N/A	{"versione": "aghjurnata"} o {"versione": " ”}	Tuttu	> 4.1
Verificate u servitore di firmware di Algo per l'ultima versione di firmware è aghjurnate à quella versione.	POST	/api/controls/upgrade/start	N/A	{"status": "aghjurnatu"} o {"status": "aghjurnà ", "url": url>> o {"statu": " ”}	Tuttu	> 4.1
Mostra una maghjina o mudellu nantu à u screnu.	POST	/api/controls/screen/start	Vede sottu	N/A	8410 8420	> 5.3.4
Ferma u mudellu di u screnu è torna à u screnu predeterminatu.	POST	/api/controls/screen/stop	N/A	N/A	8410 8420	> 5.3.4

Riavvia l'applicazione principale.	POST	/api/controls/reload	N/A	N/A	Tuttu	> 5.3.4
Cumincià à sente un flussu audio direttu. Configurate u numeru di portu à quale u flussu hè mandatu.	POST	/api/controls/rx/start	{"portu": }	N/A	Tuttu	> 5.3.4
Smetti di sente un flussu audio direttu.	POST	/api/controls/rx/stop	N/A	N/A	Tuttu	> 5.3.4
Stabbilisce u modu multicast.	PUT	/api/state/mcast/update/	{"mode":"mittente", "indirizzu": , "portu": , "type":"rtp"} o {"mode":"mittente", "indirizzu": , "portu": , "tipu": "poli", "gruppu": 1} **Nota**: Se i cuntrolli/tonu/iniziu sò usati prima di stu cumandamentu, u tonu riproducerà utilizendu i paràmetri attuali nantu à u web UI.	N/A	8301	> 5.0
Inserisci un valore à un paràmetru specificu da u payload JSON.	PUT	/api/settings	paràmetru: {valore} per esempiu {"audio.page.vol": "-3dB"}	N/A	8180 (G2) 8186 8190 8190S 8301 8373	> 3.3

 Cumandamenti di l'interfaccia di cuntrollu simplice (SCI).

Tutti i cumandamenti SCI sò richieste GET è anu i paràmetri cumuni "usi" è "admin" per l'autentificazione.
ExampLe:
GET http:// /sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local

Descrizzione	URI	Supplémentaire Payload Parametri	I prudutti	FW
Sblocca a porta. "local" cuntrolla u relé locale "netdc1" cuntrolla u cuntrollu di a porta di a rete remota (8063)	/sci/controls/do o/sbloccare	doorid: {local, netdc1} * Facultativu	8039 8028 (G2) 8201 8063	> 3.3
Chjode a porta.	/sci/controls/do o/lock	doorid: {local, netdc1} * Facultativu	8039 8028 (G2) 8201 8063	> 3.3
Ghjucà un tonu una volta o loop it.	/sci/controls/to ne/start	caminu : {tone} ie. chime.wav ciclu: {true, false} o {0, 1}	Tuttu	> 3.3
Ferma u tonu.	/sci/controls/to ne/stop	N/A	Tuttu	> 3.3
Attivate u stroboscopiu cù i paràmetri di culore è mudellu desiderati.	/sci/controls/strobe/start	mudellu: {0 - 15} culore 1: {blu, rossu, ambra, verde} culore 2: {blu, rossu, ambra, verde} ledlvl: {1 - 255} holdover: {veru, falsu}	8128 (G2) 8138 8190S	> 3.3
Stop the strobe.	/sci/controls/strobe/stop	N/A	8128 (G2) 8138 8190S	> 3.3

Documenti / Risorse

	API ALGO RESTful [pdfGuida di l'utente AL061-GU-GF000API-001-R0, AL061-GU-CP00TEAM-001-R0, RESTful API, RESTful, API
	API ALGO RESTful [pdfGuida di l'utente AL061-GU-CP000API-230717, RESTful API, RESTful, API

Referenze

• Manuale d'usu