AVEVA PI
Référence du pilote AVEVA PI : la PI Web API en HTTPS, authentification par jeton bearer ou Basic, adressage AF et point PI, lectures et écritures.
Le pilote AVEVA PI lit et écrit un AVEVA PI System à travers la PI Web API, l'interface REST du système (du JSON sur HTTP). C'est un pilote en mode client (Ganter Lab se connecte au service PI Web API) et le transport est HTTPS par défaut : le pilote place les identifiants de l'équipement sur chaque requête qu'il émet, si bien qu'une connexion non chiffrée les publierait. Le HTTP simple n'existe que comme choix explicite par équipement.
Un tag adresse un attribut AF, un point PI, ou un flux brut de la PI Web API, et lit sa valeur instantanée (courante).
Champs de connexion
| Champ | Ce que c'est | Format | Défaut |
|---|---|---|---|
| Hôte | Le nom d'hôte ou l'adresse IP du serveur PI Web API. Une adresse peut être collée entière (https://pi-host/piwebapi) : https:// ou http:// devant règle le transport plus bas en conséquence et est retiré, un port va dans le champ du port et le chemin dans le chemin de la ressource. |
Nom d'hôte ou IP | vide |
| Port | Le port TCP du service. 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 | Le chemin de racine de service ajouté à l'autorité. Vide, ou un simple /, signifie la racine standard de la PI Web API, piwebapi. Tout autre chemin est le chemin que le pilote ouvre, exactement tel qu'il est tapé : un service publié derrière un proxy inverse sur /pi est joint sur /pi, et rien ne lui est ajouté. Écrivez tout le chemin dont un navigateur aurait besoin, piwebapi compris là où le service y répond encore. |
texte de chemin | vide (= piwebapi) |
| Envoyer en HTTP simple | Fait descendre ce seul équipement du HTTPS vers le HTTP en clair. Décoché signifie HTTPS, le transport normal de la PI Web API. Le volet énonce la conséquence : en HTTP simple, le jeton bearer ou le mot de passe est envoyé sans chiffrement à chaque requête. À n'employer que pour une PI Web API 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 la racine de service (HEAD, en se rabattant sur GET). 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. 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.
Préparer la PI Web API
Le pilote se connecte avec un nom d'utilisateur et un mot de passe par HTTP Basic, ou avec un jeton bearer. La PI Web API est livrée avec Kerberos pour seule méthode d'authentification, et le pilote ne parle pas Kerberos : un service fraîchement installé refuse donc en général la station tant que l'une de ces voies n'est pas mise en place sur le serveur de la PI Web API :
| Voie | Où elle se règle | Ensuite |
|---|---|---|
| Authentification Basic | PI Web API Admin Utility, page Authentication Options : cochez Basic et appliquez. Ou PI System Explorer, base Configuration, l'élément System Configuration sous OSIsoft > PI Web API > le nom de l'instance : ajoutez Basic à l'attribut AuthenticationMethods et archivez la modification par un check in. Redémarrez le service de la PI Web API. | Nom d'utilisateur et Mot de passe, sur la carte Connexion de l'équipement, portent un compte Windows que le PI System accepte ; un compte de domaine s'écrit DOMAINE\utilisateur |
| Jeton bearer | PI Web API configurée avec AVEVA Identity Manager (authentification Bearer) | Le jeton va dans le champ Jeton bearer de l'équipement |
Quand le service répond 401 sans proposer Basic, la page de l'équipement le dit, avec ces étapes, à la place de l'erreur en anglais du pilote ; quand il propose Basic et refuse le compte que l'équipement a envoyé, la page dit que le nom d'utilisateur ou le mot de passe a été refusé et renvoie à la carte Connexion. L'un comme l'autre de ces avis disparaît de lui-même dès que le service répond. Le journal et l'agent lisent les mêmes étapes. Un jeton bearer que le service refuse est dit dans les mots du pilote lui-même.
Adressage des tags
Le champ Chemin PI du tag accepte quatre formes :
| Forme | Ressemble à | Comment elle est résolue |
|---|---|---|
| Chemin d'attribut AF | \\AFServer\Database\Element\SubElement\|Attribute |
Cherché une fois par attributes?path=… pour obtenir le WebId de l'attribut |
| Chemin de point PI | \\PIServer\TagName |
Cherché une fois par points?path=… pour obtenir le WebId du point |
| WebId | La chaîne WebId opaque elle-même | Employée directement (reconnue comme un long jeton sans \, \| ni /) |
| URL relative | streams/{webId}/value, streamsets/…, attributes?…, points?… |
Envoyée telle quelle sous la racine de service |
Les recherches de chemin sont mises en cache 12 heures, si bien qu'une scrutation en régime établi ne les
répète pas. Pour les trois premières formes, la lecture récupère en GET la valeur instantanée du flux
(streams/{webId}/value) et en extrait le champ JSON Value ; une URL relative est
lue littéralement, pointez-la donc vers un endpoint qui répond par un document de valeur. Le
résultat est converti vers le type de donnée déclaré du tag.
Le verdict propre de l'archive sur l'échantillon est lu avec lui. Une valeur que l'archive marque comme non correcte, comme douteuse, ou comme substituée (un nombre saisi à la main plutôt que mesuré) n'est pas une lecture du matériel, elle n'est donc pas publiée comme telle : le tag passe en mauvaise qualité et la raison dit lequel des trois cas s'est présenté. Il en va de même quand la réponse ne porte aucune valeur, ou répond par un état numérique plutôt qu'une valeur unique, auquel cas le nom de l'état fait partie de la raison. Rien n'est inventé à leur place, et aucun document n'arrive comme s'il était la mesure.
Une lecture que la PI Web API refuse (un état hors de la plage de succès, comme un compte
sans accès en lecture au point) passe elle aussi en mauvaise qualité, et la raison nomme
l'état et ce que le service a dit avec lui (HTTP 403 Forbidden: …). Un chemin que le
service ne connaît pas le dit, en nommant le chemin. Une adresse vide, une adresse dans aucune
des quatre formes et une réponse qui ne se lit pas selon le type déclaré donnent aussi la raison.
Un service 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.
Exemples :
\\PI-SRV01\FURNACE.TEMP: un point PI classique.\\AF-SRV\Plant\Line 3\Furnace|Temperature: un attribut AF.streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value: une URL de flux brute, utile quand vous détenez déjà le WebId depuis un autre outil.
Écritures
Les tags dont le mode d'accès est inscriptible écrivent par l'endpoint de flux de la PI Web API : un
POST de {"Timestamp":"*","Value":…} (l'horodatage * signifie maintenant) vers
streams/{webId}/value. L'écriture a besoin d'un WebId résoluble, elle fonctionne donc pour les tags
adressés par chemin AF, par chemin de point PI, par WebId, et aussi par une URL relative streams/… :
le WebId est lu dans cette URL et l'écriture atterrit sur l'endpoint de valeur de ce flux,
quelle que soit la sous-ressource de lecture (recorded, par exemple) que l'adresse portait au-delà
de lui. Trois formes relatives sont refusées, parce que chacune répond par un document plutôt
que par la valeur d'un flux et qu'une écriture adresserait la mauvaise ressource :
streamsets/…, attributes?… et points?…. Le refus nomme les formes acceptées.
Que l'écriture aboutisse dépend aussi de la configuration de la PI Web API pour les écritures
et de l'accès en écriture du compte sur le point. Une écriture que la PI Web API rejette reçoit pour réponse l'état et ce que le service a dit avec lui (par exemple HTTP 403 Forbidden: …), et celui qui a écrit la valeur en lit la raison.
La valeur que vous tapez dans la zone d'écriture du tag est la valeur physique ; 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, Int64, Float, Double et String. Les points PI numériques sont typiquement Float ou Double. Un état numérique n'est pas une valeur unique, si bien qu'un point qui répond par un état se lit en mauvaise qualité en nommant l'état, quel que soit le type que le tag déclare.
Commandes
Au-delà de la lecture et de l'écriture de points, on peut demander à un endpoint de la PI Web API de faire quelque chose, et les requêtes qu'il accepte sont l'affaire du service. Déclarez-en chacune sur l'équipement, dans la carte Commandes de sa page : un nom, l'URL relative à laquelle elle est envoyée en POST sous la racine de service, et éventuellement le nom de la seule valeur qu'elle prend, qui voyage dans le corps de la requête. Le verbe Exécuter de la ligne l'envoie et rapporte ce que le service a répondu ; la commande devient aussi une méthode sur l'équipement dans l'espace d'adressage OPC UA propre à cette station. Une requête que le service refuse reçoit pour réponse l'état et ce que le service a dit avec lui, dans les mêmes mots que ceux d'une écriture refusée.
Découverte
Le bouton Découvrir lit un service. Placez son adresse et l'élément AF d'où part le parcours
dans la carte Portée du balayage de la page du pilote, séparés par un # :
https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3. Le balayage résout cet élément, parcourt
chaque élément en dessous, et propose l'équipement avec un point par attribut, chacun adressé
par son propre flux. Le balayage lit le service sans identifiants, parce qu'il tourne avant que
l'équipement qui les porterait n'existe, si bien qu'une PI Web API qui authentifie chaque requête
ne répond rien et que l'équipement s'ajoute à la main : ajoutez le service par son hôte et ajoutez
les tags par leurs chemins AF ou PI, comme le décrit l'ajout d'un équipement sur la page
Connector.
La page d'un équipement PI n'affiche pas Découvrir les tags : le parcours part d'un élément AF, que l'équipement ne garde pas, donc les points d'un équipement viennent de ce balayage ou s'ajoutent à la main (voir Découvrir les tags d'un équipement).
Accès des équipements
Une PI Web API dont le port n'a aucun certificat attribué crée et utilise son propre certificat autosigné, 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 AVEVA PI, 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 le serveur PI 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 une PI Web API appelée 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é, un autre certificat lié au port), 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 AVEVA PI. 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 AVEVA PI. » 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. Un balayage du service depuis la carte Portée du balayage se heurte aux mêmes décisions : un certificat inconnu termine le balayage avec cette phrase et attend ici.
Les décisions sont conservées dans le dossier de données de la station, sous ua\pki\aveva-pi, 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.