REST-Client

Ca. 8 Min. Lesezeit

Beim Protokoll REST-Client ruft 2WinScada Tag-Werte in festgelegten Intervallen selbst von einem externen System mit HTTP-/HTTPS-API ab (Pull) und schreibt bei Bedarf Werte in dasselbe System. Muss das externe System die Daten selbst an 2WinScada senden, verwenden Sie das Protokoll REST-Server.

Funktionsweise im Überblick:

• Die Tags eines Geräts werden nach dem Wert Aktualisierungsintervall [s] gruppiert; für jede Gruppe wird eine einzige HTTP-Anfrage an die Leseadresse gesendet, die alle Tag-Adressen dieser Gruppe enthält.
• In der eingehenden JSON-Antwort werden die Tag-Adressen gesucht, und die gefundenen Werte werden in die Tags geschrieben.
• Wird ein Wert auf ein Tag geschrieben, wird eine Anfrage mit JSON-Body an die Schreibadresse gesendet.
• Der Timeout für Lese- und Schreibanfragen beträgt 30 Sekunden; eine Leseantwort darf höchstens 4 MB groß sein.

Lizenz

REST-Client ist in den Lizenz-Editionen Standard und Professional verfügbar, in der Edition Starter nicht. Einzelheiten finden Sie auf der Seite Lizenz.

Kanaldefinition

Auf der Registerkarte Allgemein des Fensters für einen neuen Kanal geben Sie im Feld Name den Namen ein und wählen unter Verbindungstyp den Eintrag RestClient aus.

Registerkarte Verbindungsparameter:

Feld	Beschreibung	Standard	Bereich
HTTP-Client gemeinsam nutzen	Wenn aktiviert, werden die aktiven Geräte des Kanals nicht gleichzeitig, sondern nacheinander abgefragt; das nächste Gerät sendet erst eine Anfrage, wenn die Leserunde eines Geräts beendet ist. Verwenden Sie die Option, wenn das externe System keine gleichzeitigen Anfragen verkraftet.	Nicht aktiviert	–
JSON-Tiefenebene	Legt fest, wie tief verschachtelte Objekte in der Antwort durchsucht werden, wenn im Gerät Schlüsselnamen als Tag-Adresse verwenden gewählt ist.	2	1–15

Gerätedefinition

Auf der Registerkarte Allgemein werden die Felder Name und Aktiv wie bei den anderen Protokollen ausgefüllt. Ein REST-Client-Gerät hat zusätzlich die Registerkarten Parameter, Lesen und Schreiben.

Registerkarte Parameter

Die Tabelle Header-Parameter definiert HTTP-Header, die allen Lese- und Schreibanfragen hinzugefügt werden. Mit der Schaltfläche + oben rechts in der Tabelle wird eine neue Zeile hinzugefügt; in die erste Spalte wird der Header-Name, in die zweite der Wert eingetragen.

Bei APIs, die eine Authentifizierung erfordern, werden die nötigen Angaben in dieser Tabelle als Header eingetragen. Beispiele:

Header-Name	Wert
Authorization	Bearer <Zugriffstoken>
Authorization	Basic <Base64-Darstellung des Texts Benutzer:Passwort>
X-Api-Key	<API-Schlüssel> (der Header-Name wird so eingegeben, wie er in der API-Dokumentation steht)

Wird ein gespeichertes Gerät geöffnet, erscheint der Wert von Headern, deren Name auf Anmeldedaten hinweist (Authorization, API-Schlüssel, Token, Cookie usw.), als ********. Speichern ohne Änderung erhält den Wert, ein neuer Wert ändert ihn, das Löschen des Headers löscht den Wert. Bei einem Gerät, das im Raster durch Kopieren/Einfügen entsteht, werden diese Werte nicht kopiert; sie müssen neu eingegeben werden.

WARNING

Bei Anfragen mit Body wird Content-Type: application/json automatisch gesendet; Sie müssen diesen Header nicht in die Tabelle eintragen. In die Tabelle eingetragene Inhalts-Header (die mit Content- beginnen) werden auf den Body der Anfrage angewendet. Ein ungültiger oder widersprüchlicher Header wird übersprungen, und eine Warnung wird in das Dienstprotokoll geschrieben; die anderen Lese- und Schreibvorgänge des Geräts sind nicht betroffen.

Registerkarte Lesen

In der Gruppe Leseanfrage werden die Adresse für das Lesen und das Format der Anfrage festgelegt.

Feld	Beschreibung	Optionen
URL	API-Adresse, von der gelesen wird. In die Adresse geschriebene feste Abfrageparameter (nach ?) bleiben erhalten.	–
Anforderungsmethode	HTTP-Methode der Leseanfrage.	GET (Standard), PUT, POST
Parametertyp	Wie die Tag-Adressen der Anfrage hinzugefügt werden.	None, Query (Standard), Body

Optionen für Parametertyp:

• None: Der Anfrage wird keine Tag-Adresse hinzugefügt; wird verwendet, wenn die API alle Werte ohne Parameter zurückgibt.
• Query: Jede Tag-Adresse der Gruppe wird als Abfrageparameter mit dem Schlüsselnamen hinzugefügt, der in der Tabelle Leseanfrage-Parameter in der Zeile TagAddress steht. Da die Adresslänge an Grenzen von Server und Proxy stoßen kann, ist bei vielen Tags Body vorzuziehen.
• Body: Die Tag-Adressen werden im JSON-Body als Array gesendet.

Im unteren Teil der Registerkarte befinden sich die Registerkarten Leseanfrage, Antwortschema und Werteschema.

Registerkarte Leseanfrage: Die Tabelle Leseanfrage-Parameter definiert die Parameter, die der Leseanfrage hinzugefügt werden. In der ersten Spalte wird der Parameter aus der Liste gewählt, in die zweite Spalte der Wert eingetragen.

• TagAddress: Gibt an, unter welchem Schlüsselnamen die Tag-Adressen gesendet werden. Sollen Adressen gesendet werden, muss diese Zeile definiert sein.
• Period, SampleTime, ValueType, FillType, FillValue, StartTime, EndTime, AlignToCalendar, CalculateConsumption, IANATimeZone, PeriodCount: Diese Zeilen werden der Anfrage mit dem Namen aus der Liste und dem Wert aus der zweiten Spalte als zusätzliche Parameter hinzugefügt. Definieren Sie sie, wenn die verwendete API diese Parameter erwartet.

Zum Beispiel entstehen bei einem Gerät mit dem Wert ids für TagAddress für zwei Tags mit den Adressen Kazan.Sicaklik und Kazan.Basinc diese Anfragen.

Bei Parametertyp Query:

GET https://<api-server>/read?ids=Kazan.Sicaklik&ids=Kazan.Basinc

Bei Parametertyp Body der Body der Anfrage:

{ "ids": ["Kazan.Sicaklik", "Kazan.Basinc"] }

Registerkarte Antwortschema: Die Tabelle Antwortparameter legt fest, wo in der Antwort die Werte stehen. Höchstens zwei Zeilen können hinzugefügt werden.

• Values: Name des Felds auf der obersten Ebene der Antwort, das die Werteliste enthält (z. B. readResults). Fehlt diese Zeile oder wird das Feld in der Antwort nicht gefunden, wird die Wurzel der Antwort verwendet.
• TimeStamp: Wird in dieser Version nicht verwendet.

Registerkarte Werteschema: Legt fest, wie jedes Element der Werteliste gelesen wird.

Die Option Schlüsselnamen als Tag-Adresse verwenden wird aktiviert, wenn in der Antwort die Tag-Adresse als Feldname und der Tag-Wert als Wert dieses Felds kommt (z. B. { "Kazan.Sicaklik": 81.5 }). In diesem Fall wird die Tabelle Antwortwertschema nicht verwendet; verschachtelte Objekte werden nach der Einstellung JSON-Tiefenebene des Kanals durchsucht. Derselbe Feldname darf in der Antwort nicht mehrfach vorkommen; das zuverlässigste Ergebnis erhalten Sie, wenn die Werte in der Antwort auf einer einzigen Ebene liegen.

Ist die Option nicht aktiviert, wird als Werteliste ein Array erwartet, und die Tabelle Antwortwertschema wird ausgefüllt:

Zeile	Beschreibung
TagAddress	Name des Felds im Array-Element, das die Tag-Adresse enthält. Pflichtangabe.
TagValue	Name des Felds im Array-Element, das den Wert enthält. Pflichtangabe.
TagChangeTime	Wird in dieser Version nicht verwendet; als Zeitpunkt des Werts wird der Lesezeitpunkt gespeichert.
TagQuality	Wird in dieser Version nicht verwendet.

Sind die Array-Elemente keine Objekte, sondern Arrays (z. B. ["Kazan.Sicaklik", 81.5]), wird anstelle des Feldnamens die Position des Elements (ab 0) eingetragen.

Beispiel für eine Antwort, die zum obigen Schema passt (Values = readResults, TagAddress = id, TagValue = v):

{
  "readResults": [
    { "id": "Channel1.Device1.tag1", "s": true, "r": "", "v": 263, "t": 1442606724647 }
  ]
}

Mit dieser Antwort wird der Wert 263 in das Tag mit der Adresse Channel1.Device1.tag1 geschrieben.

Registerkarte Schreiben

Unterstützt das externe System Schreibvorgänge, wird die Gruppe Schreibanfrage ausgefüllt. Bleibt URL leer, wird nicht auf die Tags geschrieben.

Feld	Beschreibung	Optionen
URL	API-Adresse, an die geschrieben wird.	–
Anforderungsmethode	HTTP-Methode der Schreibanfrage.	PUT, POST (Standard)
Parametertyp	Steht in der Liste, aber die Schreibanfrage wird in jedem Fall mit JSON-Body gesendet.	None (Standard), Body

In der Tabelle Schreibanfrage-Parameter können keine Zeilen hinzugefügt oder gelöscht werden; nur die Werte lassen sich ändern:

• TagAddress: Name des Felds, in dem die Tag-Adresse gesendet wird. Pflichtangabe.
• TagValue: Name des Felds, in dem der zu schreibende Wert gesendet wird. Pflichtangabe.

Bei TagAddress = id und TagValue = v wird beim Schreiben von 42 auf das Tag Channel1.Device1.tag1 dieser Body gesendet:

[{ "id": "Channel1.Device1.tag1", "v": 42 }]

Bool-Tags werden als 0 oder 1 gesendet. Jeder Schreibvorgang wird mit einer einzigen Anfrage einmal gesendet; ein fehlgeschlagener Schreibvorgang wird nicht wiederholt; der HTTP-Fehlercode erscheint auf dem Bildschirm Gerätezustände im Feld Fehler.

Tag-Definition

Wählen Sie im Kanalbaum das Gerät aus und fügen Sie in der Tag-Tabelle rechts ein neues Tag hinzu. Die allgemeinen Felder werden wie auf der Seite Tag-Verwaltung ausgefüllt. Für REST-Client wichtige Felder:

Feld	Beschreibung
Adresse	Kennung, unter der das externe System das Tag kennt (1–250 Zeichen). Dieser Wert wird in der Leseanfrage gesendet und mit dem Adressfeld in der Antwort exakt und unter Beachtung der Groß- und Kleinschreibung abgeglichen. Im obigen Beispiel muss die Adresse Channel1.Device1.tag1 lauten.
Datentyp	Es wird ein zum gelesenen Wert passender Typ gewählt; kann der Wert nicht in diesen Typ umgewandelt werden, wird das Tag nicht aktualisiert.
Aktualisierungsintervall [s]	Leseintervall. Tags mit demselben Intervall werden in einer Anfrage gelesen.

Fehlerbehebung

Symptom	Prüfungen
Gerät und alle Tags der Gruppe Bad	Prüfen Sie, ob die API einen anderen HTTP-Code als 2xx zurückgibt, den Wert URL, den Netzwerk- und Firewall-Zugriff, das Zertifikat und die Authentifizierungs-Header. Die Antwort muss innerhalb von 30 Sekunden eintreffen, gültiges JSON sein und darf 4 MB nicht überschreiten.
Es wird gar nicht gelesen	Prüfen Sie, ob der Wert URL ausgefüllt und gültig ist und ob das Dienstprotokoll eine Warnung zu einem übersprungenen Header enthält. Ist HTTP-Client gemeinsam nutzen aktiviert, kann ein langsames Gerät im selben Kanal die anderen warten lassen.
Tag-Qualität Uncertain	Die Tag-Adresse wurde in der Antwort nicht gefunden. Prüfen Sie, ob der Wert Adresse einschließlich Groß- und Kleinschreibung mit der Antwort übereinstimmt, sowie die Feldnamen Values und TagAddress.
Tag-Wert wird nicht aktualisiert	Prüfen Sie den Feldnamen TagValue und die Auswahl Datentyp.
Schreiben funktioniert nicht	Prüfen Sie den Wert URL auf der Registerkarte Schreiben, die Auswahl Anforderungsmethode, die Feldnamen TagAddress / TagValue und die letzte Fehlermeldung im Gerätezustand.