Diese Seite bearbeiten Links hierher Zu Buch hinzufügen PDF exportieren Buch erstellen Diese Seite zum Buch hinzufügen Buch erstellen Diese Seite aus Buch entfernen Buch anzeigen, ändern (0 Seite/n) Hilfe REST API Dokumentation 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": "" } } Zugriff 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 Siehe Konfiguration des Ports Anfrage & Antwort Spezifikationen der Anfrage Methode POST Inhaltstyp application/json Kodierung UTF-8 Inhalt JSON Objekt Tools für eine Beispielanfrage HTTP Anfrage Script HTTP Anfragetool für Firefox HTTP Anfragetool für Google Chrome Allgemeine Anfrage 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 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 */ } } Allgemeine Antwort 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 */ }, } Lesen / Browsen Anfrage 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 */ }] } Antwort Für jedes angeforderte „Get“- oder „Browse“-Objekt antwortet der Server mit einem Node (in Array), das folgende Eigenschaften hat: 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) 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 } } } Schreiben Anfrage 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 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 } ] } Antwort 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" } } } Erstellen Anfrage 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 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" }] } Antwort 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." } } } Updaten Alle Eigenschaften eines Nodes modifizieren. Diese Funktion ist noch nicht implementiert, wird aber bald eingebaut. Löschen Einen Node entfernen. Diese Funktion ist noch nicht implementiert, wird aber bald eingebaut. Inhaltsverzeichnis Zugriff Anfrage & Antwort Spezifikationen der Anfrage Tools für eine Beispielanfrage Allgemeine Anfrage Allgemeine Antwort Lesen / Browsen Anfrage Antwort Schreiben Anfrage Antwort Erstellen Anfrage Antwort Updaten Löschen