# 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.

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 **die Wahl des Geräts selbst**. Ein Gerät erreicht seinen Dienst
  über TLS, bis sein Haken **Über einfaches HTTP senden** etwas anderes sagt, und ein Host,
  vor dem `http://` oder `https://` steht, verschiebt diesen Haken und wird als reiner Host
  gespeichert, sodass die beiden einander nie widersprechen können. 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](driver-aveva-pi) und [Redfish](driver-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 numerisches Tag erwartet, dass der Rumpf die nackte Zahl ist.

## Verbindungsfelder {#connection-fields}

| Feld | Was es ist | Format | Standard |
|---|---|---|---|
| Host | Hostname oder IP-Adresse des Endpunkts. Ein Host, vor dem `http://` oder `https://` steht, verschiebt den Haken für den Übertragungsweg weiter unten entsprechend und wird ohne ihn gespeichert. Ein Port hinter dem Host (`:8080`) geht in das Feld Port und ein Pfad dahinter (`/api`) in den Ressourcenpfad, sodass sich hier eine ganze Adresse wie `http://192.168.0.5:8080/api` einfügen lässt. Eine IPv6-Adresse behält ihre eckigen Klammern. | Hostname, IP oder beides mit `http://` oder `https://` davor | leer |
| Port | Der TCP-Port. Ein neues Gerät lässt ihn leer, und ein leeres Feld bedeutet den Port, auf dem der gewählte Übertragungsweg antwortet, 443 über HTTPS und 80 im Klartext: Das Feld zeigt diesen Port grau und folgt der Wahl des Übertragungswegs; ein mit 0 gespeichertes Gerät liest sich genauso. | 1 bis 65535 oder leer | leer |
| Ressourcenpfad | Ein wahlweiser Pfad, der **jedem** Pfad eines Tags vorangestellt wird, z. B. `api/v2`. Leer stellt nichts voran. | Pfadtext | leer |
| Über einfaches HTTP senden | Stuft dieses eine Gerät von HTTPS auf unverschlüsseltes HTTP herunter. Aus bedeutet HTTPS, und genau das hält Anmeldedaten von der Leitung fern. Der Bereich nennt die Folge: Über einfaches HTTP gehen die Anfragen, und alle Anmeldedaten des Geräts mit ihnen, unverschlüsselt hinaus. Verwenden Sie es für einen Endpunkt, der 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 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 wird das TLS-Zertifikat des
Dienstes angenommen, wenn Windows ihm vertraut oder wenn Sie genau dieses Zertifikat unter
[Anlagenzugriff](#equipment-access) auf der Seite dieses Treibers freigegeben haben. Anmeldedaten auf einem Gerät,
das auf einfaches HTTP heruntergestuft ist, 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 jedes Tag,
das keinen eigenen nennt.

## Adressierung der Tags {#tag-addressing}

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 dieses Tag angefragt wird. Die vollständige URL ist `<transport>://<host>:<port>/<resource path>/<path>`. | Freitext (Pflichtfeld) | leer |

Beispiel: Host `192.168.0.40`, auf einfaches HTTP heruntergestuft, Ressourcenpfad `api`,
Pfad des Tags `sensors/temp` liest zyklisch `http://192.168.0.40/api/sensors/temp`.

## Lesevorgänge {#reads}

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: Das Tag geht auf schlechte Qualität, und
seine Regel für Lesefehler entscheidet, was dargestellt wird, wie auf der Seite
[Connector](connector) beschrieben. Ein Status außerhalb des Erfolgs ist der Endpunkt, der
den Lesevorgang ablehnt, und der Grund des Tags nennt den Status und zitiert, was der Endpunkt
dazu gesagt hat (`HTTP 404 Not Found: …`), in denselben Worten wie bei einem abgelehnten
Schreibvorgang oder Befehl. Ein Rumpf, den der erklärte Typ nicht lesen kann, gibt dem Tag einen
Grund, der zitiert, was sich nicht lesen ließ, und das Gerät bleibt verbunden. Ein Endpunkt, der
gar nicht antwortet, ist die Verbindung des Geräts, die ausfällt: Das Gerät meldet es und verbindet
sich neu, und seine Tags verweisen auf das Gerät. Die rote Zeile des Tags sagt einen solchen Status in der Sprache der Station, bei 401, 403 und 404 mit seiner Bedeutung, und einen Inhalt, der sich nicht auswerten lässt, als Antwort, die sich nicht als Wert vom Typ des Tags lesen lässt; die Seite Ereignisse behält die eigenen Worte des Endpoints.

## Schreiben {#writes}

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 ist der Endpunkt, der den Wert ablehnt: Die Ablehnung nennt den Status und zitiert, was der Endpunkt dazu gesagt hat, in denselben Worten wie bei einem abgelehnten Befehl, und wer den Wert geschrieben hat, liest den Grund. 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](connector)
beschrieben.

## Unterstützte Datentypen {#supported-data-types}

Boolean, Int32, Float und String.

## Befehle {#commands}

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 Internal Server Error: the burner is locked out"), und sonst wird nichts am Gerät gestört.

## Gerätesuche {#discovery}

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](connector).

## Anlagenzugriff {#equipment-access}

Ein HTTPS-endpoint mit einem selbstsignierten Zertifikat oder einem, das eine eigene Stelle ausgestellt hat, legt ein Zertifikat vor, für das keine in Windows installierte Wurzel bürgt. Diese Wurzel muss auf diesem Rechner nicht installiert werden. Die erste Verbindung wird abgewiesen, das Gerät zeigt im Baum und auf seiner Seite
**Wartet auf Freigabe des Zertifikats**, deren Schaltfläche **Zertifikat prüfen** diese Karte
auf dem Zertifikat öffnet, und das Zertifikat wartet unter **Anlagenzugriff** am Ende der
Seite des HTTP-Treibers, derselben Karte wie auf der Seite des OPC UA-Treibers, bis Sie
entscheiden:

| Gruppe | Was sie zeigt | Was Sie tun können |
|---|---|---|
| Wartet auf Freigabe | Jedes abgewiesene Zertifikat unter dem Namen, den es behauptet: sein SHA-256-Fingerabdruck, die Adresse, unter der es angetroffen wurde, wann es zuletzt versucht wurde und wie oft, und seine Details (Antragsteller, Aussteller, Domänennamen, Gültigkeitsdaten). Das Zertifikat, das **Zertifikat prüfen** eines Geräts geöffnet hat, ist als Zur Prüfung ausgewählt markiert. | **Freigeben** nimmt das Zertifikat ab dem nächsten Verbindungsversuch an. **Sperren** weist es weiter ab, ohne es hier erneut aufzuführen. **Alle ausstehenden Zertifikate verwerfen** leert die Liste, ohne etwas freizugeben oder zu sperren. |
| Freigegebene Anlagen | Die Zertifikate, die Sie freigegeben oder importiert haben, mit der Angabe, wer wann entschieden hat, und der Adresse, unter der jedes zuletzt angetroffen wurde. | **Freigabe zurücknehmen** schließt die Verbindung und bringt das Zertifikat in die Liste zurück. **Zertifikat importieren** gibt eine öffentliche Zertifikatsdatei, die Sie bereits haben (.der, .cer, .crt oder .pem), vor der ersten Verbindung frei. |
| Gesperrte Anlagen | Die Zertifikate, die Sie gesperrt haben. Ein gesperrtes Zertifikat wird abgewiesen, auch wenn Windows ihm vertraut. | **Entsperren** bringt das Zertifikat in die Liste zurück, ohne es freizugeben. |

Prüfen Sie den Fingerabdruck mit derjenigen Person, die die Anlage betreut, bevor Sie das Zertifikat freigeben.
Eine Freigabe nimmt genau dieses Zertifikat an und kein anderes, und nur innerhalb seiner
Gültigkeitsdaten; sie steht für die Wurzel ein, die Windows fehlt, und für den Namen, den das
Zertifikat trägt, sodass sich ein endpoint, der über seine IP-Adresse angewählt wird, verbindet, obwohl sein Zertifikat einen anderen Namen trägt,
und sonst wird am Zertifikat nichts gelockert. Antwortet die Anlage an einer Adresse, deren
Zertifikat Sie freigegeben haben, mit einem anderen (ein erneuertes Zertifikat), hört das Lesen auf, das neue wartet
hier, und die Station meldet "Zertifikat geändert: `<Name>`" mit einer Schaltfläche
**Prüfen**. Ein Zertifikat, dem Windows bereits vertraut, wird wie bisher angenommen und
erscheint hier nie; nichts wird automatisch freigegeben.

Der eigene Fehlschlag des Treibers nennt den Grund statt eines namenlosen TLS-Fehlers: "Das
Zertifikat dieser Anlage (die ersten 16 Zeichen des Fingerabdrucks) wartet unter
Anlagenzugriff auf der Seite des HTTP-Treibers auf Ihre Freigabe. Das Lesen beginnt, sobald Sie
es freigeben." Ein gesperrtes liest "…ist an dieser Station gesperrt. Prüfen Sie es unter
Anlagenzugriff auf der Seite des HTTP-Treibers." Ein Zertifikat außerhalb seiner
Gültigkeitsdaten, widerrufen oder mit gebrochener Signatur wird mit diesem Grund abgewiesen
und nie aufgeführt, weil keine Freigabe es einwandfrei macht.

Die Entscheidungen liegen im Datenordner der Station unter `ua\pki\http` und überstehen
einen Neustart. Die Befehle werden nur einer Rolle gezeichnet, die den Connector
konfigurieren darf, und sie wirken nur im eigenen Fenster der Station: Ein Browser auf einem
anderen Gerät liest die Karte, ohne sie zu ändern, und kein Werkzeug eines Agenten gibt ein
Zertifikat frei (`connector_browse` meldet das wartende Gerät mit `awaitingCertificate`).
Die Liste hält bis zu 100 Zertifikate, die auf Freigabe warten; ist sie voll, wird ein neues
weiter abgewiesen, aber nicht aufgeführt, und die Karte sagt das.