API ALGO RESTful

Informació del producte: Guia de l'API RESTful

L'API RESTful d'Algo permet als usuaris accedir, manipular i activar accions als punts finals d'Algo IP a la seva xarxa mitjançant sol·licituds HTTP/HTTPS. Aquest document proporciona un conjunt uniforme i predefinit d'operacions sense estat que es poden utilitzar per interactuar amb dispositius Algo. L'API admet sol·licituds HTTP/HTTPS GET, POST i PUT amb càrregues útils JSON.

Autenticació

Hi ha tres tipus d'autenticacions disponibles amb l'API RESTful d'Algo:

• Autenticació estàndard (activada per defecte)
• Autenticació bàsica (opcional)
• Sense mètode d'autenticació (no recomanat; només amb finalitats de prova)

Instruccions d'ús del producte: API RESTful

Requisits previs

Abans d'activar l'API RESTful, assegureu-vos que el dispositiu tingui connexió a Internet per arribar als servidors NTP preconfigurats. Si no hi ha connexió a Internet disponible, configureu un servidor NTP local i introduïu la seva adreça IP.

Habilitant l'API RESTful

1. Inicieu sessió al dispositiu web interfície i navegueu a la pestanya Administrador de la configuració avançada.
2. Desplaceu-vos cap avall fins a la secció Suport de l'API i activeu l'API RESTful.
3. Establiu la contrasenya desitjada (contrasenya per defecte: algo). Tingueu en compte que l'autenticació estàndard està activada per defecte.

Habilitació de l'autenticació bàsica (opcional)

1. En el web interfície, navegueu a la pestanya Manteniment del sistema i descarregueu la configuració file.
2. Obriu la configuració file amb qualsevol editor de text i afegiu la línia següent: api.auth.basic = 1
3. Deseu i pengeu la configuració modificada file tornar al dispositiu mitjançant la configuració de restauració File funció a la pestanya Manteniment del sistema.

Activació del mètode sense autenticació (opcional)

Per habilitar el mètode sense autenticació, deixeu el camp Contrasenya de l'API RESTful buit. Aquest mètode no es recomana i només s'ha d'utilitzar amb finalitats de prova, ja que no ofereix seguretat.

Habilitació de la interfície de control simple (opcional)

1. A la web interfície, navegueu a la pestanya Manteniment del sistema i descarregueu la configuració file.
2. Obriu la configuració file utilitzant un editor de text i afegiu dues línies. Canvieu la contrasenya que vulgueu.
3. Admin.web.sci = 1
4. Sci.admin.pwd =
5. Deseu i pengeu la configuració modificada file tornar al dispositiu mitjançant la configuració de restauració File funció a la pestanya Manteniment del sistema.

Autenticació Sampel codi

Si us plau, envieu un correu electrònic support@algosolutions.com si voleu una autenticació estàndard o bàsica sampel codi.
Per obtenir suport addicional, truqueu 604-454-3792 o correu electrònic support@algosolutions.com

Avisos informatius

Nota
La nota indica actualitzacions, informació i instruccions útils que s'han de seguir

Exempció de responsabilitat

Es considera que la informació continguda en aquest document és precisa en tots els aspectes, però Algo no la garanteix. La informació està subjecta a canvis sense previ avís i no s'ha d'interpretar de cap manera com un compromís d'Algo o de cap de les seves filials o filials. Algo i les seves filials i filials no assumeixen cap responsabilitat per errors o omissions en aquest document. Es poden emetre revisions d'aquest document o noves edicions d'aquest per incorporar aquests canvis. Algo no assumeix cap responsabilitat per danys o reclamacions derivades de l'ús d'aquest manual o d'aquests productes, programari, microprogramari i/o maquinari. Cap part d'aquest document no es pot reproduir ni transmetre de cap forma ni per cap mitjà –electrònic o mecànic– per a cap finalitat sense el permís per escrit d'Algo.
Per obtenir informació addicional o assistència tècnica a Amèrica del Nord, poseu-vos en contacte amb l'equip d'assistència d'Algo:

Suport tècnic d'Algo
1-604-454-3792
support@algosolutions.com

©2022 Algo és una marca comercial registrada d'Algo Communication Products Ltd.
Tots els drets reservats. Totes les altres marques comercials són propietat dels seus respectius propietaris. Totes les especificacions estan subjectes a canvis sense previ avís.

 GENERAL

Introducció

Aquest document descriu com es pot utilitzar l'API RESTful d'Algo per accedir, manipular i activar accions als punts finals d'Algo IP a la vostra xarxa mitjançant sol·licituds HTTP/HTTPS, així com un parell de mètodes d'autenticació diferents amb diferents nivells de seguretat. Els sistemes de sol·licitud poden interactuar amb els dispositius Algo mitjançant un conjunt uniforme i predefinit d'operacions sense estat definides en aquest document. Les sol·licituds es fan a l'URI d'un recurs amb una càrrega útil JSON i obtenen una resposta JSON. Les sol·licituds HTTP/HTTPS GET, POST i PUT es fan a l'URI del recurs juntament amb la càrrega útil JSON (vegeu la secció d'ordres per obtenir una llista de càrregues útils).

 Autenticació

Hi ha tres tipus d'autenticacions:

•  Estàndard (recomanat)
•  Bàsica
•  Cap (no recomanat)

L'autenticació estàndard utilitza un codi d'autenticació de missatges basat en hash (HMAC) amb un resum codificat SHA-256. L'autenticació bàsica utilitza la codificació Base64 i només s'ha d'utilitzar mitjançant HTTPS. Cap autenticació només s'ha d'utilitzar amb extrema cura, ja que no proporciona autenticació. Consulteu la secció Requisits d'autenticació per obtenir més detalls.

INSTAL·LACIÓ I CONFIGURACIÓ

Requisits previs

•  Aquest document assumeix que el punt final d'Algo està executant la versió de microprogramari 3.3 o superior.
•  La diferència de temps entre el sol·licitant i els dispositius Algo hauria de ser inferior a 30 segons per utilitzar l'autenticació estàndard.
• Assegureu-vos que s'utilitza NTP (Network Time Protocol). Les adreces dels servidors NTP personalitzats es poden configurar a la pestanya Configuració avançada → Hora.

Nota
Els servidors NTP preconfigurats estan allotjats públicament, per tant, cal connexió a Internet per arribar-hi. Si no hi ha connexió a Internet disponible, configureu un servidor NTP local i introduïu la seva adreça IP.

• Assegureu-vos que l'hora del sistema del dispositiu Algo s'ajusti a la zona horària correcta. Això es pot fer navegant a la pestanya Configuració avançada → Hora.

 Habilitant l'API RESTful

1. Inicieu sessió a web interfície i navegueu a la pestanya Configuració avançada → Administrador.
2. Desplaceu-vos cap avall fins a la secció de suport de l'API, activeu l'API RESTful i configureu la contrasenya com vulgueu (contrasenya predeterminada: algo)
   Nota
   L'autenticació estàndard està activada per defecte.

Activa l'autenticació bàsica (opcional)

1. En el web interfície, navegueu a la pestanya Sistema → Manteniment i descarregueu la configuració file.
2. Obriu la configuració file amb qualsevol editor de text i afegiu la línia següent: api.auth.basic = 1
3.  Deseu i pengeu la configuració modificada file tornar al dispositiu mitjançant la configuració de restauració File funció a la pestanya Sistema → Manteniment.

Sense mètode d'autenticació (opcional)

Per habilitar el mètode sense autenticació, deixeu el camp Contrasenya de l'API RESTful buit. Aquest mètode no es recomana i només s'ha d'utilitzar amb finalitats de prova, ja que no ofereix seguretat.

Habilitació de la interfície de control simple (opcional)

1. A la web interfície, navegueu a la pestanya Sistema → Manteniment i descarregueu la configuració file.
2.  Obriu la configuració file utilitzant un editor de text i afegiu dues línies. Canvia el a la vostra contrasenya desitjada. Admin.web.sci = 1
   Sci.admin.pwd =
3.  Deseu i pengeu la configuració modificada file tornar al dispositiu mitjançant la configuració de restauració File funció a la pestanya Sistema → Manteniment.

REQUISITS D'Autenticació

Si us plau, envieu un correu electrònic support@algosolutions.com si voleu una autenticació estàndard o bàsica sampel codi.

Sol·licitud d'autenticació estàndard amb una càrrega útil JSON

Capçaleres obligatòries a la sol·licitud HTTP/HTTPS
> Tipus de contingut: "aplicació/json"
> Contingut-MD5: [content_md5] Example
Content-MD5: 74362cc86588b2b3c5a4491baf80375b

Autorització: hmac admin:[nonce]:[hmac_output]
Les capçaleres d'autorització consisteixen en:

1. La cadena 'hmac admin' seguida de dos punts ':'.
2. Nonce: un valor aleatori o que no es repeteix, seguit de dos punts ':'.
3. Hmac_output: generat per la contrasenya de l'API RESTful (clau secreta) configurada al vostre dispositiu i l'entrada HMAC, tal com es mostra a continuació:
   [request_method]:[request_uri]:[content_md5]:[content_type]:[timestamp]:[nonce]

Entrada HMAC example: (utilitzant "algo" com a clau secreta)
POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 Genereu HMAC amb contrasenya i cadena d'entrada HMAC com a resum mitjançant SHA-256:
Sortida HMAC example: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

Data: dia, data mes, any hr:min:sec GMT
Example
Data: dijous, 22 de setembre de 2022 02:33:07 GMT
Autenticació estàndard amb càrrega útil exampLI:

 Sol·licitud d'autenticació estàndard sense càrrega útil JSON

Idèntic a 3.1 amb les capçaleres relacionades amb el contingut/l'entrada hmac omesa.
Entrada HMAC: [request_method]:[request_uri]:[timestamp]:[nonce] entrada HMAC example: (utilitzant "algo" com a clau secreta)
GET:/api/settings/audio.page.vol:1601312252:49936
Genereu HMAC amb contrasenya i cadena d'entrada HMAC mitjançant SHA-256:
Sortida HMAC example: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8
Autenticació estàndard sense càrrega útil exampLI:

 Sol·licitud d'autenticació bàsica

Aquest mètode d'autenticació s'ha d'utilitzar amb cura, ja que és menys segur que el mètode estàndard.

Autorització: bàsica [base64]
ExampLI:
Autorització: Basic YWRtaW46YWxnbwo=
Autenticació bàsica exampLI:

COMANDES

 Ordres de l'API RESTful

A continuació es mostra una llista de totes les ordres de l'API compatibles.

Nota
Una sol·licitud PUT canvia o crea un recurs permanent que sobreviu a un reinici, mentre que una sol·licitud POST només controla el dispositiu per a la sessió actual.

Descripció	Mètode	URI	Càrrega útil Paràmetres	Tornar Example	Producte	FW
Recuperar el valor d'un paràmetre específic.	OBTENIR	/api/settings/[nom-clau] Ex./api/settings/audio.page.vol	N/A	{“audio.page.vol”: “-18dB”}	Tots	> 3.3
Retorna el nivell de soroll ambiental mesurat en decibels. La compensació de soroll ambiental s'ha d'activar a la pestanya Configuració bàsica -> Funcions.	OBTENIR	/api/info/audio.noise.level	N/A	{“audio.noise.level”: 72}	Altaveus Mostra Altaveus	> 3.3
Extraieu l'estat del terminal d'entrada del relé.	OBTENIR	/api/info/input.relay.status	N/A	{“input.relay.status”: “idle”} o {“input.relay.status”: “actiu”}	Tots els productes amb una entrada de relé, excepte el 8063. Vegeu a continuació.	> 4.1
Extraieu l'estat dels terminals d'entrada 1 o d'entrada 2.	OBTENIR	/api/info/input.relay1.status o /api/info/input.relay2.status	N/A	{“input.relay1.status”: “idle”} o {“input.relay1.status”: “actiu”}	8063	> 4.1
Recuperar la llista de tons fileestà instal·lat actualment.	OBTENIR	/api/info/tonelist	N/A	{“tonelist”:[“bell-na.wav”,”bell uk.wav”,”buzzer.wav”,…]}	Tots	> 5.0
Recupereu la informació del dispositiu que es mostra a la pàgina Estat.	OBTENIR	/api/info/status	N/A	Llista completa d'informació de la pestanya Estat.	Tots	> 5.4

Recupereu la informació del producte que es mostra a la pàgina Quant a.	OBTENIR	/api/info/about	N/A	Tota la informació es troba a la pestanya Sobre.	Tots	> 5.4
Activeu l'estrobo amb els paràmetres de color i patró desitjats.	PUBLICACIÓ	/api/controls/strobe/start	patró: {0 – 15} color1: {blau, vermell, ambre, verd} color2: {blau, vermell, ambre, verd} ledlvl: {1 – 255} resta: {vertader, fals}	N/A	8128(G2) 8138 8190S	> 3.3
Atura l'estroboscopi.	PUBLICACIÓ	/api/controls/strobe/stop	N/A	N/A	8128(G2) 8138 8190S	> 3.3
Toca un to una vegada o fes-lo en bucle.	PUBLICACIÓ	/api/controls/tone/start	camí: {ton} és a dir. carillon.wav bucle: {true, false} o {0, 1} p. ex. {“path”:”chime.wav”, “loop”:true}	N/A	Ponents 8301 8373 8028(G2) 8201 8039	> 3.3
Atura el to.	PUBLICACIÓ	/api/controls/tone/stop	N/A	N/A	Ponents 8301 8373 8028(G2) 8201 8039	> 3.3
Truqueu a una extensió telefònica amb un missatge pregravat.	PUBLICACIÓ	/api/controls/call/start	{“extensió”:”2099″, “tone”:”gong.wav”, “interval”:”0″, “maxdur”:”10″}	N/A	Ponents 8301 8410 8420	> 3.3
Finalitzar la trucada.	PUBLICACIÓ	/api/controls/call/stop	N/A	N/A	Ponents 8301 8410 8420	> 3.3

Inicieu una trucada de pàgina unidireccional. El dispositiu rebrà el flux d'àudio de l'extensió de destinació.	PUBLICACIÓ	/api/controls/call/page	{“extensió”:” ”}	N/A	Ponents 8410 8420	> 5.3.4
Reinicieu el punt final de destinació.	PUBLICACIÓ	/api/controls/reboot	N/A	N/A	Tots	> 3.3
Obriu la porta. "local" controla el relé local "netdc1" controla el controlador de la porta de la xarxa remota (8063)	PUBLICACIÓ	/api/controls/door/unlock	identificador de la porta: {local, netdc1} * Opcional	N/A	8039 8028(G2) 8201 8063	> 3.3
Tanca la porta.	PUBLICACIÓ	/api/controls/door/lock	identificador de la porta: {local, netdc1} * Opcional	N/A	8039 8028(G2) 8201 8063	> 3.3
Activeu el relé de sortida auxiliar de 24 V.	PUBLICACIÓ	api/controls/24v/enable	N/A	N/A	8063	> 5.0
Desactiveu el relé de sortida auxiliar de 24 V.	PUBLICACIÓ	api/controls/24v/disable	N/A	N/A	8063	> 5.0
Habiliteu el relé de sortida.	PUBLICACIÓ	/api/controls/relay/enable	N/A	N/A	8063	> 5.0
Desactiveu el relé de sortida.	PUBLICACIÓ	/api/controls/relay/disable	N/A	N/A	8063	> 5.0
Comproveu el servidor de microprogramari d'Algo per obtenir la versió més recent del microprogramari.	PUBLICACIÓ	/api/controls/upgrade/check	N/A	{“versió”: “actualitzada”} o {“versió”: “ ”}	Tots	> 4.1
Comproveu el servidor de microprogramari d'Algo per obtenir la versió més recent del microprogramari i actualitzeu-lo a aquesta versió.	PUBLICACIÓ	/api/controls/upgrade/start	N/A	{“estat”: “actualitzat”} o {“status”: “actualitzant ”, “url”: url>} o {"estat": " ”}	Tots	> 4.1
Mostra una imatge o un patró a la pantalla.	PUBLICACIÓ	/api/controls/screen/start	Mireu a continuació	N/A	8410 8420	> 5.3.4
Atureu el patró de pantalla i torneu a la pantalla predeterminada.	PUBLICACIÓ	/api/controls/screen/stop	N/A	N/A	8410 8420	> 5.3.4

Reinicieu l'aplicació principal.	PUBLICACIÓ	/api/controls/reload	N/A	N/A	Tots	> 5.3.4
Comença a escoltar un flux d'àudio directe. Configureu el número de port al qual s'envia el flux.	PUBLICACIÓ	/api/controls/rx/start	{“port”: }	N/A	Tots	> 5.3.4
Deixa d'escoltar un flux d'àudio directe.	PUBLICACIÓ	/api/controls/rx/stop	N/A	N/A	Tots	> 5.3.4
Estableix el mode de multidifusió.	POSAR	/api/state/mcast/update/	{“mode”:”remitent”, “adreça”: , "port": , "tipus":"rtp"} o {"mode":"remitent", "adreça": , "port": , "tipus":"poly", "grup":1} **Nota**: si s'utilitzen els controls/to/inici abans d'aquesta ordre, el to es reproduirà utilitzant la configuració actual del web IU.	N/A	8301	> 5.0
Inseriu un valor a un paràmetre específic de la càrrega útil JSON.	POSAR	/api/settings	paràmetre: {valor} p. ex. {“audio.page.vol”: “-3dB”}	N/A	8180(G2) 8186 8190 8190S 8301 8373	> 3.3

 Ordres de la interfície de control simple (SCI).

Totes les ordres SCI són sol·licituds GET i tenen els paràmetres comuns "usi" i "admin" per a l'autenticació.
ExampLI:
OBTÉ http:// /sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local

Descripció	URI	Addicional Càrrega útil Paràmetres	Productes	FW
Obriu la porta. "local" controla el relé local "netdc1" controla el controlador de la porta de la xarxa remota (8063)	/sci/controls/do o/desbloquejar	identificador de la porta: {local, netdc1} * Opcional	8039 8028(G2) 8201 8063	> 3.3
Tanca la porta.	/sci/controls/do o/bloquejar	identificador de la porta: {local, netdc1} * Opcional	8039 8028(G2) 8201 8063	> 3.3
Toca un to una vegada o fes-lo en bucle.	/sci/controls/to ne/start	camí: {ton} és a dir. carillon.wav bucle: {true, false} o {0, 1}	Tots	> 3.3
Atura el to.	/sci/controls/to ne/stop	N/A	Tots	> 3.3
Activeu l'estrobo amb els paràmetres de color i patró desitjats.	/sci/controls/strobe/start	patró: {0 – 15} color1: {blau, vermell, ambre, verd} color2: {blau, vermell, ambre, verd} ledlvl: {1 – 255} holdover: {true, false}	8128(G2) 8138 8190S	> 3.3
Atura l'estroboscopi.	/sci/controls/strobe/stop	N/A	8128(G2) 8138 8190S	> 3.3

Documents/Recursos

	API ALGO RESTful [pdfGuia de l'usuari AL061-GU-GF000API-001-R0, AL061-GU-CP00TEAM-001-R0, API RESTful, RESTful, API
	API ALGO RESTful [pdfGuia de l'usuari AL061-GU-CP000API-230717, API RESTful, RESTful, API

Referències

• Manual d'usuari