Integración HTTP
El protocolo HTTP integra dispositivos y servicios que utilizan HTTP simple: API REST, servicios en la nube con API local o relés de red sencillos. Funciona en dos direcciones:
- Solicitudes salientes — cuando cambia el valor de un widget, HyperVisu envía una solicitud (control de dispositivo o llamada a un webhook).
- Consulta periódica — HyperVisu solicita periódicamente una URL y extrae un valor de la respuesta para un objeto del widget.
Conexiones. Active primero HTTP Protocol en la página Services (véase «Servicios y protocolos»); está desactivado en un servidor nuevo. HTTP admite varias conexiones: una por Base URL, cada una con sus propios Poll Interval (seconds), Timeout (ms) y autenticación (véase «Conexiones»). El tiempo de espera se expresa en milisegundos, de 1000 a 120000; si se deja vacío, la solicitud espera 30 segundos.
Seleccione el Authentication Type que requiere la API. Cambiar el tipo vacía todos los campos de credenciales.
| Authentication Type | Datos que debe proporcionar | Cómo se envían |
|---|---|---|
| None | Sin credenciales. | No se añade nada. |
| API Key (Header) | Header Name y API Key. | Una cabecera con ese nombre y la clave. |
| API Key (Query Parameter) | Query Parameter y API Key. | Se añaden a la URL de cada solicitud. |
| Basic Authentication | Username y Password. | La cabecera de autorización Basic estándar. |
| Bearer Token | Bearer Token. | La cabecera de autorización Bearer estándar. |
| Custom Headers | Una fila por cabecera, con nombre y valor; Add Header añade una fila. | Todas las filas, en cada solicitud. |
Complete ambos campos de cada par: un par con un campo vacío no se envía. API Key, Password y Bearer Token se ocultan en el editor; los valores introducidos en Custom Headers se muestran en texto claro.
Una conexión HTTP no tiene botón Test. Su estado permanece en State unknown hasta que un objeto vinculado intercambia una solicitud; entonces Connected significa que la última solicitud fue aceptada y No reply since aparece tras una solicitud fallida.
📘 Nota: Un intervalo de consulta de
0convierte la conexión en solo escritura — no se consulta nada, solo se envían solicitudes salientes. Un intervalo vacío también significa que el endpoint nunca se consulta: introduzca el valor, el60gris es solo una indicación.
Vincular un objeto. Para cada objeto se definen Path y HTTP Method y, para los valores consultados, cómo extraer la lectura de la respuesta mediante Parse Method y Parse Path:
- JSON — una ruta con sintaxis de puntos y matrices, por ejemplo
data.sensors[0].temperature. Un índice negativo como[-1]lee el último elemento; no se admiten filtros ni comodines. - Pattern Matching — para respuestas que no sean JSON. Parse Path debe empezar por
PATTERN=, por ejemploPATTERN=Temp:\s\v. Cambiar el método de análisis vacía Parse Path, por lo que debe introducirlo después de elegir el método.
Para solicitudes salientes, establezca HTTP Method en POST o PUT y seleccione Content Type. Request Body Template es una plantilla en la que ${value} se sustituye por el valor enviado, por ejemplo {"state": ${value}}.
📘 Nota: La consulta periódica siempre envía un GET al Path del objeto. Un objeto POST o PUT solo envía una solicitud cuando cambia su valor.
Ejemplo práctico — calidad del aire exterior desde la API de un sensor local
Un monitor local de calidad del aire expone GET http://192.168.1.140/api/current, devuelve {"pm25": 8.4, "aqi": 35} y requiere la clave API en una cabecera X-Api-Key.
- Cree una conexión HTTP: Base URL
http://192.168.1.140, Poll Interval (seconds)60, Timeout (ms)5000, Authentication Type API Key (Header), Header NameX-Api-Key, la clave en API Key (véase «Conexiones»). - En Devices, añada un widget Analog Input «Calidad del aire». En Protocol, seleccione su conexión HTTP, que aparece con el nombre que le ha asignado.
- En su objeto de valor, establezca Path en
/api/current, deje HTTP Method en GET y Parse Method en JSON e introduzcaaqien Parse Path. - Pulse Save object, después Apply changes en la barra lateral y confirme. La lectura se actualiza cada minuto; configure las unidades y los decimales en el objeto (véase «Ajustes de objetos, registro y notificaciones»).
- Tras la siguiente consulta, compruebe que la conexión muestra Connected en la página Connections y compare el widget con la respuesta real de la API.
Vinculación HTTP
Los objetos HTTP también se configuran en el diálogo de ajustes del objeto (véase «Ajustes de objetos, registro y notificaciones»). La sección HTTP define una solicitud por objeto:
| Campo | Descripción |
|---|---|
| Path | Se añade a la URL base de la conexión (por ejemplo weather?q=London). |
| HTTP Method | GET, POST o PUT. |
| Content Type | Para POST/PUT: JSON, TEXT o FORM. JSON y FORM establecen la cabecera de tipo de contenido correspondiente; TEXT no envía ninguna. |
| Parse Method | JSON — la respuesta es JSON y Parse Path identifica el valor. Pattern Matching — la respuesta es texto y Parse Path contiene un patrón. La ayuda de sintaxis integrada documenta ambos. Cambiar el método de análisis vacía Parse Path, por lo que debe elegir primero el método. |
| Parse Path | Con JSON: una ruta simple — notación de puntos (data.power), índice de matriz (sensors[0]), índice negativo ([-1] para el último elemento) y prefijo opcional $.. No se admiten filtros ni comodines. Con Pattern Matching: el patrón, que debe empezar por PATTERN= — por ejemplo PATTERN=Temp:\s\v. |
| Request Body Template | Para POST/PUT: el cuerpo que se envía, con ${value} como marcador del valor escrito — por ejemplo {"state":${value}}. |
La lectura utiliza el intervalo de consulta de la conexión; un intervalo de 0 convierte el endpoint en solo escritura (véase «Conexiones»). La consulta periódica siempre envía un GET al Path del objeto; un objeto POST o PUT solo envía su solicitud cuando cambia su valor. El capítulo HTTP incluye un ejemplo práctico.