HTTP

Référence du pilote HTTP : scruter des endpoints HTTP et HTTPS comme des tags, les identifiants, la composition du chemin, l'analyse du corps, les écritures PUT et les types.

Afficher en Markdown

Le pilote HTTP scrute des endpoints HTTP génériques comme des tags : un capteur LAN avec un petit serveur web, une passerelle qui publie des relevés à des URL fixes, un service à vous. C'est le pilote client le plus simple du produit : Ganter Lab se connecte au matériel par de simples requêtes GET et lit chaque corps de réponse comme une valeur.

Deux propriétés tracent la limite de ce à quoi il sert :

Le transport est le choix de l'équipement lui-même. Un équipement joint son service par TLS tant que sa case Envoyer en HTTP simple ne dit pas autre chose, et un hôte écrit avec http:// ou https:// devant déplace cette case et est conservé comme hôte seul, de sorte que les deux ne peuvent jamais se contredire. Dans les deux cas, le pilote envoie l'identifiant de l'équipement à chaque requête, un nom d'utilisateur et un mot de passe en HTTP Basic ou un jeton bearer. Ce que les pilotes AVEVA PI et Redfish apportent encore pour ces deux services, c'est leur vocabulaire : chemins PI et WebIds, arbres de ressources Redfish, que ce pilote ignore.
Le corps de réponse entier est la valeur. Le pilote n'est pas un extracteur de champ JSON : un tag numérique attend que le corps soit le nombre nu.

Champs de connexion

Champ	Ce que c'est	Format	Défaut
Hôte	Le nom d'hôte ou l'adresse IP de l'endpoint. Un hôte écrit avec `http://` ou `https://` devant déplace la case du transport ci-dessous pour qu'elle corresponde, et il est conservé sans lui. Un port écrit après l'hôte (`:8080`) va dans le champ Port et un chemin après lui (`/api`) dans le chemin de ressource, si bien qu'on peut coller ici une adresse entière comme `http://192.168.0.5:8080/api`. Une adresse IPv6 garde ses crochets.	Nom d'hôte, IP, ou l'un ou l'autre précédé de `http://` ou `https://`	vide
Port	Le port TCP. Un nouvel équipement le laisse vide, et un champ vide signifie le port sur lequel le transport choisi répond, 443 en HTTPS et 80 en clair : le champ affiche ce port en gris et suit le choix du transport ; un équipement enregistré avec 0 se lit de la même façon.	De 1 à 65535, ou vide	vide
Chemin de ressource	Un préfixe de chemin facultatif placé devant le chemin de chaque tag, par exemple `api/v2`. Vide ne préfixe rien.	texte de chemin	vide
Envoyer en HTTP simple	Fait descendre ce seul équipement du HTTPS vers le HTTP en clair. Décoché signifie HTTPS, ce qui garde un identifiant hors du câble. Le volet énonce la conséquence : en HTTP simple, les requêtes, et tout identifiant porté par l'équipement, circulent sans chiffrement. À employer pour un endpoint qui ne répond sur aucun autre transport.	coché / décoché	décoché
Nom d'utilisateur	Le compte pour l'authentification HTTP Basic, employé seulement quand aucun jeton bearer n'est réglé. Vide (et sans jeton) laisse les requêtes anonymes.	Texte libre	vide
Mot de passe	Le mot de passe associé au nom d'utilisateur. Protégé au repos par utilisateur Windows ; un secret saisi sous un autre compte Windows s'affiche comme illisible et doit être saisi de nouveau.	Texte libre	vide
Jeton bearer	Un jeton envoyé en `Authorization: Bearer …` à chaque requête. Quand il est réglé, il l'emporte sur la paire nom d'utilisateur et mot de passe. Protégé au repos de la même façon.	Texte de jeton	vide

À la connexion, le pilote vérifie l'endpoint par une requête HEAD vers l'adresse configurée, l'hôte suivi du chemin de ressource, en se rabattant sur GET quand HEAD n'est pas implémenté ; une adresse qui répond correctement à l'une ou l'autre compte comme joignable. Un service dont la racine répond 404 alors que son API répond normalement est donc en ligne, tant que le chemin de ressource pointe vers l'API. En HTTPS, le certificat TLS du service est accepté quand Windows lui fait confiance, ou quand vous avez approuvé ce certificat précis sous Accès des équipements, sur la page de ce pilote. Un identifiant sur un équipement descendu au HTTP simple voyage sans chiffrement, et la station l'écrit dans le journal du connecteur au moment où l'équipement se connecte. Chaque requête reçoit dix secondes : un endpoint qui accepte la connexion puis ne dit rien coûte une lecture, pas l'équipement entier, parce que les autres tags de l'équipement sont lus dans la même passe. La période de scrutation est configurable : la valeur par défaut de l'équipement (1000 ms) s'applique à chaque tag qui ne donne pas la sienne.

Adressage des tags

Le champ Chemin du tag est le chemin d'URL relatif au chemin de ressource de l'équipement :

Champ	Ce qu'il fait	Valeurs	Défaut
Chemin	Le chemin demandé pour ce tag. L'URL complète est `<transport>://<host>:<port>/<chemin de ressource>/<chemin>`.	Texte libre (obligatoire)	vide

Exemple : l'hôte 192.168.0.40 descendu au HTTP simple, le chemin de ressource api et le chemin de tag sensors/temp scrutent http://192.168.0.40/api/sensors/temp.

Lectures

Chaque scrutation récupère l'URL du tag en GET et analyse le corps de réponse entier selon le type de donnée déclaré du tag :

Type	Corps accepté
Float	Un nombre au format invariant (`21.5`, point décimal, sans séparateur de milliers)
Int32	Un entier (`42`)
Boolean	`true` ou `false`
String	N'importe quoi ; le corps est la valeur telle quelle (un document JSON arrive sous forme de texte brut)

Un corps que le type déclaré ne sait pas analyser, ou un code d'état hors succès, se lit comme une lecture en échec : le tag passe en mauvaise qualité et sa politique de lecture en échec décide de ce qui est présenté, comme le décrit la page Connector. Un état hors succès est l'endpoint qui refuse la lecture, et la raison du tag nomme l'état et cite ce que l'endpoint a dit avec lui (HTTP 404 Not Found: …), dans les mêmes mots que ceux d'une écriture ou d'une commande refusée. Un corps que le type déclaré ne sait pas analyser donne au tag une raison qui cite ce qui n'a pas pu être lu, et l'équipement reste connecté. Un endpoint qui ne répond pas du tout, c'est la connexion de l'équipement qui échoue : l'équipement le signale et se reconnecte, et ses tags renvoient à lui. La ligne rouge du tag dit un tel statut dans la langue de la station, avec ce qu'il signifie pour 401, 403 et 404, et un corps qui ne s'analyse pas comme une réponse qui ne se lit pas comme une valeur du type du tag ; la page Événements garde les mots de l'endpoint lui-même.

Écritures

Les tags dont le mode d'accès est inscriptible écrivent en PUT vers la même URL : le corps est la valeur en JSON, envoyée avec le type de contenu application/json. Un nombre part en littéral nu (42.5), un booléen en true ou false, et le texte part entre guillemets ("automatic"). C'est l'endpoint qui décide de ce qu'il en fait ; un état hors succès est l'endpoint qui refuse la valeur : le refus nomme l'état et cite ce que l'endpoint a dit avec lui, dans les mêmes mots que celui d'une commande refusée, et celui qui a écrit la valeur en lit la raison. Comme partout ailleurs, la zone d'écriture prend la valeur physique et les étapes de conversion du tag sont remontées avant que la valeur brute ne parte sur le bus, comme le décrit la page Connector.

Types de donnée pris en charge

Boolean, Int32, Float et String.

Commandes

Un tag lit une valeur ; une commande demande au service de faire quelque chose. Déclarez-en chacune sur l'équipement, dans la carte Commandes de sa page : un nom, le chemin auquel elle est envoyée en POST (sous l'adresse propre de l'équipement, exactement comme l'est le chemin d'un tag), et éventuellement le nom de la seule valeur qu'elle prend. Le verbe Exécuter de la ligne l'envoie et rapporte ce que le service a répondu, et la commande devient aussi une méthode sur l'équipement dans l'espace d'adressage OPC UA propre à cette station, si bien que tout ce qui peut appeler une méthode peut l'envoyer. La valeur que vous tapez est envoyée dans le corps de la requête, telle qu'écrite.

Ce que le service répond est le résultat de la commande. Un état que le service retourne hors de la plage de succès est le service qui refuse la commande, pas la connexion qui échoue : le refus nomme l'état et cite ce que le service a dit avec lui (« HTTP 500 Internal Server Error : le brûleur est en sécurité »), et rien d'autre sur l'équipement n'en est dérangé.

Découverte

Le pilote n'a pas de balayage de découverte. Ajoutez chaque endpoint par son hôte et chaque valeur par son chemin ; l'ajout d'un équipement est décrit sur la page Connector.

Accès des équipements

Un endpoint HTTPS au certificat autosigné, ou émis par une autorité à lui, présente un certificat dont aucune racine installée dans Windows ne se porte garante. Cette racine n'a pas besoin d'être installée sur cet ordinateur. La première connexion est refusée, l'équipement indique En attente de l'approbation du certificat dans l'arborescence et sur sa page, dont le bouton Examiner le certificat ouvre cette carte sur le certificat, et le certificat attend sous Accès des équipements, à la fin de la page du pilote HTTP, la même carte que porte la page du pilote OPC UA, jusqu'à ce que vous décidiez :

Groupe	Ce qu'il liste	Ce que vous pouvez faire
En attente d'approbation	Chaque certificat refusé, sous le nom qu'il déclare : son empreinte SHA-256, l'adresse où il a été rencontré, quand il a essayé pour la dernière fois et combien de fois, et ses détails (sujet, émetteur, noms de domaine, dates de validité). Celui qu'a ouvert Examiner le certificat d'un équipement est marqué Sélectionné pour examen.	Approuver accepte le certificat dès la tentative de connexion suivante. Bloquer continue de le refuser sans le lister de nouveau ici. Écarter tous les certificats en attente vide la liste sans rien approuver ni bloquer.
Équipements approuvés	Les certificats que vous avez approuvés ou importés, avec qui a décidé et quand, et l'adresse où chacun a été rencontré en dernier.	Retirer l'approbation ferme la connexion et remet le certificat dans la liste. Importer un certificat approuve un fichier de certificat public que vous avez déjà (.der, .cer, .crt ou .pem) avant la première connexion.
Équipements bloqués	Les certificats que vous avez bloqués. Un certificat bloqué est refusé même si Windows lui fait confiance.	Débloquer remet le certificat dans la liste, sans l'approuver.

Vérifiez l'empreinte auprès de la personne qui gère l'équipement avant d'approuver le certificat. Une approbation accepte ce certificat et aucun autre, et seulement dans ses dates de validité ; elle tient lieu de la racine qui manque à Windows et du nom que porte le certificat, si bien que un endpoint appelé par son adresse IP se connecte même si son certificat porte un autre nom, et rien d'autre du certificat n'est assoupli. Quand l'équipement répond à une adresse dont vous aviez approuvé le certificat avec un autre (un certificat renouvelé), la lecture s'arrête, le nouveau attend ici, et la station signale « Certificat modifié : <nom> » avec un bouton Examiner. Un certificat auquel Windows fait déjà confiance est accepté comme avant et n'apparaît jamais ici ; rien n'est approuvé automatiquement.

L'échec du pilote lui-même dit le motif au lieu d'une erreur TLS sans nom : « Le certificat de cet équipement (les 16 premiers caractères de l'empreinte) attend votre approbation sous Accès des équipements, sur la page du pilote HTTP. La lecture commence dès que vous l'approuvez. » Un certificat bloqué donne « …est bloqué à cette station. Examinez-le sous Accès des équipements, sur la page du pilote HTTP. » Un certificat hors de ses dates de validité, révoqué ou à la signature invalide est refusé avec ce motif et n'est jamais listé, car aucune approbation ne le rend valable.

Les décisions sont conservées dans le dossier de données de la station, sous ua\pki\http, et survivent à un redémarrage. Les verbes ne sont dessinés que pour un rôle qui peut configurer le Connector, et ils n'agissent que dans la fenêtre de la station elle-même : un navigateur sur un autre appareil lit la carte sans la changer, et aucun outil d'agent n'approuve un certificat (connector_browse signale l'équipement en attente avec awaitingCertificate). La liste garde jusqu'à 100 certificats en attente d'approbation ; une fois pleine, un nouveau est encore refusé mais pas listé, et la carte le dit.