REST API Dokumentation

Buch erstellen

Diese Seite zum Buch hinzufügen

Buch erstellen

Diese Seite aus Buch entfernen

Buch anzeigen, ändern (0 Seite/n)

Hilfe

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

Spezifikationen der Anfrage

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

Tools für eine Beispielanfrage

HTTP Anfrage Script

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": "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 */ },
}

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)

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

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

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

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

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.

REST API Dokumentation

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