Die Rest-API ist immer unter folgender Adresse erreichbar:
https://localhost:22722/api/{Ressource}
(Link funktioniert nur bei korrekt installierter und konfigurierter DataSuite)
Abhängig von der gewählten Authentifizierung, müssen Sie in jeder Anfrage noch Benutzername und Passwort im Header (Basic) übergeben. Wie genau Sie die Basic Authentifikation einstellen, ist abhängig von Ihrem Client.
Alle Informationen werden immer im JSON Format übertragen.
Fehlercodes auswerten #
Die folgenden HTTP Status Codes werden zurückgegeben. Wenn die Anfrage mit einem Fehler beendet wurde, wird zu dem Fehlercode eine Fehler-Objekt zurückgegeben, welches eine Fehlermeldung enthält.
| HTTP Code | Beschreibung |
| 200 | Anfrage erfolgreich ausgeführt |
| 400 | Bad Request: Anfrage konnte nicht ausgeführt werden. Parameter sind ungültig. |
| 401 | Unauthorized: Authentifizierung (Benutzername/Passwort) ist ungültig |
| 403 | Forbidden: Der Zugriff auf die Ressource ist in den Einstellungen des Webservers/Rest-API auf „Kein Zugriff“ eingestellt. |
| 404 | Not Found: Die Adresse wurde nicht gefunden. |
Objekt: Fehler
| Parameter | Typ | Beschreibung |
| code | string | HTTP Status Code |
| message | string | Fehlermeldung |
SPS – Endpunkte #
Alle Steuerungen abfragen (Get) #
Über den Endpunkt api/plcs erhalten Sie eine Liste aller freigegebenen Steuerungen.
GET
https://localhost:22722/api/plcs
Parameter: Keine
Antwort: Auflistung von SPS Objekten (JSON).
Objekt: SPS
| Parameter | Typ | Beschreibung |
| name | string | Name der SPS |
| ip | string | IP Adresse der SPS. Bei dem Simulator ist es [MB] Simulator |
| plcType | string | SPS Typ Simulator, S7-300, S7-1200, S7-… |
| connectionType | string | Verbindungstyp: [MB] Simulator S7 OPC UA |
| connectionState | int | Verbindungsstatus: 0 = Getrennt 1 = Verbindung wird hergestellt 2 = Verbunden |
| dataBlocks | Auflistung von Strings | Alle importierten Datenbausteine |
Variablen eines Datenbausteins abfragen (Get) #
Über den Endpunkt api/plcs/{SPS-Name}/datablocks/{DB-Name}/variables erhalten Sie eine Liste aller SPS Variablen in diesem Datenbaustein.
GET
https://localhost:22722/api/plcs/{SPS-Name}/datablocks/{DB-Name}/variables
https://localhost:22722/api/plcs/SPS/datablocks/Daten/variables
Parameter: Die Parameter SPS-Name und DB-Name werden benötigt.
| Parameter | Typ | Beschreibung |
| SPS-Name | string | Name der SPS |
| DB-Name | string | Name des Datenbausteins |
Antwort: Auflistung der Variablen des Datenbausteins als Variablen Objekt (JSON).
Objekt: Variable
| Parameter | Typ | Beschreibung |
| name | string | Name der SPS |
| fullName | string | Vollständiger Name der Variable. Wenn die Variable z. B. innerhalb eines Structs liegt: StructName.VariableName |
| dataType | String | S7 Datentyp |
| variables | Auflistung vom Typ Variable | Enthält alle verschachtelten Variablen, z. B. bei Structs oder Arrays. |
Variablenwerte abfragen (Get) #
Über den Endpunkt api/plcs/{SPS-Name}/datablocks/{DB-Name}/values?variables=.. können Sie Variablenwerte abfragen.
GET
https://localhost:22722/api/plcs/{SPS-Name}/datablocks/{DB-Name}/values
?variables={Variable-Name},{Variable-Name}
https://localhost:22722/api/plcs/SPS/datablocks/Daten/values
?variables=Auftrag,Produkt
Sie können entweder eine einzelne Variable abfragen oder auch mehrere Variablen gleichzeitig. Wenn Sie mehrere Variablen lesen möchten, geben Sie einfach die Namen der Variablen durch ein Komma getrennt an. Alle Variablen müssen sich im gleichen Datenbaustein befinden.
Parameter: Die Parameter SPS-Name, DB-Name Variable-Name werden benötigt.
| Parameter | Typ | Beschreibung |
| SPS-Name | string | Name der SPS |
| DB-Name | string | Name des Datenbausteins |
| Variable-Name | string | Name einer oder mehrerer Variablen. Mehrere Variablen werden durch ein Komma getrennt. |
| mode (optional) | string | Wenn Mode auf raw gesetzt wird, werden keine Informationen zu den Variablen zurückgegeben, sondern nur der Wert. |
Antwort: Auflistung der Variablen des Datenbausteins als Variablen Objekt (JSON).
Objekt: Variable
| Parameter | Typ | Beschreibung |
| name | string | Name der Variable |
| dataType | string | S7 Datentyp |
| value | Abhängig vom Typ der Variable | Abhängig vom Typ der Variable. Wird im folgenden Absatz erläutert. |
Der Wert (Value) einer Variable ist abhängig vom Datentyp der Variable. Dabei wird zwischen den vier Möglichkeiten unterschieden:
1. Einfacher Werte-Datentyp
Bei einfachen Datentypen, wie z. B. Byte, Int, String, wird der einfache Wert als Value zurückgegeben.
2. Struct-Datentyp
Bei einem Struct befindet sich in Value eine Auflistung des Objekttyps Variable.
3. Array-Datentyp
Bei einem Array befindet sich in Value eine Auflistung des Objekttyps Variable. Jedes Element des Arrays wird als vollständige Variable angegeben.
4. Struct-Array-Datentyp
Bei einem Struct-Array befindet sich in Value eine Auflistung des Objekttyps Variable (Struct). Jedes Element in der Auflistung ist dabei ein Struct, welches wiederum in Value eine Auflistung vom Objekt Variable enthält.
Variablenwerte schreiben (Post) #
Über den Endpunkt api/plcs/{SPS-Name}/datablocks/{DB-Name}/values können Sie Variablenwerte in die SPS schreiben. Um Variablen zu schreiben, gibt es zwei Möglichkeiten.
Variablenwerte direkt als Parameter mit übergeben #
Variablenwerte werden direkt als Parameter mit übergeben: {Name}={Wert}. Wenn Sie mehrere Variablen schreiben möchten, können Sie diese durch ein Komma trennen.
Diese Methode eignet sich, um einfache Variablenwerte unkompliziert zu schreiben. Bei dieser Methode wird der Body der Anfrage leer gelassen.
POST
https://localhost:22722/api/plcs/{SPS-Name}/datablocks/{DB-Name}/values
?variables={Variable-Name}={Variable-Value}
https://localhost:22722/api/plcs/SPS/datablocks/Daten/values
?variables=Auftrag=123,Produkt=abc
Parameter: Die Parameter SPS-Name, DB-Name, Variable-Name und Variable-Value werden benötigt.
| Parameter | Typ | Beschreibung |
| SPS-Name | string | Name der SPS |
| DB-Name | string | Name des Datenbausteins |
| variables Variable-Name = Variable-Value | string | Name einer oder mehrerer Variablen mit der Zuweisung des Wertes. Mehrere Zuweisungen werden durch ein Komma getrennt. |
Antwort: Status Code 200 (OK). Es wird kein Body zurückgegeben.
Variablenwerte als JSON Body übergeben #
Wenn Sie viele Variablen in einem Vorgang schreiben möchten, eignet sich die Übertragung der Variablenwerte als JSON Body.
POST
https://localhost:22722/api/plcs/{SPS-Name}/datablocks/{DB-Name}/values
https://localhost:22722/api/plcs/SPS/datablocks/Daten/values
Parameter: Die Parameter SPS-Name, DB-Name, Variable-Name und Variable-Value werden benötigt.
| Parameter | Typ | Beschreibung |
| SPS-Name | string | Name der SPS |
| DB-Name | string | Name des Datenbausteins |
Im Body der Anfrage werden die zu schreibenden Variablenwerte übergeben. Diese werden als Auflistung des Objekts Variablenwert übertragen. Wenn Sie nur einen Wert schreiben möchten, können Sie anstatt der Auflistung auch nur das einzelne Objekt senden.
Objekt Variablenwert
| Parameter | Typ | Beschreibung |
| fullName | string | Vollständiger Name der Variable. Wenn die Variable z. B. innerhalb eines Structs liegt: StructName.VariableName Für Array Variablen: Array[10].ID Den Namen erhalten Sie durch die Abfrage der verfügbaren Variablen des Datenbausteins |
| value | object | Neuer Variablenwert |
Übertragung eines Variablenwert-Objekts
Übertragung einer Auflistung von Variablenwert-Objekten
Antwort: Status Code 200 (OK). Es wird kein Body zurückgegeben.
Trigger – Endpunkte #
Über den Endpunkt api/trigger können erhalten Sie eine Auflistung aller über die Rest-API verfügbaren Trigger.
Get
https://localhost:22722/api/trigger
Parameter: Keine Parameter
Antwort: Auflistung der Trigger (JSON).
Objekt: Trigger
| Parameter | Typ | Beschreibung |
| name | string | Name des Triggers |
| group | string | Gruppe des Triggers |
| isEnabled | Bool | Gibt an, ob der Trigger aktiviert ist. False = Trigger ist deaktiviert, wird nicht überwacht, kann nicht gestartet werden. True = Trigger ist aktiviert, wird überwacht, kann gestartet werden. |
| actions | Auflistung vom Typ string | Beschreibung aller im Trigger definierten Aktionen |
Trigger starten (Post) #
Über den Endpunkt api/trigger/{Trigger-Name}/start können Sie einen Trigger starten.
Post
https://localhost:22722/api/trigger/{Trigger-Name}/start
Parameter: Die Parameter Trigger-Name wird benötigt.
| Parameter | Typ | Beschreibung |
| Trigger-Name | string | Name des Triggers |
Antwort: Status Code 200 (OK). Es wird kein Body zurückgegeben.
