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": "" }
}

Der Zugriff auf das REST API kann durch die Benutzung des folgenden Links gewährt werden:

http(s)://<ip/domain>:<port>/api/json

z.B.

http://localhost:8181/api/json

Siehe Konfiguration des Ports

Spezifikationen der Anfrage

Methode POST
Inhaltstyp application/json
Kodierung UTF-8
Inhalt JSON Objekt

Tools für eine Beispielanfrage

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

Beispielanfrage (Token benutzen):

{
   "tk": "961:oseIqCm8WOOnPEE5g0tt1TZz2wbL/qUq", 
   "get": { 
      "na": "Temperature" 
   } 
}

Beispielanfrage (Benutzername-Passwort benutzen):

{
   "username": "user@demo.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,
                  "ct": 0,
                  "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 */ },
}

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 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 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.

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)

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,
                  "ct": 0,
                  "st": 0
               }
            ]
         },
         {
            "id": 964,
            "na": "Pressure",
            "dn": "Pressure",
            "ds": "",
            "lo": "",
            "ty": "double",
            "hi": true,
            "min": 10,
            "max": 110,
            "values": [
               {
                  "va": 86,
                  "ts": 1472740619105,
                  "ct": 0,
                  "st": 0
               },
               {
                  "va": 84,
                  "ts": 1472740617887,
                  "ct": 0,
                  "st": 0
               },
               {
                  "va": 98,
                  "ts": 1472740616967,
                  "ct": 0,
                  "st": 0
               },
               {
                  "va": 32,
                  "ts": 1472740615136,
                  "ct": 0,
                  "st": 0
               },
               {
                  "va": 31,
                  "ts": 1472740612718,
                  "ct": 0,
                  "st": 0
               }
            ]
         }
      ],
      "res": {
         "value": 0
      }
   }
}

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
ct nein Zahl Categorie
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,             /* the Category 0 and the Status 0                    */
      "ts": 1472800198510,  /* to Node: "/Nodes/Demo-Nodes/Pressure"              */
      "ct": 0,
      "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,             /* the Category 0 and the Status 0                    */
      "ts": 1472800198510,  /* to Node: "/Nodes/Demo-Nodes/Pressure"              */
      "ct": 0,
      "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 */
            "ct": 0,
            "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"
      }
   }
}

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
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."
      }
   }
}
  • Alle Eigenschaften eines Nodes modifizieren.
  • Diese Funktion ist noch nicht implementiert, wird aber bald eingebaut.
  • Einen Node entfernen.
  • Diese Funktion ist noch nicht implementiert, wird aber bald eingebaut.