ALGO RESTful API

Información do produto: Guía da API RESTful

A API RESTful de Algo permite aos usuarios acceder, manipular e activar accións en puntos de conexión IP de Algo na súa rede mediante solicitudes HTTP/HTTPS. Este documento ofrece un conxunto uniforme e predefinido de operacións sen estado que se poden usar para interactuar cos dispositivos Algo. A API admite solicitudes HTTP/HTTPS GET, POST e PUT con cargas JSON.

Autenticación

Hai tres tipos de autenticacións dispoñibles coa API RESTful de Algo:

• Autenticación estándar (activada por defecto)
• Autenticación básica (opcional)
• Sen método de autenticación (non recomendado; só para fins de proba)

Instrucións de uso do produto: API RESTful

Requisitos previos

Antes de activar a API RESTful, asegúrese de que o dispositivo teña unha conexión a Internet para acceder aos servidores NTP preconfigurados. Se non hai conexión a Internet dispoñible, configure un servidor NTP local e introduza o seu enderezo IP.

Activando a API RESTful

1. Inicia sesión no dispositivo web e desprácese ata a pestana Administrador de Configuración avanzada.
2. Desprácese cara abaixo ata a sección Soporte de API e habilita a API RESTful.
3. Establece o contrasinal desexado (contrasinal predeterminado: algo). Teña en conta que a autenticación estándar está activada por defecto.

Activación da autenticación básica (opcional)

1. No web interface, navegue ata a pestana Mantemento do sistema e descargue a configuración file.
2. Abre a configuración file con calquera editor de texto e engade a seguinte liña: api.auth.basic = 1
3. Garda e carga a configuración modificada file volver ao dispositivo usando Restaurar configuración File función na pestana Mantemento do sistema.

Activar o método sen autenticación (opcional)

Para activar o método sen autenticación, deixe baleiro o campo Contrasinal da API RESTful. Este método non se recomenda e só debe usarse con fins de proba xa que non proporciona seguridade.

Activación da interface de control simple (opcional)

1. Sobre o web interface, navegue ata a pestana Mantemento do sistema e descargue a configuración file.
2. Abre a configuración file usando un editor de texto e engade dúas liñas. Cambia o contrasinal que desexes.
3. Admin.web.sci = 1
4. Sci.admin.pwd =
5. Garda e carga a configuración modificada file volver ao dispositivo usando Restaurar configuración File función na pestana Mantemento do sistema.

Autenticación Sampo Código

Por favor, envíe un correo electrónico support@algosolutions.com se desexa unha autenticación estándar ou básica sampcódigo le.
Para obter asistencia adicional, chame 604-454-3792 ou correo electrónico support@algosolutions.com

Avisos informativos

Nota
A nota indica actualizacións útiles, información e instrucións que se deben seguir

Exención de responsabilidade

Crese que a información contida neste documento é precisa en todos os aspectos, pero Algo non a garante. A información está suxeita a cambios sen previo aviso e non debe interpretarse de ningún xeito como un compromiso de Algo ou de calquera das súas filiales ou subsidiarias. Algo e as súas filiais e subsidiarias non asumen ningunha responsabilidade por erros ou omisións neste documento. Poderanse emitir revisións deste documento ou novas edicións do mesmo para incorporar tales cambios. Algo non asume ningunha responsabilidade por danos ou reclamacións derivados de calquera uso deste manual ou destes produtos, software, firmware e/ou hardware. Ningunha parte deste documento pode ser reproducida ou transmitida de calquera forma ou por ningún medio –electrónico ou mecánico– para ningún propósito sen o permiso escrito de Algo.
Para obter información adicional ou asistencia técnica en América do Norte, póñase en contacto co equipo de soporte de Algo:

Soporte Técnico Algo
1-604-454-3792
support@algosolutions.com

©2022 Algo é unha marca rexistrada de Algo Communication Products Ltd.
Todos os dereitos reservados. Todas as outras marcas comerciais son propiedade dos seus respectivos propietarios. Todas as especificacións están suxeitas a cambios sen previo aviso.

 XERAL

Introdución

Este documento describe como se pode usar a API RESTful de Algo para acceder, manipular e activar accións en puntos de conexión IP de Algo na súa rede mediante solicitudes HTTP/HTTPS, así como un par de métodos de autenticación diferentes con distintos niveis de seguridade. Os sistemas de solicitude poden interactuar cos dispositivos Algo mediante un conxunto uniforme e predefinido de operacións sen estado definidas neste documento. As solicitudes realízanse ao URI dun recurso cunha carga útil JSON e obtén unha resposta JSON. As solicitudes HTTP/HTTPS GET, POST e PUT realízanse ao URI do recurso xunto coa carga útil JSON (consulta a sección de comandos para ver unha lista de cargas útiles).

 Autenticación

Hai tres tipos de autenticacións:

•  Estándar (recomendado)
•  Básico
•  Ningún (non recomendado)

A autenticación estándar usa un código de autenticación de mensaxes baseado en hash (HMAC) cun resumo codificado SHA-256. A autenticación básica usa a codificación Base64 e só debe usarse a través de HTTPS. Non se debe usar ningunha autenticación con moito coidado xa que non proporciona autenticación. Consulte a sección Requisitos de autenticación para obter máis detalles.

INSTALACIÓN E CONFIGURACIÓN

Requisitos previos

•  Este documento asume que o punto final de Algo está executando a versión de firmware 3.3 ou superior.
•  A diferenza de tempo entre o solicitante e os dispositivos Algo debe ser inferior a 30 segundos para usar a autenticación estándar.
• Asegúrese de estar en uso NTP (Network Time Protocol). Os enderezos dos servidores NTP personalizados pódense configurar na pestana Configuración avanzada → Hora.

Nota
Os servidores NTP preconfigurados están aloxados publicamente, polo que é necesaria unha conexión a Internet para acceder a el. Se non hai conexión a Internet dispoñible, configure un servidor NTP local e introduza o seu enderezo IP.

• Asegúrate de que a hora do sistema do dispositivo Algo estea axustada á zona horaria correcta. Isto pódese facer navegando ata a pestana Configuración avanzada → Hora.

 Activando a API RESTful

1. Inicia sesión en web e desprácese ata a pestana Configuración avanzada → Administrador.
2. Desprácese ata a sección Soporte de API, habilite a API RESTful e configure o contrasinal como desexe (contrasinal predeterminado: algo)
   Nota
   A autenticación estándar está activada por defecto.

Activar a autenticación básica (opcional)

1. No web interface, navegue ata a pestana Sistema → Mantemento e descargue a configuración file.
2. Abre a configuración file con calquera editor de texto e engade a seguinte liña: api.auth.basic = 1
3.  Garda e carga a configuración modificada file volver ao dispositivo usando Restaurar configuración File función na pestana Sistema → Mantemento.

Sen método de autenticación (opcional)

Para activar o método sen autenticación, deixe baleiro o campo Contrasinal da API RESTful. Este método non se recomenda e só debe usarse con fins de proba xa que non proporciona seguridade.

Activación da interface de control simple (opcional)

1. Sobre o web interface, navegue ata a pestana Sistema → Mantemento e descargue a configuración file.
2.  Abre a configuración file usando un editor de texto e engade dúas liñas. Cambia o ao teu contrasinal desexado. Admin.web.sci = 1
   Sci.admin.pwd =
3.  Garda e carga a configuración modificada file volver ao dispositivo usando Restaurar configuración File función na pestana Sistema → Mantemento.

REQUISITOS DE AUTENTICACIÓN

Por favor, envíe un correo electrónico support@algosolutions.com se desexa unha autenticación estándar ou básica sampcódigo le.

Solicitude de autenticación estándar cunha carga útil JSON

Cabeceiras obrigatorias na solicitude HTTP/HTTPS
> Tipo de contido: "application/json"
> Contido-MD5: [content_md5] Example
Content-MD5: 74362cc86588b2b3c5a4491baf80375b

Autorización: hmac admin:[nonce]:[hmac_output]
As cabeceiras de autorización constan de:

1. A cadea 'hmac admin' seguida de dous puntos ':'.
2. Nonce: un valor aleatorio ou que non se repite, seguido de dous puntos ':'.
3. Hmac_output: xerado polo contrasinal da API RESTful (clave secreta) configurado no teu dispositivo e a entrada HMAC, como se indica a continuación:
   [request_method]:[request_uri]:[content_md5]:[content_type]:[timestamp]:[nonce]

Entrada HMAC example: (usando 'algo' como chave secreta)
POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 Xera HMAC con contrasinal e cadea de entrada HMAC como resumo usando SHA-256:
Saída HMAC example: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

Data: día, data, mes, ano hr:min:seg GMT
Example
Data: Xov, 22 de setembro de 2022 02:33:07 GMT
Autenticación estándar con carga útil exampLe:

 Solicitude de autenticación estándar sen carga útil JSON

Idéntico ao 3.1, con cabeceiras relacionadas co contido/entrada hmac omitidas.
Entrada HMAC: [request_method]:[request_uri]:[timestamp]:[nonce] entrada HMAC, example: (usando 'algo' como chave secreta)
GET:/api/settings/audio.page.vol:1601312252:49936
Xera HMAC con contrasinal e cadea de entrada HMAC usando SHA-256:
Saída HMAC example: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8
Autenticación estándar sen carga útil exampLe:

 Solicitude de autenticación básica

Este método de autenticación debe usarse con coidado xa que é menos seguro que o método estándar.

Autorización: Básica [base64]
ExampLe:
Autorización: Basic YWRtaW46YWxnbwo=
Autenticación básica exampLe:

COMANDOS

 Comandos da API RESTful

A continuación móstrase unha lista de todos os comandos da API admitidos.

Nota
Unha solicitude PUT cambia ou crea un recurso permanente que sobrevive a un reinicio, mentres que unha solicitude POST só controla o dispositivo para a sesión actual.

Descrición	Método	URI	Carga útil Parámetros	Volver Example	Produto	FW
Recuperar o valor dun parámetro específico.	CONSEGUIR	/api/settings/[nome da clave] Ex./api/settings/audio.page.vol	N/A	{“audio.page.vol”: “-18 dB”}	Todos	> 3.3
Devolve o nivel de ruído ambiental medido en decibelios. A compensación de ruído ambiental debe estar activada en Configuración básica -> pestana Funcións.	CONSEGUIR	/api/info/audio.noise.level	N/A	{“audio.noise.level”: 72}	Altofalantes Mostrar Altofalantes	> 3.3
Extrae o estado do terminal de entrada do relé.	CONSEGUIR	/api/info/input.relay.status	N/A	{“input.relay.status”: “inactivo”} ou {“input.relay.status”: “activo”}	Todos os produtos cunha entrada de relé, excepto o 8063. Consulte a continuación.	> 4.1
Extrae o estado dos terminais da entrada 1 ou da entrada 2.	CONSEGUIR	/api/info/input.relay1.status ou /api/info/input.relay2.status	N/A	{“input.relay1.status”: “inactivo”} ou {“input.relay1.status”: “activo”}	8063	> 4.1
Recuperar a lista de tons fileestá instalado actualmente.	CONSEGUIR	/api/info/tonelist	N/A	{“tonelist”:[“bell-na.wav”,”bell uk.wav”,”buzzer.wav”,…]}	Todos	> 5.0
Recupera a información do dispositivo que se mostra na páxina Estado.	CONSEGUIR	/api/info/status	N/A	Lista completa de información da pestana Estado.	Todos	> 5.4

Recupera a información do produto que se mostra na páxina Acerca de.	CONSEGUIR	/api/info/about	N/A	Toda a información está presente na pestana Acerca de.	Todos	> 5.4
Activa a luz estroboscópica cos parámetros de cor e patrón que desexes.	POST	/api/controls/strobe/start	patrón: {0 – 15} cor 1: {azul, vermello, ámbar, verde} cor 2: {azul, vermello, ámbar, verde} ledlvl: {1 – 255} remanente: {verdadeiro, falso}	N/A	8128 (G2) 8138 8190S	> 3.3
Detén a luz estroboscópica.	POST	/api/controls/strobe/stop	N/A	N/A	8128 (G2) 8138 8190S	> 3.3
Toca un ton unha vez ou fai un bucle.	POST	/api/controls/tone/start	camiño: {ton} é dicir. badalada.wav bucle: {verdadeiro, falso} ou {0, 1} p.ex. {“ruta”:”chime.wav”, “bucle”: verdadeiro}	N/A	Relatores 8301 8373 8028 (G2) 8201 8039	> 3.3
Detén o ton.	POST	/api/controls/tone/stop	N/A	N/A	Relatores 8301 8373 8028 (G2) 8201 8039	> 3.3
Chame a unha extensión telefónica cunha mensaxe previamente gravada.	POST	/api/controls/call/start	{“extensión”:”2099”, “tone”:”gong.wav”, “intervalo”:”0″, “maxdur”:”10″}	N/A	Relatores 8301 8410 8420	> 3.3
Finaliza a chamada.	POST	/api/controls/call/stop	N/A	N/A	Relatores 8301 8410 8420	> 3.3

Inicia unha chamada de páxina unidireccional. O dispositivo recibirá o fluxo de audio da extensión de destino.	POST	/api/controls/call/page	{“extensión”:” ”}	N/A	Relatores 8410 8420	> 5.3.4
Reinicie o punto final de destino.	POST	/api/controls/reboot	N/A	N/A	Todos	> 3.3
Desbloquea a porta. “local” controla o relé local “netdc1” controla o controlador remoto da porta da rede (8063)	POST	/api/controls/door/unlock	doorid: {local, netdc1} * Opcional	N/A	8039 8028 (G2) 8201 8063	> 3.3
Pecha a porta.	POST	/api/controls/door/lock	doorid: {local, netdc1} * Opcional	N/A	8039 8028 (G2) 8201 8063	> 3.3
Activa o relé de saída auxiliar de 24 V.	POST	api/controls/24v/enable	N/A	N/A	8063	> 5.0
Desactiva o relé de saída auxiliar de 24 V.	POST	api/controls/24v/disable	N/A	N/A	8063	> 5.0
Activa o relé de saída.	POST	/api/controls/relay/enable	N/A	N/A	8063	> 5.0
Desactivar o relé de saída.	POST	/api/controls/relé/desactivar	N/A	N/A	8063	> 5.0
Consulte o servidor de firmware de Algo para ver a versión máis recente de firmware.	POST	/api/controls/upgrade/check	N/A	{“versión”: “actualizada”} ou {“versión”: “ ”}	Todos	> 4.1
Consulte o servidor de firmware de Algo para ver a versión máis recente de firmware e actualíceo a esa versión.	POST	/api/controls/upgrade/start	N/A	{“estado”: ​​“actualizado”} ou {“status”: “actualizándose ”, “url”: url>} ou {“estado”: ​​“ ”}	Todos	> 4.1
Mostrar unha imaxe ou un patrón na pantalla.	POST	/api/controls/screen/start	Vexa abaixo	N/A	8410 8420	> 5.3.4
Detén o patrón de pantalla e volve á pantalla predeterminada.	POST	/api/controls/screen/stop	N/A	N/A	8410 8420	> 5.3.4

Reinicie a aplicación principal.	POST	/api/controls/reload	N/A	N/A	Todos	> 5.3.4
Comeza a escoitar unha emisión de audio directa. Configure o número de porto ao que se envía o fluxo.	POST	/api/controls/rx/start	{"Porto": }	N/A	Todos	> 5.3.4
Deixa de escoitar unha emisión de audio directa.	POST	/api/controls/rx/stop	N/A	N/A	Todos	> 5.3.4
Establece o modo de multidifusión.	POÑER	/api/state/mcast/update/	{“mode”:”remitente”, “enderezo”: , "Porto": , “tipo”:”rtp”} ou {“modo”:”remitente”, “enderezo”: , "Porto": , “tipo”:”poly”, “grupo”:1} **Nota**: se se usan controis/ton/inicio antes deste comando, o ton reproducirase usando os axustes actuais do web UI.	N/A	8301	> 5.0
Insira un valor nun parámetro específico da carga útil JSON.	POÑER	/api/settings	parámetro: {valor} p.ex. {“audio.page.vol”: “-3dB”}	N/A	8180 (G2) 8186 8190 8190S 8301 8373	> 3.3

 Comandos da interface de control simple (SCI).

Todos os comandos SCI son solicitudes GET e teñen os parámetros comúns "usi" e "admin" para a autenticación.
ExampLe:
OBTER http:// /sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local

Descrición	URI	Adicional Carga útil Parámetros	Produtos	FW
Desbloquea a porta. “local” controla o relé local “netdc1” controla o controlador remoto da porta da rede (8063)	/sci/controls/do ou/desbloquear	doorid: {local, netdc1} * Opcional	8039 8028 (G2) 8201 8063	> 3.3
Pecha a porta.	/sci/controls/facer ou/bloquear	doorid: {local, netdc1} * Opcional	8039 8028 (G2) 8201 8063	> 3.3
Toca un ton unha vez ou fai un bucle.	/sci/controls/to ne/start	camiño: {ton} é dicir. badalada.wav bucle: {verdadeiro, falso} ou {0, 1}	Todos	> 3.3
Detén o ton.	/sci/controls/to ne/stop	N/A	Todos	> 3.3
Activa a luz estroboscópica cos parámetros de cor e patrón que desexes.	/sci/controls/strobe/start	patrón: {0 – 15} cor 1: {azul, vermello, ámbar, verde} cor 2: {azul, vermello, ámbar, verde} ledlvl: {1 – 255} holdover: {true, false}	8128 (G2) 8138 8190S	> 3.3
Detén a luz estroboscópica.	/sci/controls/strobe/stop	N/A	8128 (G2) 8138 8190S	> 3.3

Documentos/Recursos

	ALGO RESTful API [pdfGuía do usuario AL061-GU-GF000API-001-R0, AL061-GU-CP00TEAM-001-R0, API RESTful, RESTful, API
	ALGO RESTful API [pdfGuía do usuario AL061-GU-CP000API-230717, API RESTful, RESTful, API

Referencias

• Manual de usuario