TOP
SSV Software Systems Register  Register
Log in to check your private messages  Log in to check your private messages
Startseite FAQ Search Mitglieder Profile  Log in 
SSV Support-Forum
Cloud REST APIs …

 
Post new topic   Reply to topic    SSV-Forum Forum Index >>> IGW/935
<<< Previous topic - Next topic >>>  
Display posts from previous:   
Author Message
kdw



Joined: 05 May 2006
Posts: 1460

PostPosted: 04.10.2014, 18:36    Post subject: Cloud REST APIs … Reply with quote

Hallo Forum.

Wenn Sie ein IGW/935 mit einer Cloud- bzw. IoT-Serviceplattform verbinden wollen, müssen Sie sich zunächst einmal das jeweilige API (Application Programming Interface) genau anschauen. Die meisten Plattformen bieten ein REST-API (REST = REpresentational State Transfer, siehe zum Beispiel http://www.restapitutorial.com/lessons/whatisrest.html#).

REST folgt dem Create-Read-Update-Delete-(CRUD)-Gedanken aus der Datenbankwelt. D. h., es gibt jeweils separate (API-) Funktionen, um ein Datenobjekt zu erzeugen, den aktuellen Wert zu lesen, einen neuen Wert zu schreiben und das Objekt wieder zu löschen. In einem REST-API werden die einzelnen CRUD-Funktionen durch HTTP-Request/Response-Paare realisiert. Hierzu zwei Beispiele:

Der folgende HTTP-POST-Request ermöglicht zum Beispiel einen Variablen-Update auf der EXOSITE-IoT-Plattform (http://exosite.com/). In diesem Fall wird in die Variable Tengine der neue Wert 12.34 geschrieben. Das EXOSITE-REST-API erfordert dafür einen HTTP-POST-Request. Beachten Sie bitte, dass innerhalb des EXOSITE-REST-API-HTTP-Requests ein API-Key als Zugriffsberechtigungsschlüssel erforderlich ist (siehe HTTP-Header-Element X-Exosite-CIK). Diesen Code erhält man durch die Registrierung auf der EXOSITE-IoT-Plattform.

Code:
POST /onep:v1/stack/alias HTTP/1.1\r\n
User-Agent: curl/7.37.0\r\n
Host: m2.exosite.com\r\n
X-Exosite-CIK: 88caf201140928b632a32c33a94762f93fb16438\r\n
Accept: application/x-www-form-urlencoded; charset=utf-8\r\n
Content-Length: 13\r\n
Content-Type: application/x-www-form-urlencoded\r\n
\r\n
Tengine=12.34

Der gesamte Request wurde auf einem PC mit cURL (http://curl.haxx.se/) erzeugt. Die Zeichenfolge „Tengine=12.34“ transportiert die Daten für den Update. Ist der Update erfolgreich, antwortet der EXOSITE-Server mit dem HTTP-Statuscode „204 No Content“:

Code:
HTTP/1.1 204 No Content\r\n
Date: Fri, 03 Oct 2014 04:58:37 GMT\r\n
Content-Length: 0\r\n
Connection: keep-alive\r\n
Server: nginx\r\n
\r\n


Ein zweites Beispiel zeigt den HTTP-Request für einen Variablen-Update mit dem SSV Real Time Data Channel (SSV/RTDC) API. Dieses API erfordert einen PUT-Request mit einem JSON-Objekt, um einen Werte-Update auszuführen. Im RTDC-REST-API sind zwei API-Key als Zugriffsberechtigungsschlüssel für eine Update-Operation erforderlich (siehe HTTP-Header-Elemente X-RTDC-Access-Key und X-RTDC-Auth-Key). Der X-RTDC-Auth-Key ist ein allgemeiner Zugriffsschlüssel, der in jedem einzelnen REST-Request erforderlich ist. Bei allen „Schreiboperation“ (Create, Update, Delete) ist zusätzlich ein X-RTDC-Access-Key als zweiter Schlüssel erforderlich.

Code:
PUT /rtdc/v0/ HTTP/1.1\r\n
Host: 192.168.0.54\r\n
Connection: keep-alive\r\n
Content-Length: 91\r\n
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64)\r\n
Cache-Control: no-cache\r\n
Origin: chrome-extension://fdmmgilgnpjigdojojpjoooidkmcomcm\r\n
X-RTDC-Access-Key: ad698900-2546-11e3-95ef-e3081976e170\r\n
X-RTDC-Auth-Key: 2f3113d0-2796-11e3-87fb-c560cb0ca47b\r\n
Content-Type: application/json; charset=UTF-8\r\n
Accept: */*\r\n
Accept-Encoding: gzip,deflate,sdch\r\n
Accept-Language: de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4\r\n
\r\n
{"do": [{"name":"BAT1","item":[{"name":"SI_PowerL1","data":209.8}]}]}


Die Zeichenfolge

Code:
{"do": [{"name":"BAT1","item":[{"name":"SI_PowerL1","data":209.8}]}]}


ist ein RTDC-JSON-Objekt, um in dem Datenobjekt “BAT1” das Daten-Item „SI_PowerL1“ auf den neuen Wert „209.8“ zu setzen. Ist der Update erfolgreich, antwortet der RTDC-Server mit dem HTTP-Statuscode „200 OK“ und einem zusätzlichen JSON-Objekt:

Code:
HTTP/1.1 200 OK\r\n
Date: Mon, 29 Sep 2014 16:20:14 GMT\r\n
Server: Apache/2.2.22 (Debian)\r\n
X-Powered-By: PHP/5.4.4-14+deb7u14\r\n
Content-Length: 48\r\n
Keep-Alive: timeout=5, max=100\r\n
Connection: Keep-Alive\r\n
Content-Type: application/json\r\n
\r\n
{"status":{"code":0,"info":"Update successful"}}


Der PUT-Request für das RTDC-API wurde mit dem POSTMAN-Extension unter Chrome ausgeführt.

Gruß KDW
Back to top
View user's profile Send private message
kdw



Joined: 05 May 2006
Posts: 1460

PostPosted: 05.10.2014, 08:10    Post subject: Die RTDC-CRUD-Funktionen … Reply with quote

Hallo Forum.

Hier noch ein paar Hintergrundinformationen zum den SSV/RTDC: Die wichtigsten Elemente der SSV Real Time Data Channel (SSV/RTDC), auf die per REST-API zugegriffen werden kann, sind Datenprojekt (dp), Datenobjekt (do) und Daten-Item (di).

Ein Datenprojekt ist ein JSON-Objekt, das beliebig viele Datenobjekte enthalten kann. Ein Datenobjekt ist ein JSON-Objekt, in dem beliebig viele Daten-Items enthalten sein können.

Die einzelnen CRUD-Funktionen sind im RTDC-REST-API durch die HTTP-Methoden POST (Create), GET (Read), PUT (Update) und DELETE (Delete) implementiert.

1. Create: Ein RTDC-Create-Request erzeugt einzelne oder mehrere Datenobjekte innerhalb eines Datenprojekts bzw. einzelne oder mehrere Daten-Items in einem Datenprojekt.

URI:
Code:
http://<host>/rtdc/v0/

HTTP-Request:
Code:
POST /rtdc/v0/ HTTP/1.1\r\n
Host: <host>\r\n
X-RTDC-Auth-Key: <valid authentication key>\r\n
X-RTDC-Access-Key: <valid access key>\r\n
Content-Type: application/json; charset=UTF-8\r\n
Content-Length: <length>\r\n
\r\n
<JSON data>

Beispiel für einen RTDC-Create-Request:

URI:
Code:
http://192.168.0.118/rtdc/v0/

HTTP-Request:
Code:
POST /rtdc/v0/ HTTP/1.1\r\n
Host: 192.168.0.54\r\n
X-RTDC-Auth-Key: ad698900-2546-11e3-95ef-e3081976e170\r\n
X-RTDC-Access-Key: 2f3113d0-2796-11e3-87fb-c560cb0ca47b\r\n
Content-Type: application/json; charset=UTF-8\r\n
Content-Length: 159\r\n
\r\n
{"do": [{"name":"BHKW_1",
         "item":[{"name":"Tengine",
         "desc":"Engine Temperature",
         "type":"GAUGE",
         "property":{"unit":"Degree Celsius"}}]
}]}

Python-Beispielcode:
Code:
import httplib
import socket

body_js = '{"do":[{"name":"BHKW_1",'\
          '"item":[{"name":"Tengine",'\
          '"desc":"Engine Temperature",'\
          '"type":"GAUGE",'\
          '"property":{"unit":"Degree Celsius"}}]}]}'
   
try:
    conn = httplib.HTTPConnection('192.168.0.54', 80)
    conn.connect()
    request = conn.putrequest('POST', '/rtdc/v0/')
    headers = {}
    headers['X-RTDC-Auth-Key'] = 'ad698900-2546-11e3-95ef-e3081976e170'
    headers['X-RTDC-Access-Key'] = '2f3113d0-2796-11e3-87fb-c560cb0ca47b'
    headers['Content-Type'] = 'application/json; charset=utf-8'
    headers['Content-Length'] = "%d"%(len(body_js))
    for item in headers:
        conn.putheader(item, headers[item])
    conn.endheaders()
    conn.send(body_js)
    response = conn.getresponse()
    print response.status, response.reason
    print response.read()
    conn.close()
except (httplib.HTTPException, socket.error) as ex:
    print 'RTDC service not ready ...'

2. Read: Ein RTDC-Read-Request ermöglicht, alle Daten-Items eines Datenobjekts, einzelne Daten-Items oder ein einziges Daten-Item mit Zeitstempel des letzten Updates auszulesen. Darüber hinaus kann auch ein vollständiges Datenobjekt inklusive aller Meta-Daten gelesen werden.

URI:
Code:
http://<host>/rtdc/v0/<query string parameter>

HTTP-Request:
Code:
GET /rtdc/v0/<query string parameter> HTTP/1.1\r\n
Host: <host>\r\n
X-RTDC-Auth-Key: <valid authentication key>\r\n
\r\n

Beispiel für einen RTDC-Read-Request:

URI:
Code:
http://192.168.0.54/rtdc/v0/?get=data&do=BHKW_1&item=ophour

HTTP-Request:
Code:
GET /rtdc/v0/?get=data&do=BHKW_1&item=ophour HTTP/1.1\r\n
Host: 192.168.0.54\r\n
X-RTDC-Auth-Key: ad698900-2546-11e3-95ef-e3081976e170\r\n
\r\n

Python-Beispielcode:
Code:
import httplib
import socket

try:
    conn = httplib.HTTPConnection('192.168.0.54', 80)
    conn.connect()
    request = conn.putrequest('GET', '/rtdc/v0/ \
    ?get=data&do=BHKW_1&item=ophour')
    headers = {}
    headers['X-RTDC-Auth-Key'] = 'ad698900-2546-11e3-95ef-e3081976e170'
    headers['Content-Type'] = 'application/json; charset=utf-8'
    for item in headers:
        conn.putheader(item, headers[item])
    conn.endheaders()
    response = conn.getresponse()
    print response.status, response.reason
    print response.read()
    conn.close()
except (httplib.HTTPException, socket.error) as ex:
    print 'RTDC service not ready ...'

3. Update: Mit einem RTDC-Update-Request können einzelne oder alle Daten-Items in einem Datenobjekt mit neuen Werten versehen werden.

URI:
Code:
http://<host>/rtdc/v0/

HTTP-Request:
Code:
PUT /rtdc/v0/ HTTP/1.1\r\n
Host: <host>\r\n
X-RTDC-Auth-Key: <valid authentication key>\r\n
X-RTDC-Access-Key: <valid access key>\r\n
Content-Type: application/json; charset=UTF-8\r\n
Content-Length: <length>\r\n
\r\n
<JSON data>

Beispiel für einen RTDC-Update-Request:

URI:
Code:
http://192.168.0.118/rtdc/v0/

HTTP-Request:
Code:
PUT /rtdc/v0/ HTTP/1.1\r\n
Host: 192.168.0.54\r\n
X-RTDC-Auth-Key: ad698900-2546-11e3-95ef-e3081976e170\r\n
X-RTDC-Access-Key: 2f3113d0-2796-11e3-87fb-c560cb0ca47b\r\n
Content-Type: application/json; charset=UTF-8\r\n
Content-Length: 68\r\n
\r\n
{"do":[{"name":"BAT1","item":[{"name":"SI_PowerL1","data":209.8}]}]}

Python-Beispielcode:
Code:
import httplib
import socket

body_js = '{"do":[{"name":"BAT1","item":[{"name":"SI_PowerL1", \
            "data": 209.8}]}]}'

try:
    conn = httplib.HTTPConnection('192.168.0.54', 80)
    conn.connect()
    request = conn.putrequest('PUT', '/rtdc/v0/')
    headers = {}
    headers['X-RTDC-Auth-Key'] = 'ad698900-2546-11e3-95ef-e3081976e170'
    headers['X-RTDC-Access-Key'] = '2f3113d0-2796-11e3-87fb-c560cb0ca47b'
    headers['Content-Type'] = 'application/json; charset=utf-8'
    headers['Content-Length'] = "%d"%(len(body_js))
    for item in headers:
        conn.putheader(item, headers[item])
    conn.endheaders()
    conn.send(body_js)
    response = conn.getresponse()
    print response.status, response.reason
    print response.read()
    conn.close()
except (httplib.HTTPException, socket.error) as ex:
    print 'RTDC service not ready ...'

4. Delete: Ein RTDC-Delete-Request löscht ein einzelnes Datenobjekt, eine Liste von Datenobjekten innerhalb eines Datenprojekts, ein einzelnes Daten-Item oder eine Liste von Daten-Items in einem Datenobjekt. Dabei gehen die gespeicherten Werte verloren.

URI:
Code:
http://<host>/rtdc/v0/<query string parameter>

HTTP-Request:
Code:
DELETE /rtdc/v0/<query string parameter> HTTP/1.1\r\n
Host: <host>\r\n
X-RTDC-Auth-Key: <valid authentication key>\r\n
X-RTDC-Access-Key: <valid access key>\\r\n
\r\n

Beispiel für einen RTDC-Delete-Request:

URI:
Code:
http://192.168.0.54/rtdc/v0/?do=1&item=9

HTTP-Request:
Code:
DELETE /rtdc/v0/?do=1&item=9 HTTP/1.1\r\n
Host: 192.168.0.54\r\n
X-RTDC-Auth-Key: ad698900-2546-11e3-95ef-e3081976e170\r\n
X-RTDC-Access-Key: 2f3113d0-2796-11e3-87fb-c560cb0ca47b\r\n
\r\n

Anmerkungen zu den JSON-Daten in einem RTDC-Create- bzw. Update-Request: Die Daten können sowohl als Zeichenfolge ohne Leerzeichen und Zeilenumbrüche als auch mit diesen Trennelementen in einem Request an einen RTDC-Server übermittelt werden.

Zu jedem RTDC-HTTP-REST-Request liefert ein RTDC-Server einen HTTP-Status- bzw. Fehlercode. Hier eine Übersicht der möglichen Antworten:

200: OK – Die gewünschte Aktion wurde ausgeführt
400: Bad Request – Der HTTP-Request war fehlerhaft aufgebaut
401: Unauthorized – Die Zugriffsberechtigung fehlt oder war ungültig
404: Not found – Request war gültig, aber die ausgewählte Ressource existiert nicht
405: Method Not Allowed – Request beinhaltet eine nicht unterstützte HTTP-Methode
500: Internal Server Error – Der Request kann nicht bearbeitet werden

Gruß KDW
Back to top
View user's profile Send private message
Display posts from previous:   
Post new topic   Reply to topic    SSV-Forum Forum Index >>> IGW/935 All times are GMT + 1 Hour
Page 1 of 1

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum

SSV Software Systems GmbH

Dünenweg 5
30419 Hannover

Fon: +49(0)511  ·  40 000-0
Fax: +49(0)511  ·  40 000-40

sales@ssv-embedded.de


Impressum    ·    Datenschutz    ·    AGB

© 2023 SSV SOFTWARE SYSTEMS GmbH. Alle Rechte vorbehalten.

ISO 9001:2015