API RESTful ALGO

Informazioni sul prodotto: Guida API RESTful

L'API Algo RESTful consente agli utenti di accedere, manipolare e attivare azioni sugli endpoint IP Algo sulla propria rete tramite richieste HTTP/HTTPS. Questo documento fornisce un insieme uniforme e predefinito di operazioni stateless che possono essere utilizzate per interagire con i dispositivi Algo. L'API supporta richieste HTTP/HTTPS GET, POST e PUT con payload JSON.

Autenticazione

Sono disponibili tre tipi di autenticazione con l'API Algo RESTful:

• Autenticazione standard (abilitata per impostazione predefinita)
• Autenticazione di base (opzionale)
• Nessun metodo di autenticazione (non consigliato; solo a scopo di test)

Istruzioni per l'uso del prodotto: API RESTful

Prerequisiti

Prima di abilitare l'API RESTful, assicurati che il dispositivo disponga di una connessione Internet per raggiungere i server NTP preconfigurati. Se non è disponibile alcuna connessione Internet, configura un server NTP locale e inserisci il suo indirizzo IP.

Abilitazione dell'API RESTful

1. Accedi al dispositivo web interfaccia e vai alla scheda Amministratore delle impostazioni avanzate.
2. Scorri verso il basso fino alla sezione Supporto API e abilita l'API RESTful.
3. Impostare la password desiderata (password predefinita: algo). Tieni presente che l'autenticazione standard è abilitata per impostazione predefinita.

Abilitazione dell'autenticazione di base (opzionale)

1. Nel web dell'interfaccia, accedere alla scheda System Maintenance e scaricare la configurazione file.
2. Apri la configurazione file con qualsiasi editor di testo e aggiungi la seguente riga: api.auth.basic = 1
3. Salva e carica la configurazione modificata file al dispositivo utilizzando il ripristino della configurazione File funzione nella scheda Manutenzione del sistema.

Abilitare nessun metodo di autenticazione (facoltativo)

Per abilitare il metodo senza autenticazione, lasciare vuoto il campo Password API RESTful. Questo metodo non è consigliato e dovrebbe essere utilizzato solo a scopo di test in quanto non fornisce alcuna sicurezza.

Abilitazione dell'interfaccia di controllo semplice (opzionale)

1. Sul web dell'interfaccia, accedere alla scheda System Maintenance e scaricare la configurazione file.
2. Apri la configurazione file utilizzando un editor di testo e aggiungi due righe. Cambia la password che desideri.
3. Amministratore.web.sci = 1
4. Sci.admin.pwd =
5. Salva e carica la configurazione modificata file al dispositivo utilizzando il ripristino della configurazione File funzione nella scheda Manutenzione del sistema.

Autenticazione Sample Codice

Per favore invia un'e-mail support@algosolutions.com se desideri un'autenticazione standard o di baseampcodificali
Per ulteriore supporto, chiamare Numero di telefono: 604-454-3792 o e-mail support@algosolutions.com

Avvisi informativi

Nota
La nota indica aggiornamenti, informazioni e istruzioni utili da seguire

Disclaimer

Le informazioni contenute in questo documento sono ritenute accurate sotto tutti gli aspetti ma non sono garantite da Algo. Le informazioni sono soggette a modifiche senza preavviso e non devono essere interpretate in alcun modo come un impegno da parte di Algo o delle sue affiliate o controllate. Algo e le sue affiliate e controllate non si assumono alcuna responsabilità per eventuali errori o omissioni presenti nel presente documento. Potrebbero essere rilasciate revisioni del presente documento o nuove edizioni per incorporare tali modifiche. Algo non si assume alcuna responsabilità per danni o reclami derivanti dall'uso di questo manuale o di tali prodotti, software, firmware e/o hardware. Nessuna parte di questo documento può essere riprodotta o trasmessa in qualsiasi forma o con qualsiasi mezzo, elettronico o meccanico, per qualsiasi scopo senza il consenso scritto di Algo.
Per ulteriori informazioni o assistenza tecnica in Nord America, contattare il team di supporto di Algo:

Supporto tecnico Algo
1-Numero di telefono: 604-454-3792
support@algosolutions.com

©2022 Algo è un marchio registrato di Algo Communication Products Ltd.
Tutti i diritti riservati. Tutti gli altri marchi commerciali appartengono ai rispettivi proprietari. Tutte le specifiche sono soggette a modifiche senza preavviso.

 GENERALE

Introduzione

Questo documento descrive come utilizzare l'API Algo RESTful per accedere, manipolare e attivare azioni sugli endpoint IP Algo sulla rete tramite richieste HTTP/HTTPS, nonché un paio di metodi di autenticazione diversi con diversi livelli di sicurezza. I sistemi richiedenti possono interagire con i dispositivi Algo attraverso un insieme uniforme e predefinito di operazioni stateless definite in questo documento. Le richieste vengono effettuate all'URI di una risorsa con un payload JSON e suscitano una risposta JSON. Le richieste HTTP/HTTPS GET, POST e PUT vengono effettuate all'URI della risorsa insieme al payload JSON (vedere la sezione comandi per un elenco dei payload).

 Autenticazione

Esistono tre tipi di autenticazione:

•  Standard (consigliato)
•  Di base
•  Nessuno (non consigliato)

L'autenticazione standard utilizza un codice di autenticazione del messaggio basato su hash (HMAC) con un digest codificato SHA-256. L'autenticazione di base utilizza la codifica Base64 e deve essere utilizzata solo su HTTPS. Nessuna autenticazione deve essere utilizzata solo con estrema cautela poiché non fornisce alcuna autenticazione. Consulta la sezione Requisiti di autenticazione per maggiori dettagli.

INSTALLAZIONE E CONFIGURAZIONE

Prerequisiti

•  Questo documento presuppone che l'endpoint Algo esegua la versione firmware 3.3 o successiva.
•  La differenza temporale tra il richiedente e i dispositivi Algo deve essere inferiore a 30 secondi per utilizzare l'autenticazione standard.
• Assicurarsi che sia in uso il protocollo NTP (Network Time Protocol). Gli indirizzi dei server NTP personalizzati possono essere configurati nella scheda Impostazioni avanzate → Ora.

Nota
I server NTP preconfigurati sono ospitati pubblicamente, pertanto per raggiungerli è necessaria la connessione Internet. Se non è disponibile alcuna connessione Internet, configura un server NTP locale e inserisci il suo indirizzo IP.

• Assicurarsi che l'ora del sistema del dispositivo Algo sia regolata sul fuso orario corretto. Questo può essere fatto accedendo alla scheda Impostazioni avanzate → Ora.

 Abilitazione dell'API RESTful

1. Accedi al web e vai alla scheda Impostazioni avanzate → Amministrazione.
2. Scorri verso il basso fino alla sezione Supporto API, abilita l'API RESTful e imposta la password come desiderato (password predefinita: algo)
   Nota
   L'autenticazione standard è abilitata per impostazione predefinita.

Abilita l'autenticazione di base (facoltativo)

1. Nel web accedere alla scheda Sistema → Manutenzione e scaricare la configurazione file.
2. Apri la configurazione file con qualsiasi editor di testo e aggiungi la seguente riga: api.auth.basic = 1
3.  Salva e carica la configurazione modificata file al dispositivo utilizzando il ripristino della configurazione File funzione nella scheda Sistema → Manutenzione.

Nessun metodo di autenticazione (facoltativo)

Per abilitare il metodo senza autenticazione, lasciare vuoto il campo Password API RESTful. Questo metodo non è consigliato e dovrebbe essere utilizzato solo a scopo di test in quanto non fornisce alcuna sicurezza.

Abilitazione dell'interfaccia di controllo semplice (opzionale)

1. Sul web accedere alla scheda Sistema → Manutenzione e scaricare la configurazione file.
2.  Apri la configurazione file utilizzando un editor di testo e aggiungi due righe. Cambia con la password che desideri. Ammin.web.sci = 1
   Sci.admin.pwd =
3.  Salva e carica la configurazione modificata file al dispositivo utilizzando il ripristino della configurazione File funzione nella scheda Sistema → Manutenzione.

REQUISITI DI AUTENTICAZIONE

Per favore invia un'e-mail support@algosolutions.com se desideri un'autenticazione standard o di baseampcodificali

Richiesta di autenticazione standard con un payload JSON

Intestazioni obbligatorie nella richiesta HTTP/HTTPS
> Tipo di contenuto: “application/json”
> Contenuto-MD5: [contenuto_md5] Example
Content-MD5: 74362cc86588b2b3c5a4491baf80375b

Autorizzazione: hmac admin:[nonce]:[hmac_output]
Le intestazioni di autorizzazione sono costituite da:

1. La stringa "hmac admin" seguita da due punti ":".
2. Nonce – Un valore casuale o non ripetitivo, seguito da due punti ":".
3. Hmac_output – generato dalla password API RESTful (chiave segreta) configurata sul dispositivo e dall'input HMAC, come di seguito:
   [metodo_richiesta]:[uri_richiesta]:[contenuto_md5]:[tipo_contenuto]:[orarioamp]:[nonce]

Ingresso HMAC esample: (usando "algo" come chiave segreta)
POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 Genera HMAC con password e stringa di input HMAC come digest utilizzando SHA-256:
Uscita HMAC esample: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

Data: giorno, data mese, anno ore:min:sec GMT
Example
Data: giovedì 22 settembre 2022 02:33:07 GMT
Autenticazione standard con payload esampon:

 Richiesta di autenticazione standard senza payload JSON

Identico a 3.1 con intestazioni relative al contenuto/input hmac omessi.
Ingresso HMAC: [request_method]:[request_uri]:[timestamp]:[nonce] Ingresso HMAC esample: (usando "algo" come chiave segreta)
OTTIENI:/api/settings/audio.page.vol:1601312252:49936
Genera HMAC con password e stringa di input HMAC utilizzando SHA-256:
Uscita HMAC esample: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8
Autenticazione standard senza carico utile esampon:

 Richiesta di autenticazione di base

Questo metodo di autenticazione deve essere utilizzato con cautela poiché è meno sicuro del metodo standard.

Autorizzazione: Base [base64]
Exampon:
Autorizzazione: Base YWRtaW46YWxnbwo=
Autenticazione di base, ad esampon:

COMANDI

 Comandi API RESTful

Di seguito è riportato un elenco di tutti i comandi API supportati.

Nota
Una richiesta PUT modifica o crea una risorsa permanente che sopravvive a un riavvio, mentre una richiesta POST controlla solo il dispositivo per la sessione corrente.

Descrizione	Metodo	Nome dell'utente	Carico utile Parametri	Ritorno Example	Prodotto	FW
Recupera il valore di un parametro specifico.	OTTENERE	/api/settings/[nome-chiave] Es./api/settings/audio.page.vol	N / A	{“audio.page.vol”: “-18dB”}	Tutto	> 3.3
Restituisce il livello di rumore ambientale misurato in decibel. La compensazione del rumore ambientale deve essere abilitata in Impostazioni di base -> scheda Funzionalità.	OTTENERE	/api/info/audio.noise.level	N / A	{“audio.rumore.livello”: 72}	Altoparlanti Visualizza gli altoparlanti	> 3.3
Estrarre lo stato del terminale di ingresso relè.	OTTENERE	/api/info/input.relay.status	N / A	{"input.relay.status": "idle"} o {"input.relay.status": "active"}	Tutti i prodotti con ingresso relè, tranne l'8063. Vedi sotto.	> 4.1
Estrarre lo stato dei terminali Input 1 o Input 2.	OTTENERE	/api/info/input.relay1.status o /api/info/input.relay2.status	N / A	{"input.relay1.status": "idle"} o {"input.relay1.status": "attivo"}	8063	> 4.1
Recupera l'elenco dei toni fileè attualmente installato.	OTTENERE	/api/info/tonelist	N / A	{“tonelist”:[“bell-na.wav”,”bell uk.wav”,”buzzer.wav”,…]}	Tutto	> 5.0
Recupera le informazioni sul dispositivo visualizzate nella pagina Stato.	OTTENERE	/api/info/stato	N / A	Elenco completo delle informazioni dalla scheda Stato.	Tutto	> 5.4

Recupera le informazioni sul prodotto visualizzate nella pagina Informazioni.	OTTENERE	/api/info/about	N / A	Tutte le informazioni presenti nella scheda Informazioni.	Tutto	> 5.4
Attiva lo strobo con i parametri del colore e del motivo desiderati.	INVIARE	/api/controlli/strobe/start	modello: {0 – 15} color1: {blu, rosso, ambra, verde} color2: {blu, rosso, ambra, verde} ledlvl: {1 – 255} residuo: {vero, falso}	N / A	8128(G2) 8138 8190S	> 3.3
Arresta lo stroboscopio.	INVIARE	/api/controlli/strobe/stop	N / A	N / A	8128(G2) 8138 8190S	> 3.3
Riproduci un tono una volta o riproducilo in loop.	INVIARE	/api/controlli/tone/start	percorso: {tono} es. carillon.wav ciclo: {vero, falso} o {0, 1} es. {“path”:”chime.wav”, “loop”:true}	N / A	Altoparlanti 8301 8373 8028(G2) 8201 8039	> 3.3
Ferma il tono.	INVIARE	/api/controlli/tone/stop	N / A	N / A	Altoparlanti 8301 8373 8028(G2) 8201 8039	> 3.3
Chiama un interno telefonico con un messaggio preregistrato.	INVIARE	/api/controlli/call/start	{“estensione”:”2099″, “tone”:”gong.wav”, “intervallo”:”0″, “maxdur”:”10″}	N / A	Altoparlanti 8301 8410 8420	> 3.3
Termina la chiamata.	INVIARE	/api/controlli/call/stop	N / A	N / A	Altoparlanti 8301 8410 8420	> 3.3

Avvia una chiamata cercapersone unidirezionale. Il dispositivo riceverà il flusso audio dall'estensione di destinazione.	INVIARE	/api/controlli/chiamata/pagina	{“estensione”:””}	N / A	Altoparlanti 8410 8420	> 5.3.4
Riavvia l'endpoint di destinazione.	INVIARE	/api/controlli/reboot	N / A	N / A	Tutto	> 3.3
Sblocca la porta. “local” controlla il relè locale “netdc1” controlla il controllore remoto della porta di rete (8063)	INVIARE	/api/controlli/porta/sblocco	ID porta: {locale, netdc1} *Opzionale	N / A	8039 8028(G2) 8201 8063	> 3.3
Blocca la porta.	INVIARE	/api/controlli/porta/serratura	ID porta: {locale, netdc1} *Opzionale	N / A	8039 8028(G2) 8201 8063	> 3.3
Abilita il relè di uscita ausiliaria da 24 V.	INVIARE	api/controls/24v/enable	N / A	N / A	8063	> 5.0
Disabilitare il relè di uscita aux da 24 V.	INVIARE	api/controls/24v/disable	N / A	N / A	8063	> 5.0
Abilitare il relè di uscita.	INVIARE	/api/controlli/relay/abilita	N / A	N / A	8063	> 5.0
Disabilitare il relè di uscita.	INVIARE	/api/controlli/relay/disabilita	N / A	N / A	8063	> 5.0
Controlla il server del firmware di Algo per l'ultima versione del firmware.	INVIARE	/api/controlli/aggiornamento/controllo	N / A	{"versione": "aggiornata"} o {“versione”: “”}	Tutto	> 4.1
Controlla il server firmware di Algo per la versione più recente del firmware e aggiorna a quella versione.	INVIARE	/api/controlli/aggiornamento/start	N / A	{“stato”: “aggiornato”} o {“status”: “aggiornamento ”, “url”: url>} o {“stato”: “”}	Tutto	> 4.1
Visualizza un'immagine o un motivo sullo schermo.	INVIARE	/api/controlli/schermo/start	Vedere sotto	N / A	8410 8420	> 5.3.4
Arresta lo schema della schermata e torna alla schermata predefinita.	INVIARE	/api/controlli/schermo/stop	N / A	N / A	8410 8420	> 5.3.4

Riavvia l'applicazione principale.	INVIARE	/api/controlli/ricarica	N / A	N / A	Tutto	> 5.3.4
Inizia ad ascoltare un flusso audio diretto. Configura il numero di porta a cui viene inviato il flusso.	INVIARE	/api/controlli/rx/start	{"porta": }	N / A	Tutto	> 5.3.4
Smetti di ascoltare un flusso audio diretto.	INVIARE	/api/controlli/rx/stop	N / A	N / A	Tutto	> 5.3.4
Imposta la modalità multicast.	METTERE	/api/stato/mcast/aggiornamento/	{“mode”:”sender”, “address”:, “port”:, “type”:”rtp”} o {“mode”:”sender”, “address”: , “porta”:, “tipo”:”poli”, “gruppo”:1} **Nota**: se i controlli/tono/inizio viene utilizzato prima di questo comando, il tono suonerà utilizzando le impostazioni correnti sul web UI.	N / A	8301	> 5.0
Inserisci un valore in un parametro specifico dal payload JSON.	METTERE	/api/impostazioni	parametro: {valore} per esempio. {“audio.page.vol”: “-3dB”}	N / A	8180(G2) 8186 8190 8190S 8301 8373	> 3.3

 Comandi dell'interfaccia di controllo semplice (SCI).

Tutti i comandi SCI sono richieste GET e hanno i parametri comuni "usi" e "admin" per l'autenticazione.
Exampon:
OTTIENI http:///sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local

Descrizione	Nome dell'utente	Aggiuntivo Carico utile Parametri	Prodotti	FW
Sblocca la porta. “local” controlla il relè locale “netdc1” controlla il controller remoto della porta di rete (8063)	/sci/controlli/fare o/sbloccare	ID porta: {locale, netdc1} *Opzionale	8039 8028(G2) 8201 8063	> 3.3
Blocca la porta.	/sci/controlli/fare o/bloccare	ID porta: {locale, netdc1} *Opzionale	8039 8028(G2) 8201 8063	> 3.3
Riproduci un tono una volta o riproducilo in loop.	/sci/controlli/to ne/start	percorso: {tono} es. carillon.wav ciclo: {vero, falso} o {0, 1}	Tutto	> 3.3
Ferma il tono.	/sci/controlli/ne/stop	N / A	Tutto	> 3.3
Attiva lo strobo con i parametri del colore e del motivo desiderati.	/sci/controlli/strobo/start	modello: {0 – 15} colore1: {blu, rosso, ambra, verde} color2: {blu, rosso, ambra, verde} ledlvl: {1 – 255} holdover: {vero, falso}	8128(G2) 8138 8190S	> 3.3
Arresta lo stroboscopio.	/sci/controlli/strobo/stop	N / A	8128(G2) 8138 8190S	> 3.3

Documenti / Risorse

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

Riferimenti

• Manuale d'uso