Intégration HTTP
Le protocole HTTP intègre les appareils et services qui communiquent en HTTP : API REST, services cloud disposant d’une API locale ou simples relais réseau. Il fonctionne dans deux sens :
- Requêtes sortantes — lorsque la valeur d’un widget change, HyperVisu envoie une requête (commande d’appareil ou appel de webhook).
- Interrogation périodique — HyperVisu interroge périodiquement une URL et extrait une valeur de la réponse dans un objet de widget.
Connexions. Activez d’abord HTTP Protocol sur la page Services (voir « Services et protocoles ») ; il est désactivé sur un nouveau serveur. HTTP accepte plusieurs connexions : une connexion par Base URL, chacune avec ses propres Poll Interval (seconds), Timeout (ms) et authentification (voir « Connexions »). Le délai est exprimé en millisecondes, de 1000 à 120000 ; si le champ reste vide, une requête attend 30 secondes.
Choisissez le Authentication Type requis par l’API. Changer de type vide tous les champs d’identification.
| Authentication Type | Informations à fournir | Mode d’envoi |
|---|---|---|
| None | Aucun identifiant. | Rien n’est ajouté. |
| API Key (Header) | Header Name et API Key. | Un en-tête portant ce nom et contenant la clé. |
| API Key (Query Parameter) | Query Parameter et API Key. | Ajoutés à l’URL de chaque requête. |
| Basic Authentication | Username et Password. | L’en-tête d’autorisation Basic standard. |
| Bearer Token | Bearer Token. | L’en-tête d’autorisation Bearer standard. |
| Custom Headers | Une ligne par en-tête, avec nom et valeur ; Add Header ajoute une ligne. | Toutes les lignes, à chaque requête. |
Remplissez les deux champs de chaque paire : une paire dont un champ est vide n’est pas envoyée. API Key, Password et Bearer Token sont masqués dans l’éditeur ; les valeurs saisies sous Custom Headers sont affichées en clair.
Une connexion HTTP n’a pas de bouton Test. Son état reste State unknown jusqu’à ce qu’un objet lié ait échangé une requête ; Connected signifie alors que la dernière requête a été acceptée, et No reply since apparaît après un échec.
📘 Remarque : Un intervalle d’interrogation de
0rend la connexion accessible uniquement en écriture — aucune interrogation, seules les requêtes sortantes sont envoyées. Un intervalle laissé vide signifie également que le point de terminaison n’est jamais interrogé : saisissez la valeur, le60gris est seulement une indication.
Liaison d’un objet. Pour chaque objet, définissez Path et HTTP Method et, pour les valeurs interrogées, la méthode d’extraction de la réponse avec Parse Method et Parse Path :
- JSON — un chemin utilisant des points et des indices de tableau, par exemple
data.sensors[0].temperature. Un indice négatif tel que[-1]lit le dernier élément ; les filtres et les caractères génériques ne sont pas pris en charge. - Pattern Matching — pour les réponses non JSON. Parse Path doit commencer par
PATTERN=, par exemplePATTERN=Temp:\s\v. Changer de méthode d’analyse vide Parse Path ; saisissez-le donc après avoir choisi la méthode.
Pour les requêtes sortantes, réglez HTTP Method sur POST ou PUT et choisissez Content Type. Request Body Template est un modèle dans lequel ${value} est remplacé par la valeur envoyée, par exemple {"state": ${value}}.
📘 Remarque : L’interrogation périodique envoie toujours un GET au Path de l’objet. Un objet POST ou PUT n’envoie une requête que lorsque sa valeur change.
Exemple pratique — qualité de l’air extérieur depuis l’API d’un capteur local
Un capteur local de qualité de l’air expose GET http://192.168.1.140/api/current, renvoie {"pm25": 8.4, "aqi": 35} et exige la clé API dans un en-tête X-Api-Key.
- Créez une connexion 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 clé dans API Key (voir « Connexions »). - Dans Devices, ajoutez un widget Analog Input « Qualité de l’air ». Sous Protocol, sélectionnez votre connexion HTTP, affichée sous le nom que vous lui avez donné.
- Sur son objet de valeur, réglez Path sur
/api/current, laissez HTTP Method sur GET et Parse Method sur JSON, puis saisissezaqidans Parse Path. - Cliquez sur Save object, puis sur Apply changes dans la barre latérale et confirmez. La mesure se met à jour chaque minute ; définissez les unités et les décimales sur l’objet (voir « Paramètres des objets, journalisation et notifications »).
- Après l’interrogation suivante, vérifiez que la connexion affiche Connected sur la page Connections, puis comparez le widget avec la réponse réelle de l’API.
Liaison HTTP
Les objets HTTP se configurent également dans la boîte de dialogue des paramètres de l’objet (voir « Paramètres des objets, journalisation et notifications »). La section HTTP définit une requête par objet :
| Champ | Description |
|---|---|
| Path | Ajouté à l’URL de base de la connexion (par exemple weather?q=London). |
| HTTP Method | GET, POST ou PUT. |
| Content Type | Pour POST/PUT : JSON, TEXT ou FORM. JSON et FORM définissent l’en-tête de type de contenu correspondant ; TEXT n’en envoie aucun. |
| Parse Method | JSON — la réponse est en JSON et Parse Path désigne la valeur. Pattern Matching — la réponse est du texte et Parse Path contient un motif. L’aide de syntaxe intégrée documente les deux. Changer de méthode d’analyse vide Parse Path ; choisissez donc d’abord la méthode. |
| Parse Path | Avec JSON : un chemin simple — notation par points (data.power), indice de tableau (sensors[0]), indice négatif ([-1] pour le dernier élément) et préfixe facultatif $.. Les filtres et les caractères génériques ne sont pas pris en charge. Avec Pattern Matching : le motif, qui doit commencer par PATTERN= — par exemple PATTERN=Temp:\s\v. |
| Request Body Template | Pour POST/PUT : le corps à envoyer, avec ${value} comme variable représentant la valeur écrite — par exemple {"state":${value}}. |
La lecture utilise l’intervalle d’interrogation de la connexion ; un intervalle de 0 rend le point de terminaison accessible uniquement en écriture (voir « Connexions »). L’interrogation périodique envoie toujours un GET au Path de l’objet ; un objet POST ou PUT n’envoie sa requête que lorsque sa valeur change. Un exemple pratique figure dans le chapitre HTTP.