HTTP

Referenz zum Treiber HTTP: Endpunkte über HTTP und HTTPS als Tags zyklisch lesen, Anmeldedaten, Zuordnung der Pfade, Auswertung des Rumpfes, Schreibvorgänge per PUT und Typen.

Als Markdown ansehen

Der Treiber HTTP liest beliebige HTTP-Endpunkte zyklisch als Tags: einen Sensor im LAN mit einem winzigen Webserver, ein Gateway, das Messwerte unter festen URLs veröffentlicht, einen eigenen Dienst. Er ist der einfachste Treiber im Client-Betrieb im Produkt: Ganter Lab verbindet sich mit der Anlage über einfache GET-Anfragen und liest jeden Rumpf der Antwort als einen Wert.

Zwei Eigenschaften ziehen die Grenze um das, wofür er gedacht ist:

Der Übertragungsweg ist der, den die Adresse nennt. Ein Gerät, dessen Host als https://host geschrieben ist, erreicht seinen Dienst über TLS; ein Host für sich allein ist einfaches HTTP. So oder so sendet der Treiber die Anmeldedaten des Geräts bei jeder Anfrage, also Benutzername und Passwort als HTTP Basic oder ein Bearer-Token. Was die Treiber AVEVA PI und Redfish für diese beiden Dienste darüber hinaus mitbringen, ist deren Wortschatz: PI-Pfade und WebIds, Ressourcenbäume von Redfish, von denen dieser Treiber nichts weiß.
Der ganze Rumpf der Antwort ist der Wert. Der Treiber ist kein Auszug einzelner JSON-Felder: Ein numerischer Tag erwartet, dass der Rumpf die nackte Zahl ist.

Verbindungsfelder

Feld	Was es ist	Format	Standard
Host	Hostname oder IP-Adresse des Endpunkts. Als `https://host` geschrieben, wird er über TLS erreicht, und genau das hält Anmeldedaten von der Leitung fern; ein Host für sich allein ist einfaches HTTP.	Hostname, IP oder beides mit `http://` oder `https://` davor	leer
Port	Der TCP-Port. Null bedeutet den Port, auf dem der Übertragungsweg antwortet: 80 einfach, 443 über HTTPS.	Portnummer	0
Ressourcenpfad	Ein wahlweiser Pfad, der jedem Pfad eines Tags vorangestellt wird, z. B. `api/v2`. Leer stellt nichts voran.	Pfadtext	leer
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 den Endpunkt mit einer HEAD-Anfrage an die eingestellte Adresse, also Host und Ressourcenpfad, und weicht auf GET aus, wenn HEAD nicht umgesetzt ist; eine Adresse, die eines von beiden erfolgreich beantwortet, gilt als erreichbar. Ein Dienst, dessen Wurzel mit 404 antwortet, während seine API normal antwortet, ist daher online, solange der Ressourcenpfad auf die API zeigt. Über HTTPS muss das TLS-Zertifikat des Dienstes die übliche Zertifikatsprüfung von Windows bestehen. Anmeldedaten auf einer Adresse, die kein TLS nennt, gehen unverschlüsselt hinaus, und die Station schreibt das beim Verbinden in das Journal des Connectors. Jeder Anfrage werden zehn Sekunden gegeben: Ein Endpunkt, der die Verbindung annimmt und dann schweigt, kostet einen Messwert, nicht das ganze Gerät, weil die übrigen Tags des Geräts im selben Durchgang gelesen werden. 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 Pfad des Tags ist der Pfad der URL relativ zum Ressourcenpfad des Geräts:

Feld	Wirkung	Werte	Standard
Pfad	Der Pfad, der für diesen Tag angefragt wird. Die vollständige URL ist `<transport>://<host>:<port>/<resource path>/<path>`.	Freitext (Pflichtfeld)	leer

Beispiel: Host 192.168.0.40, Ressourcenpfad api, Pfad des Tags sensors/temp liest zyklisch http://192.168.0.40/api/sensors/temp.

Lesevorgänge

Jeder Takt holt die URL des Tags per GET und wertet den ganzen Rumpf der Antwort nach dem erklärten Datentyp des Tags aus:

Typ	Angenommener Rumpf
Float	Eine Zahl im invarianten Format (`21.5`, Dezimalpunkt, keine Tausendertrennzeichen)
Int32	Eine Ganzzahl (`42`)
Boolean	`true` oder `false`
String	Alles; der Rumpf ist wortgetreu der Wert (ein JSON-Dokument kommt als sein roher Text an)

Ein Rumpf, den der erklärte Typ nicht auswerten kann, und ein Statuscode außerhalb des Erfolgs lesen als fehlgeschlagener Lesevorgang: Der Tag geht auf schlechte Qualität, und seine Regel für Lesefehler entscheidet, was dargestellt wird, wie auf der Seite Connector beschrieben.

Schreiben

Tags mit einer schreibbaren Zugriffsart schreiben per PUT an dieselbe URL: Der Rumpf ist der Wert als JSON, gesendet mit dem Inhaltstyp application/json. Eine Zahl geht als nacktes Literal (42.5), ein Wahrheitswert als true oder false, und Text geht in Anführungszeichen ("automatic"). Der Endpunkt entscheidet, was er daraus macht; ein Status außerhalb des Erfolgs liest als fehlgeschlagener Schreibvorgang. Wie überall sonst nimmt das Schreibfeld den technischen Wert, und 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, Float und String.

Befehle

Ein Tag liest einen Wert; ein Befehl bittet den Dienst, etwas zu tun. Erklären Sie jeden am Gerät, auf der Karte Befehle seiner Seite: einen Namen, den Pfad, an den er per POST gesendet wird (unter der eigenen Adresse des Geräts, genau wie der Pfad eines Tags), und wahlweise den Namen des einen Werts, den er nimmt. Der Befehl Ausführen in der Zeile sendet ihn und meldet, was der Dienst geantwortet hat, und der Befehl wird außerdem zu einer Methode am Gerät im eigenen OPC UA-Adressraum dieser Station, alles, was eine Methode aufrufen kann, kann ihn also erteilen. Der Wert, den Sie eintippen, wird als Rumpf der Anfrage gesendet, so wie er geschrieben steht.

Was der Dienst antwortet, ist das Ergebnis des Befehls. Ein Status, den der Dienst außerhalb des Erfolgsbereichs zurückgibt, ist der Dienst, der den Befehl ablehnt, nicht die Verbindung, die fehlschlägt: Die Ablehnung nennt den Status und zitiert, was der Dienst dazu gesagt hat ("HTTP 500: the burner is locked out"), und sonst wird nichts am Gerät gestört.

Gerätesuche

Der Treiber hat keinen Suchlauf. Legen Sie jeden Endpunkt über seinen Host an und jeden Wert über seinen Pfad; der Ablauf zum Hinzufügen eines Geräts steht auf der Seite Connector.