REST Service

Ab Version 1.4 steht für das Smart Building Automation System eine REST API unter "http://[Smart_Building_Automation_IP]/api" zur Verfügung. Für die Verwendung der REST API sind folgende Schritte erforderlich.

Vorbereitung

  • In der Benutzeroberfläche des Smart Building Automation Systems zu „Alle Apps“ – „Einstellungen“ – „Rest Service“ navigieren.
  • Die Zugangsdaten eingeben und daraus einen Hash erzeugen. Den erzeugten Hash notieren bzw. speichern, da dieser für den nächsten Schritt benötigt wird.

Authentifizierung

Für Anfragen an die REST API ist eine Authentifizierung erforderlich. Hierfür wird ein Token verwendet, der nach einer erfolgreichen Anmeldung über die REST API bereitgestellt wird.

  • Einen POST-Request an die Adresse "http://[Smart_Building_Automation_IP]/login" mit folgenden Parametern im Header senden:
    • x-elocs-username: [Benutzername]
    • x-elocs-password: [Hash]

Als Antwort wird der Token x-elocs-token zurückgegeben und automatisch als Cookie gesetzt. Dieser wird für die Authentifizierung aller weiteren Anfragen verwendet.

Abhängig davon, von wo die Anfragen an das Smart Building Automation System gesendet werden, wird der gesetzte Cookie automatisch verwendet. Andernfalls muss der Token bei jeder Anfrage im Header mitgesendet werden: Cookie:token=[Token].

Anfragen

Die Smart Building Automation REST API bietet sowohl die Möglichkeit, den aktuellen Status der einzelnen Funktionen im System abzufragen, als auch diese zu steuern. Dazu stehen folgende Anfragen zu Verfügung:

GET: apps
"http://[Smart_Building_Automation_IP]/api/apps"
Liefert eine Liste aller Apps.

GET: apps/{fullName}
Liefert detaillierte Informationen über die angefragte App.

GET: instances
Liefert eine Liste aller Instanzen.

GET: instances/{instanceId}
Liefert detaillierte Informationen über die angefragte Instanz.

GET: instances/{instanceId}/{action}
Liefert den aktuellen Wert der angefragten Eigenschaft einer spezifischen Instanz. Zu Beispiel den aktuellen Status eines Lichts.

POST: instances/{instanceId}/{action}
Ruft eine Methode der spezifischen Instanz auf.

Unter "http://[Smart_Building_Automation_IP]/api" steht eine Testseite für die REST API zur Verfügung, auf der alle aufgelisteten Anfragen ausprobiert werden können.

Beispiele

Im folgenden Beispiel wird ein Licht über die REST API geschaltet.

Zunächst müssen die erforderlichen Schritte zur Authentifizierung durchgeführt werden (siehe Abschnitte „Vorbereitung“ und „Authentifizierung“). Mit dem dabei erhaltenen Token können anschließend die erforderlichen Anfragen und Befehle gesendet werden.

Zuerst wird eine GET-Anfrage an "http://[Smart_Building_Automation_IP]/api/instances" gesendet. Als Antwort wird eine Liste aller aktuell im Smart Building Automation System vorhandenen Instanzen zurückgegeben.

{
  "statusCode": 200,
  "statusText": "success",
  "data": [
    {
      "ID": "SC1_M04.Light1",
      "ClassName": "SmartCOM.Light.Light",
      "Name": "Arbeitslicht",
      "Group": "AreaOutdoor"
    },
    ...
  ]
}

Da ein Licht geschaltet werden soll, wird hier das „Arbeitslicht“ ausgewählt. Über den „ClassName“ „SmartCOM.Light.Light“ kann anschließend eine GET-Anfrage an "http://[Smart_Building_Automation_IP]/api/apps/SmartCOM.Light.Light" gesendet werden, um die verfügbaren Methoden und Eigenschaften abzurufen.

{
  "statusCode": 200,
  "statusText": "success",
  "data": {
    "methods": [
      {
        "parameter": [],
        "name": "SwitchOn",
        "type": 0,
        "derived": false,
        "tags": [
          "linkable"
        ],
        "returnType": "void",
        "description": "Einschalten",
        "isStatic": false
      },
      ...
    ],
    "properties": [
      {
        "name": "IsOn",
        "type": "boolean",
        "remark": "Licht eingeschaltet",
        "declaration": "2",
        "derived": true,
        "parameter": false,
        "tags": [
          "linkable"
        ],
        "isStatic": false
      },
      ...
    ],
    "fullName": "SmartCOM.Light.Light",
    "displayName": "Licht",
    "autoStart": false
  }
}

Anschließend wird eine POST-Anfrage an "http://[Smart_Building_Automation_IP]/api/instances/SC1_M04.Light1/SwitchOn" mit folgenden Parametern im Header gesendet:

  • instanceId: SC1_M04.Light1
  • action: SwitchOn
  • body: [ ]

Dadurch wird die entsprechende Methode des Lichts aufgerufen und das Licht eingeschaltet. Der aktuelle Status kann über eine GET-Anfrage an "http://[Smart_Building_Automation_IP]/api/instances/SC1_M04.Light1/IsOn" abgefragt werden. Als Antwort wird der aktuelle Status zurückgegeben, in diesem Fall 'true'.

{
  "statusCode": 200,
  "statusText": "success",
  "data": true
}