 |
Online-Hilfe icom Data Suite |
REST-Schnittstelle
REST steht für Representational State Transfer und stellt eine Schnittstelle für Konfiguration, Statusabfrage und Ausführung manueller Aktionen der Applikation über das HTTP- und HTTPS-Protokoll zur Verfügung.
Folgende Befehle (HTTP-Methoden) stehen zum Bearbeiten der Ressourcen (Parameter bzw. Einträge) zur Verfügung:
- GET: Auslesen einer Ressource
- POST: Hinzufügen einer Ressource
- PUT: Ändern einer Ressource
- DELETE: Löschen einer Ressource
Aktivieren der REST-Schnittstelle
Bevor ein Zugriff auf die REST-Schnittstelle der Applikation über HTTP oder HTTPS möglich ist, muss dies im Menü Administration auf der Seite REST-Interface entsprechend konfiguriert werden. Dazu muss der Zugang über HTTP und/oder HTTPS aktiviert werden und bei aktiver Firewall im Router eine entsprechende Ausnahmeregel vorhanden und aktiv sein. Das unverschlüsselte HTTP-Protokoll sollte nur verwendet werden, wenn die Verbindung anderweitig verschlüsselt ist, z.B. durch ein VPN.
Adressierung
Die Adressierung erfolgt über die IP-Adresse der icom Data Suite, den Port für den REST-Zugriff und den Pfad zu den Parametern.
Der Pfad zu den Parametern ist hier genauso in Sektionen strukturiert wie im CLI.
Die Adressierung für die Parameter der REST-Schnittstelle in einer Applikation mit der IP-Adresse 192.168.1.10 und den HTTPS-Port ist zum Beispiel:
192.168.1.10:9091/configuration/administration/rest
Der Pfad beginnt immer mit einem bestimmten Verzeichnis, z.B. /configuration/ für Konfigurationsparameter, darauf folgen die entsprechenden Sektionen.
Syntax
Die Syntax der verfügbaren Befehle lässt sich leicht über die Autovervollständigung im CLI herausfinden. Siehe dieses Beispiel für die Vorgehensweise zum Ermitteln der Befehls-Syntax.
Konfiguration
Zum Auslesen oder Ändern der Konfiguration stehen die Befehle (HTTP-Methoden) GET, POST, PUT und DELETE zur Verfügung. Für Konfigurationsparameter beginnt der Pfad immer mit /configuration/.
Auslesen von Parametern (GET)
Parameter werden mit der HTTP-Methode GET ausgelesen.
Beispiel für das Auslesen der Parameter der REST-Schnittstelle:
GET /configuration/administration/rest
Als Antwort werden sämtliche Parameter mit ihrer Einstellung im JSON-Format zurückgegeben:
{
"profile": {
"name": "Profile"
},
"config": {
"http_active": "1",
"https_active": "1",
"http_port": "9090",
"https_port": "9091",
"https_cert": "app_cert",
"https_key": "app_key"
}
}
Der erste Abschnitt der Antwort referenziert das Profil, der zweite die Konfiguration mit den einzelnen Parametern.
Spezifizieren des Profils im GET-Befehl
Ohne eine Angabe bezieht sich der GET-Befehl immer auf das laufende Profil. Sollen die Parameter eines anderen Profils ausgelesen werden, muss der Befehl um die Angabe des Profils ergänzt werden.
Beispiel für das Auslesen der Benutzer von Profil "Profile_2":
GET /configuration/administration/rest?profile=Profile_2
Als Antwort werden sämtliche Benutzer von Profil "Profile_2" im JSON-Format zurückgegeben:
{
"profile": {
"name": "Profile_2"
},
"config": {
"user": [
{
"active": "1",
"username": "insys",
"group": "readwrite",
"index": "user1"
},
{
"active": "1",
"username": "icom",
"group": "readwrite",
"index": "user2"
},
{
"active": "1",
"username": "reader",
"group": "read",
"index": "user3"
}
]
}
}
Filtern einer Liste im GET-Befehl
Bei Listen gibt ein GET-Befehl sämtliche Einträge zurück. Um nur die gewünschten Einträge in der Antwort zu sehen, kann der Befehl mit einem Filter übergeben werden. Für den Filter wird der Parameter, nach dem gefiltert werden soll, ein Operator für die Filterfunktion und der gewünschte Wert des Parameters in einem JSON-Array angegeben:
{
"p" : "parameter",
"o" : "operator",
"v" : "value"
}
Der Parameter ist einer der Konfigurationsparameter im Listeneintrag.
Der Operator ist entweder eq (der Parameter muss exakt den Wert haben) oder like (der Parameter muss den Wert enthalten ohne Rücksicht auf Groß-/Kleinschreibung).
Der Value ist der Wert, dem der Parameterwert entsprechen oder der darin enthalten sein muss.
Beispiel für das Ausgeben aller Benutzer mit der Berechtigung "Lesen":
GET /configuration/administration/users?filter={"p":"group","o":"eq","v":"read"}
Als Antwort werden die Parameter sämtlicher Benutzer mit der Berechtigung "Lesen" im JSON-Format zurückgegeben:
{
"profile": {
"name": "Profile"
},
"config": {
"user": [
{
"active": "1",
"username": "reader",
"group": "read",
"index": "user3"
}
]
}
}
Es sind auch mehrfache Filter möglich. Dann werden sämtliche Filter mit einem logischen UND kombiniert, d.h. alle Filterkriterien müssen erfüllt werden, damit ein Eintrag angezeigt wird.
Beispiel für das Ausgeben aller Benutzer mit der Berechtigung "Lesen" und dem String "ic" im Benutzernamen:
GET /configuration/administration/users?filter=[{"p":"group","o":"eq","v":"read"},{"p":"username","o":"like","v":"ic"}]
Abfrage der Anzahl der Listeneinträge mit dem GET-Befehl
Um die Anzahl der Einträge einer Liste abzufragen, wird der Befehl um den Parameter return_size ergänzt, wobei mit dem Parameter ein Wert übergeben muss, der allerdings irrelvant ist.
Beispiel für das Ausgeben der Anzahl der angelegten Benutzer:
GET /configuration/administration/users?return_size=1
Als Antwort wird die Anzahl der Benutzer im JSON-Format zurückgegeben:
{
"profile": {
"name": "Profile"
},
"config": {
"list_size": 3
}
}
Wird dabei ein Filter mit übergeben, wird nur die Anzahl der Listeneinträge ausgegeben, welche den Filterkriterien entsprechen.
Hinzufügen von Parametern (POST)
Mit der HTTP-Methode POST werden Einträge zu Listen hinzugefügt. Dabei darf der Eintrag keinen Listenindex haben, da der Eintrag am Ende der Liste hinzugefügt wird.
Beispiel für das Hinzufügen des neuen Benutzers "newuser" mit Leserechten zum Profil "Profile" und gleichzeitiger Aktivierung des geänderten Profils:
POST /configuration/administration/users
{
"profile": {
"name": "Profile",
"activate": "1"
},
"config": {
"user": [
{
"active": "1",
"username": "newuser",
"group": "read"
}
]
}
}
Obiges Beispiel fügt den neuen Benutzer dem Profil "Profile" hinzu. Der Parameter "name": "Profile" spezifiziert das Profil, auf das die Änderungen Anwendung finden. Wird er weggelassen, wird der Benutzer dem laufenden Profil hinzugefügt. Der Parameter "activate": "1" aktiviert das geänderte Profil. Wird er weggelassen, wird das Profil lediglich geändert, aber nicht aktiviert. Sollen Änderungen auf das laufende Profil Anwendung finden und soll keine Aktivierung stattfinden, kann der gesamte Profil-Abschnitt weggelassen werden.
Manche Funktionen der Applikation erfordern Listen innerhalb von Listen.
Beispiel für das Hinzufügen eines neuen "Holding-Register"-Datenpunkts mit der Beschreibung "test" und dem Format "Unsigned Integer 32" zur Datenpunkt-Liste des Modbus-Geräts "mdbDev1":
POST /configuration/datapoints/modbus
{
"config": {
"device": [
{
"name": "mdbDev1",
"datapoint": [
{
"datapoint_active": "1",
"datapoint_description": "test",
"datapoint_type": "holding_register",
"datapoint_register": "",
"datapoint_bit": "",
"datapoint_format": "uint32"
}
]
}
]
}
}
Ändern von Parametern (PUT)
Mit der HTTP-Methode PUT werden bestehende Einträge in Listen geändert.
Beispiel für das Ändern der Rechte des Benutzers "icom" von Lesen auf Lesen/Schreiben:
PUT /configuration/administration/users
{
"profile": {
"name": "Profile"
},
"config": {
"user": [
{
"username": "newuser",
"group": "readwrite",
"index": "user1"
}
]
}
}
Der Listen-Identifikator, hier der Parameter "index" ist zwingend erforderlich zur Bestimmung des zu ändernden Eintrags.
Löschen von Parametern (DELETE)
Mit der HTTP-Methode DELETE werden komplette Listen oder bestehende Einträge aus Listen gelöscht.
Beispiel für das Löschen aller digitalen Ausgänge:
DELETE configuration/datapoints/digital_ios/outputs
Beispiel für das Löschen aller Benutzer mit dem String "test" im Benutzernamen aus dem Profil "Profile_2":
DELETE configuration/administration/users?filter={"p":"username","o":"like","v":"test"}&profile=Profile_2
Beispiel für das Löschen aller Modbus-Datenpunkte:
DELETE configuration/datapoints/modbus?delete=datapoint
Beispiel für das Löschen aller Modbus-Datenpunkte mit dem Typ "Holding-Register":
DELETE configuration/datapoints/modbus?delete=datapoint&filter={"p":"datapoint_type","o":"eq","v":"holding_register"}
Status-Abfragen
Zum Abfragen von Statusinformationen steht der Befehl (HTTP-Methode) GET zur Verfügung. Für Abfragen von Statusinformationen beginnt der Pfad immer mit /status/.
Beispiel für das Auslesen der aktuellen Werte der Datenpunkte:
GET /status/values
Als Antwort werden sämtliche Datenpunkte mit ihren Werten im JSON-Format zurückgegeben:
{
"status": {
"values": [
{
"name": "input1",
"value": "1"
},
{
"name": "input2",
"value": "0"
},
{
"name": "input3",
"value": "0"
}
]
}
}
Beispiel für das Auslesen der aktuellen Werte bestimmter Datenpunkte:
GET /status/values?status=input1,input3
Als Antwort werden nur die im Aufruf angegebenen Datenpunkte mit ihren Werten im JSON-Format zurückgegeben:
{
"status": {
"values": [
{
"name": "input1",
"value": "1"
},
{
"name": "input3",
"value": "0"
}
]
}
}
Anzeigen von Log-Dateien und Profilen
Zum Anzeigen von Log-Dateien und Profilen steht der Befehl (HTTP-Methode) GET zur Verfügung. Für die Anzeige von Log-Dateien und Profilen beginnt der Pfad immer mit /download/.
Log-Dateien
Eine Übersicht aller in der Applikation gespeicherten Log-Dateien erhält man durch einen GET-Aufruf der Log-Datei-Liste:
GET download/log?list_files=1
{
"log_files": [
"configd/current",
"configd/log-2018-02-20-09:45:39.bz2",
"httpd/current",
"httpd/log-2018-02-20-09:45:39.bz2",
...
]
}
Die Anzeige einer Log-Datei erhält man durch einen GET-Aufruf der jeweiligen Datei:
GET download/log?log_file=configd/current
2018-04-19 07:44:46 [configd] Started
2018-04-19 07:44:50 [configd] reading m3 config again
2018-04-19 07:44:51 [configd] M3 config read
2018-04-19 08:25:11 [configd] Profile 'Profile' activated
2018-04-19 08:25:11 [configd] cleaning persistent database
Profile
Eine Übersicht aller in der Applikation gespeicherten Profile erhält man durch einen GET-Aufruf der Profile-Liste:
GET download/profiles?list_files=1
{
"profiles": [
"Profile",
"Profile_2"
]
}
Die Anzeige eines Profils erhält man durch einen GET-Aufruf des jeweiligen Profils:
GET download/profiles?profile=Profile
Da das Profil ein Binär-Format aufweist, muss es entsprechend abgespeichert werden.
Debugging und Auslösen manueller Aktionen
Zum Debugging und Auslösen manueller Aktionen steht der Befehl (HTTP-Methode) POST zur Verfügung. Für das Debugging und Auslösen manueller Aktionen beginnt der Pfad immer mit /operation/.
Für Debugging-Zwecke ist es möglich, manuelle Aktionen auszuführen.
Beispiel für das manuelle Versenden der Nachricht "sms1":
POST /operation
{
"method" : "manual_action",
"params" : {
"type" : "message",
"options" : {
"message" : "sms1"
}
}
}
Beispiel für das manuelle Setzen des analogen Merkers 1 auf den Wert "13":
POST /operation
{
"method" : "manual_action",
"params" : {
"type" : "analog",
"options" : {
"datapoint" : "flag1",
"change" : "set_to",
"set" : "to_value",
"value" : "13"
}
}
}
Siehe dazu auch dieses Beispiel für die Vorgehensweise zum Ermitteln der Befehls-Syntax.