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. | Nom d'hôte ou IP | vide |
| Port réseau | Le port TCP du service. Zéro signifie la valeur par défaut du pilote, 443. | numéro de port | 0 (= 443) |
| 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 doit passer la validation de certificat Windows normale. 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 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 point de terminaison 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.
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 le point de terminaison 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 le point de terminaison 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.
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 point de terminaison 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.
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.