Die Schnittstelle muss eine HTTP Anfrage mit einem JSON Objekt (Kodierung: UTF-8) im Anfragekörper sein.
Beispiel:
POST /api/json HTTP/1.1 Content-Type: application/json; charset=utf-8 Host: localhost:8181 Content-Length: 79 { "tk": "1:QqjkQAtk4hyWRnbTt1+dZdGFCg3QE+nS", "browse": { "na": "" } }
Der Zugriff auf das REST API kann durch die Benutzung der folgenden URL gewährt werden:
http(s)://<ip/domain>:<port>/api/json
z.B.
http://localhost:8181/api/json
Siehe Konfiguration des Ports
Methode | POST |
---|---|
Inhaltstyp | application/json |
Kodierung | UTF-8 |
Inhalt | JSON Objekt |
Verpflichtend | Typ | Zweck | |
---|---|---|---|
tk | ja (falls username und password nicht spezifiziert sind) | String | Der Token des Nodes, der authorisiert werden soll. Von diesem Node werden alle Kinder relativ adressiert. Wie man den Token findet, sehen Sie unter Nodezugriff z.B. wird der Token des Nodes System/Plugins festgelegt, dann ist "na":"OPC UA Server" der relative Pfad des Nodes /System/Plugins/OPC UA Server . |
username | ja (falls tk nicht spezifiziert ist) | String | Die Emailadresse oder Telefonnummer des zu authentifizierenden Benutzers. |
password | ja (falls tk nicht spezifiziert ist) | String | Das Passwort des Benutzers. |
get | nein | Objekt | Nodes lesen |
browse | nein | Objekt | Nodes mit allen Kindern lesen (rekursiv) |
set | nein | Objekt | Nodes schreiben |
create | nein | Objekt | Nodes erstellen |
update | nein | Objekt | Nodes updaten |
delete | nein | Objekt | Nodes löschen |
Beispielanfrage (Token benutzen):
{ "tk": "961:oseIqCm8WOOnPEE5g0tt1TZz2wbL/qUq", "get": { "na": "Temperature" } }
Beispielanfrage (Benutzername-Passwort benutzen):
{ "username": "demo@user.org", "password": "demo", "get": { "na": "/Demo-Nodes/Temperature" } }
Anfrageframe:
{ "tk": /* Token */, "username": /* Username (falls 'tk' nicht angegeben ist) */, "password": /* Passwort (falls 'tk' nicht angegeben ist) */, "get": { /* "Read"-Elemente */ }, "browse": { /* "Browse"-Elemente */ }, "set": { /* "Set"-Elemente */ }, "create": { /* "Create"-Elemente */ }, "update": { /* "Update"-Elemente */ }, "delete": { /* "Delete"-Elemente */ } }
Verpflichtend | Typ | Zweck | |
---|---|---|---|
get | nein | Objekt | Lesen & Browsen Antwort |
browse | nein | Objekt | Lesen /& Browsen Antwort |
set | nein | Objekt | Schreiben Antwort |
create | nein | Objekt | Erstellen Antwort |
update | nein | Objekt | Updaten Antwort |
delete | nein | Objekt | Löschen Antwort |
res | ja | Objekt | Ergebnis der Abfrage |
Mögliche res
-Ergebnisse:
Verpflichtend | Typ | Zweck | |
---|---|---|---|
value | ja | Zahl | Ergebniscodes: >= 0: OK - Alles ist gut! < 0: Es ist ein Fehler aufgetreten! |
reason | nein | String | Grund für den Fehler |
Beispielantwort:
{ "get": { "nodes": [ { "id": 963, "na": "Temperature", "dn": "Temperature (°C)", "ds": "", "lo": null, "ty": "double", "hi": false, "min": -20, "max": 90, "unit": "°C", "values": [ { "va": 2, "ts": 1472738754519, "st": 0 } ] } ], "res": { "value": 0 } } }
Antwortframe:
{ "get": { /* "Get"-Elemente */ }, "browse": { /* "Browse"-Elemente */ }, "set": { /* "Set"-Elemente */ }, "create": { /* "Create"-Elemente */ }, "update": { /* "Update"-Elemente */ }, "delete": { /* "Delete"-Elemente */ }, "res": { /* "Result"-Elements */ }, }
Die „Get“ Funktion ermöglicht es, einen oder mehrere (historische) Werte zu lesen. „Browsen“ is wie „Get“, erlaubt aber das Erhalten des Istwerts des Nodes, daher gibt es rekursiv alle Childnodes mitsamt deren Istwerten wider.
Verpflichtend | Typ | Zweck | |
---|---|---|---|
id | ja (falls na nicht spezifiziert ist) | Zahl | Lokaler Identifier („Id“) des Nodes. |
na | ja (falls id nicht spezifiziert ist) | String | Name des Nodes. Falls ein Token zur Authentifizierung benutzt wird, ist dies der relative Pfas vom authentifizierten Node zum Zielnode (falls leer ist der authentifizierte Node selbst der Zielnode). Andernfalls (für Benutzername-Passwort-Authentifizierung) ist es der absolute Pfad zum Zielnode. |
count (falls es kein ttl gibt) | nein | Zahl | Die Anzahl an historischen Werten (max. 1000). Standard ist 1 , was bedeutet, dass der Istwert (statt historischen Werten) wird zurückgegeben. |
from (falls es kein ttl gibt) | nein | Zahl | Falls spezifiziert, der Startzeitstempel, von dem aus historische Werte zurückgeholt werden sollen. |
to (falls es kein ttl gibt) | nein | Zahl | Falls spezifiziert, der Endzeitstempel, bis zu dem historische Werte zurückgeholt werden sollen. |
ttl (falls es kein count gibt) | nein | Zahl oder null | Time To Live. Wenn dieser Parameter nicht existiert, gibt die Funktion direkt den aktuellen („gecachten“) Wert des Nodes zurück. Wenn der Parameter existiert, wird auf dem Node ein synchroner Lesevorgang durchgeführt, um vom zugrundeliegenden Gerät zu lesen. Ein Wert von null bedeutet, dass das standardmäßige Maximalwertalter („Max Value Age“) des Nodes verwendet werden soll. Ansonsten ist der Wert das Alter in Millisekunden, das der aktuelle Nodewert haben kann, um direkt zurückgegeben zu werden. Ist der Nodewert älter, wird er synchron vom Gerät gelesen. Um einen synchronen Lesevorgang unabhängig vom eingestellten Max Value Age des Nodes zu erzwingen, geben Sie 0 als Wert an. |
Beispiel Leseanfrage (Token benutzen):
{ "tk": "961:oseIqCm8WOOnPEE5g0tt1TZz2wbL/qUq", /* Authentication for "/Nodes/Demo-Nodes/" */ "get": [{ "na": "Temperature", /* Reads Node: "/Nodes/Demo-Nodes/Temperatur" */ }, { "id": 964, /* Reads Node: "/Nodes/Demo-Nodes/Pressure" */ "count": 5 /* Reads the last 5 historical values */ }] }
Beispiel Leseanfrage (Benutzername-Passwort benutzen):
{ "username": "demo@user.org", "password": "demo", "get": [{ "na": "/Nodes/Demo-Nodes/Temperature", /* must specify the absolute Node Path here */ }, { "id": 964, /* Reads Node: "/Nodes/Demo-Nodes/Pressure" */ "count": 5 /* Reads the last 5 historical values */ }] }
Verpflichtend | Typ | Zweck | |
---|---|---|---|
res | ja | Objekt | Ergebnis der Abfrage |
id | ja | Zahl | Identifier |
na | ja | String | Name |
dn | ja | String | Anzeigename |
ds | ja | String | Beschreibung |
lo | ja | String | Ort |
ty | ja | String | Typ |
hi | ja | Bool | Hat historische Werte |
min | ja | Zahl | Minimalwert |
max | ja | Zahl | Maximalwert |
values | ja | Objekt Array | |
nodes | nein (nur bei Browsen) | Objekt Array | Beinhaltet alle Childnodes (rekursiv). Für jedes Kind sind die Eigenschaften die gleichen wie in dieser Tabelle. |
Mögliche res
-Ergebnisse:
Verpflichend | Typ | Zweck | |
---|---|---|---|
value | ja | Zahl | Ergebniscodes: >= 0: OK - Alles ist gut! < 0: Es ist ein Fehler aufgetreten! |
reason | nein | String | Grund für den Fehler |
Mögliche value
-Ergebnisse:
Verpflichend | Typ | Zweck | |
---|---|---|---|
va | ja | jeder | Wert |
ts | ja | Zahl | Zeitstempel |
ct | ja | Zahl | Kategorie |
st | ja | Zahl | Status |
sttext | nein | String | Status-Text (falls gesetzt) |
Beispiel Leseantwort:
{ "get": { "nodes": [ { "id": 963, "na": "Temperature", "dn": "Temperature (°C)", "ds": "", "lo": null, "ty": "double", "hi": false, "min": -20, "max": 90, "values": [ { "va": 78, "ts": 1472740618590, "st": 0 } ] }, { "id": 964, "na": "Pressure", "dn": "Pressure", "ds": "", "lo": "", "ty": "double", "hi": true, "min": 10, "max": 110, "values": [ { "va": 86, "ts": 1472740619105, "st": 0 }, { "va": 84, "ts": 1472740617887, "st": 0 }, { "va": 98, "ts": 1472740616967, "st": 0 }, { "va": 32, "ts": 1472740615136, "st": 0 }, { "va": 31, "ts": 1472740612718, "st": 0 } ] } ], "res": { "value": 0 } } }
Mit der „Set“-Funktion ist es möglich, Werte auf einen spezifizierten Node zu schreiben.
Falls der Zeitstempel nicht festgelegt ist, ist es wichtig, die Anfragen für denselben Node sequenziell zu senden. Bevor also eine weitere Anfrage gesendet wird, muss man auf eine erfogreiche Antwort warten. Anders kann es passieren, dass die Werte in einer anderen Reihenfolge als beabsichtigt sortiert werden. Verschiedene Nodes können selbstverständlich parallel geschrieben werden.
Verpflichtend | Typ | Zweck | |
---|---|---|---|
id | ja (wenn na nicht spezifiziert ist) | Zahl | Identifier |
na | ja (wenn id nicht spezifiziert ist) | String | Name |
va | ja | jeder | Neuer Wert |
ts | nein | Zahl | Zeitstempel |
st | nein | Zahl | Status |
Beispiel Schreibanfrage (Token benutzen):
{ "tk": "961:oseIqCm8WOOnPEE5g0tt1TZz2wbL/qUq", /* Authentication for "/Nodes/Demo-Nodes/" */ "set": [ { "na": "Temperature", /* Write Value 21 to Node: "/Nodes/Demo-Nodes/Temperatur" */ "va": 21 }, { "id": 964, /* Write Value 84 with the Timestamp 02.09.16 07:09 */ "va": 84, /* and the Status 0 */ "ts": 1472800198510, /* to Node: "/Nodes/Demo-Nodes/Pressure" */ "st": 0 } ] }
Beispiel Schreibanfrage (Benutzername-Passwort benutzen):
{ "username": "demo@user.org", "password": "demo", "set": [ { "na": "/Nodes/Demo-Nodes/Temperature", /* Write Value 21 to Node (specified by absolute Node Path) */ "va": 21 }, { "id": 964, /* Write Value 84 with the Timestamp 02.09.16 07:09 */ "va": 84, /* and the Status 0 */ "ts": 1472800198510, /* to Node: "/Nodes/Demo-Nodes/Pressure" */ "st": 0 } ] }
Für die „Set“-Funktion hat das Nodearray lediglich Antwortobjekte für gescheiterte Anfragenobjekte.
Verpflichtend | Typ | Zweck | |
---|---|---|---|
res | ja | Objekt | Ergebnis der Abfrage |
nodes | ja | Objekt Array | Beinhaltet alle Childnodes (rekursiv). Für jedes Kind sind die Eigenschaften die gleichen wie in dieser Tabelle. |
Mögliche res
-Ergebnisse:
Verpflichtend | Typ | Zweck | |
---|---|---|---|
value | ja | Zahl | Ergebniscodes: >= 0: OK - Alles ist gut! < 0: Es ist ein Fehler aufgetreten! |
reason | no | String | Grund für den Fehler |
Beispiel Schreibantwort:
{ "set": { "nodes": [], "res": { "value": 0 } } }
Beispiel Schreibantwort (Fehlerfall):
{ "set": { "nodes": [ { "id": 964, "va": 84, "ts": 4728001980, /* 24.02.1970 17:20 */ "st": 0, "res": { "value": -1, "reason": "values[0].Timestamp is lower than 01.01.2000 00:00:00 +00:00" } } ], "res": { "value": -1, "reason": "At least one error occured when processing the nodes: values[0].Timestamp is lower than 01.01.2000 00:00:00 +00:00" } } }
Verpflichtend | Typ | Zweck | |
---|---|---|---|
pid | ja (falls pna nicht spezifiziert ist) | Zahl | Parent Identifier Neuer Node wird als Kind dieses Nodes erstellt. |
pna | ja | String | Parent Name Neuer Node wird als Kind dieses Nodes erstellt. z.B. wenn pna=„Demo-Nodes“ ist, wird der neue Node in diesem Ordner angelegt. Der neue Node wird „/Nodes/Demo-Nodes/Name“ sein. |
na | ja (falls pid nicht spezifiziert ist) | String | Name |
dn | nein | String | Anzeigename |
ds | nein | String | Beschreibung |
lo | nein | String | Ort |
path | nein | String | Path (z.B. Adresse bei Device-Variablen) |
ty | ja | String | Typ |
hi | nein | Zahl | Hysteresis |
min | nein | Zahl | Minimalwert |
max | nein | Zahl | Maximalwert |
Beispiel Erstellanfrage:
{ "tk": "938:843uqQeSaLAg+7TALdOhGDkLOHFZevZw", /* Authentication for "/Nodes" */ "create": [{ "pna": "Demo-Nodes", /* Creates Node "/Nodes/Demo-Nodes/New-Node-1" */ "na": "New-Node-1", /* with Type string */ "ty": "string" }, { "pid": 961, /* Creates Node "Nodes/Demo-Nodes/New-Node-2" */ "na": "New-Node-2", /* with specified Displayname (dn), */ "dn": "Display New-Node-2", /* Description (ds) and Type double */ "ds": "This is the new Node 2", "ty": "double" }] }
Verpflichtend | Typ | Zweck | |
---|---|---|---|
res | ja | Objekt | Ergebnis der Abfrage |
nodes | ja | Objekt Array | Beinhaltet alle Childnodes (rekursiv). Für jedes Kind sind die Eigenschaften dieselben wie in dieser Tabelle. |
Mögliche res
-Ergebnisse:
Verpflichtend | Typ | Zweck | |
---|---|---|---|
value | ja | Zahl | Ergebniscodes: >= 0: OK - Alles ist gut! < 0: Es ist ein Fehler aufgetragen! |
reason | nein | String | Grund für den Fehler |
Beispiel Erstellantwort:
{ "tk": "938:843uqQeSaLAg+7TALdOhGDkLOHFZevZw", "create": [{ "pna": "Demo-Nodes", "na": "New-Node-1", "ty": "string" }, { "pid": 961, "na": "New-Node-2", "dn": "Display New-Node-2", "ds": "This is the new Node 2", "ty": "double" }] }
Beispiel Erstellantwort (Fehlerfall):
{ "create": { "nodes": [ { "pna": "Demo-Nodes", "na": "Existing-Node", "ty": "string", "res": { "value": -1, "reason": "An object with the same name does already exist. Please choose another name." } }, { "pid": 961, "na": "New-Node-2", "dn": "Display New-Node-2", "ds": "This is the new Node 2", "ty": "qwertz", "res": { "value": -1, "reason": "Could not find the Node Type \"qwertz\"." } } ], "res": { "value": -1, "reason": "At least one error occured when processing the nodes: An object with the same name does already exist. Please choose another name." } } }