AVEVA PI
Référence du pilote AVEVA PI : PI Web API en HTTPS, authentification par jeton porteur ou Basic, adressage AF et point PI, lectures et écritures.
Le pilote AVEVA PI lit et écrit un système AVEVA PI par 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 pose les identifiants de l'équipement sur chaque requête qu'il fait, donc 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 PI Web API, et lit sa valeur instantanée (courante).
Champs de connexion
| Champ | Ce que c'est | Format | Par 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 | Le port TCP du service. Zéro veut dire la valeur par défaut du pilote, 443. | numéro de port | 0 (= 443) |
| Chemin de ressource | Le chemin de la racine de service ajouté à l'autorité. Vide, ou une simple /, veut dire la racine standard de PI Web API, piwebapi. Tout autre chemin est le chemin que le pilote ouvre, exactement comme il est tapé : un service publié derrière un mandataire inverse sur /pi est atteint à /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 de HTTPS vers du HTTP en clair. Désactivé veut dire HTTPS, le transport normal de PI Web API. Le volet énonce la conséquence : en HTTP simple, le jeton porteur ou le mot de passe part en clair à chaque requête. Ne l'employez que pour un PI Web API 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 la racine de service (HEAD, en retombant sur GET). En HTTPS, le certificat TLS du service doit passer la validation de certificat habituelle de Windows. 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 PI du tag accepte quatre formes :
| Forme | Ressemble à | Comment elle est résolue |
|---|---|---|
| Chemin d'attribut AF | \\AFServer\Database\Element\SubElement\|Attribute |
Recherché une fois par attributes?path=… pour obtenir le WebId de l'attribut |
| Chemin de point PI | \\PIServer\TagName |
Recherché une fois par points?path=… pour obtenir le WebId du point |
| WebId | La chaîne WebId opaque elle-même | Employée directement (reconnue à ce qu'elle est 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 pendant 12 heures : la scrutation en régime établi
ne les répète donc pas. Pour les trois premières formes, la lecture fait un GET sur la
valeur instantanée du flux (streams/{webId}/value) et en extrait le champ JSON Value;
une URL relative est lue littéralement, alors pointez-la 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 à l'archive sur l'échantillon est lu avec lui. Une valeur que l'archive marque comme non bonne, comme douteuse, ou comme substituée (un nombre saisi à la main plutôt que mesuré) n'est pas une lecture de l'équipement : elle n'est donc pas publiée comme telle. Le tag passe en mauvaise qualité et la raison dit lequel des trois cas c'était. Il en va de même quand la réponse ne porte aucune valeur, ou répond par un état numérique plutôt que par une valeur unique, auquel cas le nom de cet é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 par un autre outil.
Écritures
Les tags dont le mode d'accès est inscriptible écrivent par le point de terminaison de flux de
PI Web API : un POST de {"Timestamp":"*","Value":…} (l'horodatage * veut dire 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/…, dont le WebId est prélevé pour que l'écriture atterrisse 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à. Trois formes relatives sont refusées, parce que chacune
répond par un document plutôt que par la valeur d'un seul 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 PI Web API pour les
écritures et de l'accès en écriture du compte au 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 décrit sur 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 : un point qui répond par un tel é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 PI Web API de faire quelque chose, et les requêtes qu'il accepte sont l'affaire du service. Déclarez chacune sur l'équipement, dans la carte Commandes de sa page : un nom, l'URL relative à laquelle elle est envoyée par POST sous la racine de service, et au besoin le nom de l'unique valeur qu'elle prend, qui voyage comme 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 seul service. Posez 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
n'existe l'équipement qui les porterait : un PI Web API qui authentifie chaque requête ne
répond donc rien et l'équipement s'ajoute plutôt à la main, en ajoutant le service par son hôte
et les tags par leurs chemins AF ou PI, comme le décrit l'ajout d'un équipement sur la page
Connector.