REST-Server

Ca. 10 Min. Lesezeit

Das Protokoll REST-Server ermöglicht es IoT-Geräten, Cloud-Diensten und anderer Software, Tag-Werte per HTTP-POST-Anfrage selbst an 2WinScada zu senden (Push). Anders als beim Protokoll REST-Client fragt 2WinScada das externe System nicht ab; das externe System übermittelt die Daten in einem beliebigen Intervall an den Ingest-Endpunkt von 2WinScada.

Jedes REST-Server-Gerät steht für eine eigene Datenquelle. Das externe System sendet bei jeder Anfrage die Gerätekennung und den für dieses Gerät erzeugten Geräteschlüssel im HTTP-Header; ist die Identität bestätigt, werden die Werte im Body in die Tags des Geräts geschrieben.

Lizenz

REST-Server ist in den Lizenz-Editionen Standard und Professional verfügbar, in der Edition Starter nicht. Enthält die Lizenz die REST-Integration nicht, lehnt der Ingest-Endpunkt Anfragen mit dem Fehlercode 4900 ab. 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 RestServer aus.

Ein REST-Server-Kanal hat nur die Registerkarte Allgemein; der Kanal hat keine Verbindungsparameter. Der Kanal verbindet sich nicht mit dem externen System, sondern nimmt die Anfragen an, die am Ingest-Endpunkt eintreffen. Authentifizierung und Body-Einstellungen werden auf der Registerkarte Parameter des jeweiligen Geräts vorgenommen.

Gerätedefinition

Auf der Registerkarte Allgemein werden die Felder Name und Aktiv wie bei den anderen Protokollen ausgefüllt. Damit Daten angenommen werden, muss das Gerät Aktiv sein.

Die Registerkarte Parameter enthält die Gruppe REST-Server-Ingest:

• REST-Server-Ingest aktiviert: Schaltet den Datenempfang des Geräts ein (Standard: aktiviert). Ist die Option nicht aktiviert, werden Anfragen an dieses Gerät mit dem Fehlercode 4603 abgelehnt.

Unter der Gruppe befinden sich die Registerkarten Identität und Schlüssel, Nutzlastanalyse und No-Data-Watchdog.

Identität und Schlüssel

Feld	Beschreibung
Externe Geräte-ID	Kennung, die das externe System im Header X-Device-Id sendet, um dieses Gerät zu bezeichnen (z. B. kazan-dairesi-01). Der Abgleich unterscheidet nicht zwischen Groß- und Kleinschreibung. Es wird empfohlen, für jedes Gerät eine schwer zu erratende Externe Geräte-ID einzugeben. Bleibt das Feld leer, muss im Header X-Device-Id die numerische Kennung des Geräts im System stehen.
Geräteschlüssel	Geheimer Schlüssel, den das externe System im Header X-Device-Key sendet. Das Feld wird maskiert angezeigt; zum Weitergeben des Schlüssels wird, wie im Hilfetext darunter angegeben, die Schaltfläche zum Kopieren verwendet. Ist der Schlüssel leer, wird für dieses Gerät keine Anfrage angenommen.
Schlüssel generieren	Holt einen neuen Zufallsschlüssel vom Server und schreibt ihn in das Feld Geräteschlüssel. Ist bei einem gespeicherten Gerät Externe Geräte-ID leer, wird in dieses Feld auch die numerische Kennung des Geräts geschrieben.
Schlüssel kopieren	Kopiert den Schlüssel in die Zwischenablage, ohne ihn anzuzeigen.

Schlüssel erzeugen und erneuern:

1. Klicken Sie auf Schlüssel generieren. Der erzeugte Schlüssel beginnt mit dev_.
2. Kopieren Sie den Schlüssel mit Schlüssel kopieren und übertragen Sie ihn auf sicherem Weg in die Konfiguration des externen Systems.
3. Speichern Sie das Geräteformular mit Speichern. Der neue Schlüssel gilt nach dem Speichern; Anfragen mit dem vorherigen Schlüssel werden ab diesem Zeitpunkt mit dem Fehlercode 4600 abgelehnt.

WARNING

Geben Sie den Geräteschlüssel nicht über offene Kanäle wie E-Mail, Screenshots oder Abfrageparameter weiter; der Schlüssel erlaubt dem sendenden System, Daten in dieses Gerät zu schreiben. Damit der Schlüssel im Netzwerk nicht im Klartext übertragen wird, greifen Sie per HTTPS auf den Ingest-Endpunkt zu. Wird ein Gerät kopiert, werden auch Externe Geräte-ID und Geräteschlüssel kopiert; erzeugen Sie in der Kopie einen neuen Schlüssel und ändern Sie die Kennung.

Nutzlastanalyse

Diese Registerkarte legt fest, wie frei strukturiertes JSON im Body in Tag-Werte umgesetzt wird. Beispiele für die Body-Formate finden Sie im Abschnitt Daten senden.

Feld	Beschreibung	Standard
Listen-JSON-Pfad	Durch Punkte getrennter Pfad des Felds im Body, das die Tag-Liste oder das Tag-Objekt enthält (z. B. data.items). Der erste Teil des Pfads muss ein Feld auf der obersten Ebene des Body sein; die Wurzel selbst kann nicht angegeben werden. Pflichtfeld, wenn der Datenempfang aktiviert ist.	Leer
Tag-Adressschlüssel	Name des Felds im Listenelement, das die Tag-Adresse enthält. Pflichtfeld, wenn Tag-Adresse in Objektschlüsseln nicht aktiviert ist.	sourceKey
Tag-Wertschlüssel	Name des Felds im Listenelement, das den Wert enthält. Pflichtfeld.	value
Tag-Zeitstempelschlüssel	Name des Felds im Listenelement, das den Zeitstempel enthält. Optional.	ts
Dezimaltrennzeichen	Dezimaltrennzeichen in Werten, die für numerische Tags als Text eintreffen: Punkt (.) oder Komma (,).	Punkt (.)
Tag-Adresse in Objektschlüsseln	Wenn aktiviert, gelten die Feldnamen des über Listen-JSON-Pfad angegebenen Objekts als Tag-Adressen und die Feldwerte als Tag-Werte.	Nicht aktiviert

Feldnamen werden ohne Unterscheidung von Groß- und Kleinschreibung abgeglichen.

TIP

Auch wenn Sie nur das Body-Format Metrics oder Tags verwenden, muss Listen-JSON-Pfad ausgefüllt werden; Sie können einen Namen eingeben, der in Ihrem Body nicht vorkommt (z. B. items).

No-Data-Watchdog

Setzt die Qualität des Geräts und der Tags herab, wenn vom externen System eine bestimmte Zeit lang keine Daten eintreffen.

Feld	Beschreibung	Standard	Bereich
No-Data-Watchdog aktiviert	Schaltet den Watchdog ein. Ist er aus, bleibt die Gerätequalität Good, auch wenn keine Daten eintreffen.	Nicht aktiviert	–
Zeitüberschreitung bei fehlenden Daten [s]	So viele Sekunden nach den zuletzt angenommenen Daten wird die Qualität herabgesetzt. Sind seit dem Start des Dienstes noch keine Daten eingetroffen, wird die Qualität sofort herabgesetzt.	30	1–86400
No-Data-Qualität	Qualität, die dem Gerät und den Tags bei Zeitüberschreitung zugewiesen wird: Bad oder Uncertain.	Uncertain	–
Qualität bei eingehenden Daten auf Good setzen	Wenn aktiviert, wird nach jeder angenommenen Anfrage die Qualität des Geräts und aller seiner Tags Good. Wenn nicht aktiviert, werden nur die Tags Good, für die ein Wert eintrifft; die Gerätequalität bleibt herabgesetzt.	Aktiviert	–

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.

Jeder eingehende Wert wird nur unter den Tags des authentifizierten Geräts in dieser Reihenfolge zugeordnet:

1. Ist im Body TargetTagId angegeben, das Tag mit dieser numerischen Kennung.
2. Das Tag, dessen Feld Adresse mit der eingehenden Adresse (z. B. dem Wert sourceKey oder dem Feldnamen in Metrics) übereinstimmt.
3. Wird keines gefunden, das Tag, dessen Name mit der eingehenden Adresse übereinstimmt.

Der Vergleich von Adresse und Name unterscheidet nicht zwischen Groß- und Kleinschreibung; Leerzeichen am Anfang und Ende werden ignoriert. Nicht zuordenbare Werte werden abgelehnt und in die Liste Errors der Antwort geschrieben.

Datentyp muss passend zum eingehenden Wert gewählt werden; ein nicht umwandelbarer Wert wird abgelehnt. Das Feld Aktualisierungsintervall [s] wird beim REST-Server nicht verwendet; das Tag wird aktualisiert, sobald die Anfrage eintrifft.

Daten senden

Anfrage

Eigenschaft	Wert
Adresse	https://<server>/api/RestIngest/Telemetry
Methode	POST
Header Content-Type	application/json
Header X-Device-Id	Externe Geräte-ID oder die numerische Kennung des Geräts
Header X-Device-Key	Geräteschlüssel

<server> ist die Adresse der 2WinScada-Weboberfläche; der Endpunkt wird über dieselbe HTTPS-Adresse wie die Weboberfläche bereitgestellt. Wird die Weboberfläche an einem anderen als dem Standardport bereitgestellt, geben Sie auch den Port an (https://<server>:<port>). Der Endpunkt verlangt weder eine Benutzersitzung noch einen API-Schlüssel; die Authentifizierung erfolgt ausschließlich über den Geräteschlüssel.

Beispielanfrage:

POST /api/RestIngest/Telemetry HTTP/1.1
Host: <server>
Content-Type: application/json
X-Device-Id: kazan-dairesi-01
X-Device-Key: <geraeteschluessel>

{
  "MessageId": "kazan-0001",
  "DeviceTime": "2026-10-15T08:30:00Z",
  "Metrics": {
    "Kazan1_Run": 1,
    "Kazan1_Temp": 45.2
  }
}

Dieselbe Anfrage mit curl:

curl -X POST "https://<server>/api/RestIngest/Telemetry" \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: kazan-dairesi-01" \
  -H "X-Device-Key: <geraeteschluessel>" \
  -d '{"Metrics":{"Kazan1_Run":1,"Kazan1_Temp":45.2}}'

Body-Formate

Der Body muss ein JSON-Objekt sein (ein Array auf oberster Ebene wird nicht akzeptiert). Im Body können diese festen Felder verwendet werden; die Feldnamen unterscheiden nicht zwischen Groß- und Kleinschreibung:

Feld	Beschreibung
MessageId	Optionale Nachrichtenkennung (höchstens 200 Zeichen). Eine zweite Anfrage mit derselben Kennung für dasselbe Gerät innerhalb von 24 Stunden wird nicht verarbeitet; die Antwort liefert IsDuplicate mit true. Dieser Eintrag wird im Arbeitsspeicher gehalten und beim Neustart des Dienstes zurückgesetzt.
DeviceTime	Optionaler Zeitstempel im Format ISO 8601 (z. B. 2026-10-15T08:30:00Z). Wird für Werte ohne eigenen Zeitpunkt verwendet.
Metrics	Objekt, dessen Feldname die Tag-Adresse und dessen Wert der Tag-Wert ist.
Tags	Array aus den Feldern SourceKey oder TargetTagId, Value und optional Ts.

Jedes Feld außer diesen wird nach den Einstellungen unter Nutzlastanalyse verarbeitet. Eine Anfrage muss mindestens eine Wertquelle enthalten; mehrere Formate können in derselben Anfrage zusammen verwendet werden.

Format Metrics: Alle Werte werden mit DeviceTime (falls nicht vorhanden, mit der Serverzeit) gespeichert.

{
  "DeviceTime": "2026-10-15T08:30:00Z",
  "Metrics": { "Kazan1_Run": 1, "Kazan1_Temp": 45.2 }
}

Format Tags: Jedes Element kann seinen eigenen Zeitstempel enthalten. Ist TargetTagId angegeben, wird das Tag über seine numerische Kennung zugeordnet.

{
  "Tags": [
    { "SourceKey": "Kazan1_Run", "Value": 1, "Ts": "2026-10-15T08:30:00Z" },
    { "TargetTagId": 1234, "Value": 45.2 }
  ]
}

Listenformat: Bei Listen-JSON-Pfad data.items und Standardwerten für die übrigen Einstellungen:

{
  "data": {
    "items": [
      { "sourceKey": "Kazan1_Run", "value": 1, "ts": "2026-10-15T08:30:00Z" },
      { "sourceKey": "Kazan1_Temp", "value": 45.2 }
    ]
  }
}

Zeigt der Pfad statt auf ein Array auf ein einzelnes Objekt, wird dieses Objekt als ein einzelner Wert gelesen.

Adressen im Feldnamen: Bei Listen-JSON-Pfad data und aktiviertem Tag-Adresse in Objektschlüsseln. Der Wert des Felds kann direkt der Tag-Wert sein oder ein Objekt, das die Felder Tag-Wertschlüssel und Tag-Zeitstempelschlüssel enthält:

{
  "data": {
    "Kazan1_Run": 1,
    "Kazan1_Temp": { "value": 45.2, "ts": "2026-10-15T08:30:00Z" }
  }
}

Werte und Zeitstempel

• Ein Wert kann eine JSON-Zahl, ein Text oder true / false sein. Werte null, Objekte oder Arrays werden abgelehnt.
• Bei Werten, die für numerische Tags als Text eintreffen, wird das Dezimaltrennzeichen nach der Einstellung Dezimaltrennzeichen interpretiert; Tausendertrennzeichen dürfen nicht verwendet werden. Als JSON-Zahl gesendete Werte sind von dieser Einstellung nicht betroffen.
• Zeitstempel müssen als Text im Format ISO 8601 gesendet werden. Unix-Zeitstempel (Zahlen) werden nicht unterstützt: In den Formaten Liste und Feldname werden sie ignoriert, in den Feldern DeviceTime oder Ts führen sie dazu, dass die gesamte Anfrage abgelehnt wird.
• Der Zeitpunkt eines Werts wird der Reihe nach aus dem eigenen Zeitstempel des Elements, aus dem Feld DeviceTime oder aus der Serverzeit übernommen.
• Die JSON-Darstellung eines einzelnen Werts darf 262.144 Zeichen nicht überschreiten; ein längerer Wert wird abgelehnt.

Antwort

Erreicht die Anfrage den Endpunkt und wird verarbeitet, kommt die Antwort – auch bei Authentifizierungsfehlern – mit dem HTTP-Code 200 zurück; das Ergebnis wird anhand der Felder Success und ErrorCode im Body ausgewertet. Ist der Body kein gültiges JSON oder hat eines der festen Felder nicht den erwarteten Typ, wird HTTP 400 zurückgegeben, ist Content-Type nicht JSON, HTTP 415.

Beispiel für eine erfolgreiche Antwort:

{
  "Success": true,
  "ErrorMessage": null,
  "ErrorCode": 0,
  "Payload": {
    "DeviceIdentifier": "kazan-dairesi-01",
    "DeviceId": 12,
    "MessageId": "kazan-0001",
    "IsDuplicate": false,
    "AcceptedCount": 2,
    "RejectedCount": 0,
    "Errors": []
  }
}

Auch wenn Success den Wert true hat, können einzelne Werte abgelehnt worden sein. AcceptedCount ist die Anzahl der angenommenen, RejectedCount die Anzahl der abgelehnten Werte; die Liste Errors enthält die Ablehnungsgründe (z. B. Tag mapping not found, Type conversion failed, Payload item too large).

Fehlercodes:

ErrorCode	Bedeutung
1101	Header X-Device-Id oder X-Device-Key fehlt.
4600, 4602	Gerätekennung oder Geräteschlüssel ungültig, oder das Gerät ist zur Laufzeit nicht geladen.
4601	Body ungültig: keine Wertquelle, im Element von Tags fehlt Adresse/Kennung oder Wert, MessageId überschreitet 200 Zeichen, oder aus dem Body konnte kein Wert gewonnen werden.
4603	Gerät passiv, REST-Server-Ingest aktiviert nicht aktiviert, oder das Gerät nimmt gerade keine Daten an.
4900	Die Lizenz enthält die REST-Integration nicht.
1000	Unerwarteter Fehler; Einzelheiten stehen im Dienstprotokoll.

Fehlerbehebung

Symptom	Prüfungen
1101 wird zurückgegeben	Prüfen Sie, ob die Header-Namen X-Device-Id und X-Device-Key richtig geschrieben und nicht leer sind.
4600 oder 4602 wird zurückgegeben	Prüfen Sie, ob der Wert X-Device-Id mit Externe Geräte-ID übereinstimmt und ob das Gerät in einem Kanal vom Typ RestServer liegt. Stellen Sie sicher, dass dieselbe Externe Geräte-ID nicht bei mehreren Geräten verwendet wird. Prüfen Sie, ob der Schlüssel im externen System mit dem zuletzt im Gerät gespeicherten Schlüssel übereinstimmt; wurde der Schlüssel erneuert, stellen Sie sicher, dass das Gerät gespeichert und das externe System aktualisiert wurde. Wurde das Gerät neu hinzugefügt, stellen Sie sicher, dass es zur Laufzeit geladen ist.
4603 wird zurückgegeben	Prüfen Sie die Optionen Aktiv und REST-Server-Ingest aktiviert des Geräts; stellen Sie sicher, dass das Gerät nach der Änderung zur Laufzeit geladen wurde.
4601 wird zurückgegeben	Prüfen Sie, ob der Body ein JSON-Objekt ist, ob Listen-JSON-Pfad auf den tatsächlichen Pfad im Body zeigt und ob die Namen unter Tag-Adressschlüssel / Tag-Wertschlüssel mit den Feldnamen im Body übereinstimmen.
Fehler Tag mapping not found	Prüfen Sie, ob die eingehende Adresse mit dem Feld Adresse oder dem Namen des Tags übereinstimmt und ob das Tag zum selben Gerät gehört.
Fehler Type conversion failed	Prüfen Sie den Typ des Werts, die Auswahl Datentyp des Tags und bei Zahlen, die als Text eintreffen, die Einstellung Dezimaltrennzeichen.
HTTP 400 wird zurückgegeben	Prüfen Sie, ob der Body gültiges JSON ist, ob die Felder DeviceTime und Ts Text im Format ISO 8601 sind und ob das Feld Tags ein Array ist.
Tag-Qualität fällt auf Uncertain oder Bad	Ist No-Data-Watchdog aktiviert, prüfen Sie, ob das Sendeintervall kürzer als der Wert Zeitüberschreitung bei fehlenden Daten [s] ist.