AVEVA PI

Referenz zum Treiber AVEVA PI: PI Web API über HTTPS, Anmeldung über Bearer-Token oder Basic, Adressierung über AF- und PI-Punkte, Lesen und Schreiben.

Als Markdown ansehen

Der Treiber AVEVA PI liest und schreibt ein AVEVA PI System über die PI Web API, die REST-Schnittstelle dieses Systems (JSON über HTTP). Er ist ein Treiber im Client-Betrieb, Ganter Lab verbindet sich mit dem Dienst PI Web API, und der Übertragungsweg ist standardmäßig HTTPS: Der Treiber legt die Anmeldedaten des Geräts jeder Anfrage bei, eine unverschlüsselte Verbindung würde sie also veröffentlichen. Einfaches HTTP gibt es nur als ausdrückliche Wahl je Gerät.

Ein Tag adressiert ein AF-Attribut, einen PI-Punkt oder einen rohen Datenstrom der PI Web API und liest dessen Momentanwert (snapshot).

Verbindungsfelder

Feld	Was es ist	Format	Standard
Host	Hostname oder IP-Adresse des Servers mit der PI Web API.	Hostname oder IP	leer
Port	Der TCP-Port des Dienstes. Null bedeutet den Standard des Treibers, 443.	Portnummer	0 (= 443)
Ressourcenpfad	Der Wurzelpfad des Dienstes, der an die Autorität angehängt wird. Leer oder ein bloßes `/` bedeutet die übliche Wurzel der PI Web API, `piwebapi`. Jeder andere Pfad ist der Pfad, den der Treiber öffnet, genau wie eingetippt: Ein Dienst, der hinter einem Reverse Proxy unter `/pi` veröffentlicht ist, wird unter `/pi` erreicht, und nichts wird daran angehängt. Schreiben Sie den ganzen Pfad, den ein Browser bräuchte, `piwebapi` eingeschlossen, wo der Dienst dort noch antwortet.	Pfadtext	leer (= `piwebapi`)
Über einfaches HTTP senden	Stuft dieses eine Gerät von HTTPS auf unverschlüsseltes HTTP herunter. Aus bedeutet HTTPS, den üblichen Übertragungsweg der PI Web API. Der Bereich nennt die Folge: Über einfaches HTTP werden Bearer-Token oder Passwort bei jeder Anfrage unverschlüsselt gesendet. Verwenden Sie es nur für eine PI Web API, die auf keinem anderen Weg antwortet.	ein / aus	aus
Benutzername	Konto für die Anmeldung über HTTP Basic, nur verwendet, wenn kein Bearer-Token gesetzt ist. Leer (und ohne Token) lässt die Anfragen anonym.	Freitext	leer
Passwort	Das Passwort zum Benutzernamen. Im Ruhezustand je Windows-Benutzer geschützt; ein unter einem anderen Windows-Konto eingegebenes Geheimnis erscheint als unlesbar und muss neu eingegeben werden.	Freitext	leer
Bearer-Token	Ein Token, das bei jeder Anfrage als `Authorization: Bearer …` gesendet wird. Ist es gesetzt, gewinnt es gegen das Paar aus Benutzername und Passwort. Im Ruhezustand ebenso geschützt.	Text des Tokens	leer

Beim Verbinden prüft der Treiber die Wurzel des Dienstes (HEAD, mit Ausweichen auf GET). Über HTTPS muss das TLS-Zertifikat des Dienstes die übliche Zertifikatsprüfung von Windows bestehen. Das Abfrageintervall ist einstellbar: Der Standard des Geräts (1000 ms) gilt für jeden Tag, der keinen eigenen nennt.

Adressierung der Tags

Das Feld PI-Pfad des Tags nimmt vier Formen an:

Form	Sieht aus wie	Wie sie aufgelöst wird
Pfad eines AF-Attributs	`\\AFServer\Database\Element\SubElement\\|Attribute`	Einmal über `attributes?path=…` nachgeschlagen, um die WebId des Attributs zu erhalten
Pfad eines PI-Punkts	`\\PIServer\TagName`	Einmal über `points?path=…` nachgeschlagen, um die WebId des Punkts zu erhalten
WebId	Die undurchsichtige Zeichenkette der WebId selbst	Unmittelbar verwendet (erkannt als langes Zeichen ohne `\`, `\\|` oder `/`)
Relative URL	`streams/{webId}/value`, `streamsets/…`, `attributes?…`, `points?…`	Unverändert unter der Wurzel des Dienstes gesendet

Nachschlagevorgänge für Pfade werden 12 Stunden zwischengespeichert, das zyklische Lesen im eingeschwungenen Zustand wiederholt sie also nicht. Bei den ersten drei Formen holt der Lesevorgang per GET den Momentanwert des Datenstroms (streams/{webId}/value) und entnimmt das JSON-Feld Value; eine relative URL wird wortgetreu gelesen, richten Sie sie also auf einen Endpunkt, der mit einem Wertdokument antwortet. Das Ergebnis wird in den erklärten Datentyp des Tags gewandelt.

Das eigene Urteil des Archivs über die Stichprobe wird mitgelesen. Ein Wert, den das Archiv als nicht gut, als fraglich oder als ersetzt kennzeichnet (eine von Hand eingetragene statt gemessene Zahl), ist kein Messwert der Anlage und wird deshalb auch nicht als solcher veröffentlicht: Der Tag geht auf schlechte Qualität, und der Grund sagt, welcher der drei Fälle es war. Dasselbe geschieht, wenn die Antwort keinen Wert trägt oder mit einem digitalen Zustand statt eines einzelnen Werts antwortet, wobei dann der Name des Zustands Teil des Grundes ist. An ihrer Stelle wird nichts erfunden, und kein Dokument kommt an, als wäre es die Messung.

Beispiele:

\\PI-SRV01\FURNACE.TEMP: ein klassischer PI-Punkt.
\\AF-SRV\Plant\Line 3\Furnace|Temperature: ein AF-Attribut.
streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value: eine rohe URL eines Datenstroms, nützlich, wenn Sie die WebId schon aus einem anderen Werkzeug haben.

Schreiben

Tags mit einer schreibbaren Zugriffsart schreiben über den Endpunkt für Datenströme der PI Web API: ein POST von {"Timestamp":"*","Value":…} (der Zeitstempel * bedeutet jetzt) an streams/{webId}/value. Der Schreibvorgang braucht eine auflösbare WebId, er funktioniert also für Tags, die über einen AF-Pfad, einen PI-Punktpfad, eine WebId und ebenso über eine relative URL streams/… adressiert sind: Die WebId wird aus dieser URL gelesen, und der Schreibvorgang landet am Wert-Endpunkt dieses Datenstroms, gleich welche Unterressource für das Lesen (etwa recorded) die Adresse dahinter trug. Drei relative Formen werden abgelehnt, weil jede mit einem Dokument statt mit dem Wert eines Datenstroms antwortet und ein Schreibvorgang die falsche Ressource adressieren würde: streamsets/…, attributes?… und points?…. Die Ablehnung nennt die angenommenen Formen. Ob der Schreibvorgang ankommt, hängt außerdem davon ab, dass die PI Web API für Schreibvorgänge eingerichtet ist und das Konto Schreibrecht am Punkt hat.

Der Wert, den Sie in das Schreibfeld des Tags tippen, ist der technische Wert; die Umrechnungsstufen des Tags werden rückwärts durchlaufen, bevor der Rohwert auf den Bus geht, wie auf der Seite Connector beschrieben.

Unterstützte Datentypen

Boolean, Int32, Int64, Float, Double und String. Numerische PI-Punkte sind üblicherweise Float oder Double. Ein digitaler Zustand ist kein einzelner Wert, ein Punkt, der mit einem antwortet, liest also schlechte Qualität und nennt den Zustand, gleich welchen Typ der Tag erklärt.

Befehle

Über das Lesen und Schreiben von Punkten hinaus lässt sich ein Endpunkt der PI Web API bitten, etwas zu tun, und welche Anfragen er annimmt, ist die Sache des Dienstes selbst. Erklären Sie jede am Gerät, auf der Karte Befehle seiner Seite: einen Namen, die relative URL, an die sie unter der Wurzel des Dienstes per POST gesendet wird, und wahlweise den Namen des einen Werts, den sie nimmt und der als Rumpf der Anfrage mitreist. Der Befehl Ausführen in der Zeile sendet sie und meldet, was der Dienst geantwortet hat; der Befehl wird außerdem zu einer Methode am Gerät im eigenen OPC UA-Adressraum dieser Station.

Gerätesuche

Die Schaltfläche Suchen liest einen Dienst. Tragen Sie seine Adresse und das AF-Element, bei dem der Durchlauf beginnt, auf der Karte Umfang des Suchlaufs auf der Seite des Treibers ein, getrennt durch ein #: https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3. Der Suchlauf löst dieses Element auf, durchläuft jedes Element darunter und bietet das Gerät mit einem Punkt je Attribut an, jeder über seinen eigenen Datenstrom adressiert. Der Suchlauf liest den Dienst ohne Anmeldedaten, weil er läuft, bevor es das Gerät gibt, das sie hielte, eine PI Web API, die jede Anfrage anmeldepflichtig macht, antwortet also nichts, und das Gerät wird stattdessen von Hand angelegt: Legen Sie den Dienst über seinen Host an und die Tags über ihre AF- oder PI-Pfade, wie es der Ablauf zum Hinzufügen eines Geräts auf der Seite Connector beschreibt.