HTTP

Référence du pilote HTTP : scruter des endpoints HTTP et HTTPS comme des tags, les identifiants, la correspondance des chemins, 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 du réseau local avec un petit serveur web, une passerelle qui publie ses relevés à des URL fixes, un service à vous. C'est le pilote en mode client le plus simple du produit : Ganter Lab se connecte à l'équipement 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 atteint 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 gardé comme hôte tout seul, si bien que les deux ne peuvent jamais se contredire. Dans les deux cas, le pilote envoie l'identifiant de l'équipement à chaque requête, soit un nom d'utilisateur et un mot de passe en HTTP Basic, soit un jeton porteur. Ce que les pilotes AVEVA PI et Redfish ajoutent encore pour ces deux services, c'est leur vocabulaire : chemins PI et WebIds, arbres de ressources Redfish, dont ce pilote ne sait rien.
Le corps entier de la réponse 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	Par 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 plus bas pour qu'elle concorde, et il est gardé 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 complète 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 de `https://`	vide
Port	Le port TCP. Un nouvel équipement le laisse vide, et un champ vide veut dire 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 de HTTPS vers du HTTP en clair. Désactivé veut dire HTTPS, ce qui tient un identifiant hors du fil. Le volet énonce la conséquence : en HTTP simple, les requêtes, et tout identifiant porté par l'équipement, partent en clair. Employez-le pour un endpoint qui ne répond sur aucun autre transport.	activé / désactivé	désactivé
Nom d'utilisateur	Le compte pour l'authentification HTTP Basic, employé seulement quand aucun jeton porteur n'est posé. 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 paraît illisible et doit être saisi de nouveau.	Texte libre	vide
Jeton porteur	Un jeton envoyé comme `Authorization: Bearer …` à chaque requête. Quand il est posé, il l'emporte sur la paire nom d'utilisateur et mot de passe. Protégé au repos de la même façon.	Texte du 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 retombant 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 part en clair, et la station l'inscrit au journal du connecteur quand 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 tout l'équipement, parce que les autres tags de l'équipement sont lus dans la même passe. L'intervalle de scrutation est configurable : la valeur de l'équipement (1000 ms) s'applique à chaque tag qui n'énonce pas la sienne.

Adressage d'un tag

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

Champ	Ce qu'il fait	Valeurs	Par défaut
Chemin	Le chemin demandé pour ce tag. L'URL complète est `<transport>://<hôte>:<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 fait un GET sur l'URL du tag et analyse le corps entier de la réponse 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 comme son texte brut)

Un corps que le type déclaré ne peut pas analyser, ou un code de statut hors succès, se lit comme une lecture en échec : le tag passe en mauvaise qualité et sa politique d'échec de lecture décide de ce qui est présenté, comme décrit sur la page Connector. Un statut hors succès est l'endpoint qui refuse la lecture, et la raison du tag nomme le statut 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 par 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 comme littéral nu (42.5), un booléen comme true ou false, et le texte part entre guillemets ("automatic"). L'endpoint décide de ce qu'il en fait; un statut hors succès est l'endpoint qui refuse la valeur : le refus nomme le statut 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 décrit sur 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 chacune sur l'équipement, dans la carte Commandes de sa page : un nom, le chemin auquel elle est envoyée par POST (sous l'adresse propre de l'équipement, exactement comme le chemin d'un tag), et au besoin le nom de l'unique 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 sait appeler une méthode peut la lancer. La valeur que vous tapez est envoyée comme corps de la requête, telle quelle.

Ce que le service répond est le résultat de la commande. Un statut que le service renvoie hors de la plage de succès est le service qui refuse la commande, non la connexion qui échoue : le refus nomme le statut et cite ce que le service a dit avec lui (« HTTP 500 Internal Server Error : le brûleur est en verrouillage »), 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.