SEM-API
SEM-API.
Durch die SEM-API erhalten Sie Zugriff auf den SEM und können so z.B. die Geräte, die im SEM eingebunden sind, über ein externes System steuern. Es gibt dabei je nach Softwarestand verschiedene Versionen der SEM-API. Die Dokumentation wird dynamisch mit Swagger generiert. Um auf die interaktive Dokumentation Zugriff zu erhalten, ist ein SEM erforderlich.
Wie komme ich zur SEM-API Dokumentation?
Loggen Sie sich am Webinterface des SEM ein und gehen Sie auf den Reiter „API“.
Vorbereitungen
Um die Kommunikation gegenüber dem SEM zu authentifizieren, muss zu allererst ein apiKey angefordert werden. Dieser apiKey wird dann in der weiteren Kommunikation dazu verwendet, die API-requests zu signieren.
Um den apiKey anfordern zu können, müssen Sie den SEM in den Coupling Modus für externe Geräte setzen. Anschließend können Sie den apiKey anfordern.
1. Rufen Sie die „Allgemeinen Einstellungen“ am SEM auf.
2. Wählen Sie den Menüpunkt „Externe Systeme“ aus.
3. Wählen Sie „Neues System hinzufügen“.
4. Der Coupling Modus ist nun aktiv.
apiKey anfordern per Swagger
1. Rufen Sie das Webinterface Ihres SEM auf.
2. Wählen Sie den Bereich „API“ aus und öffnen Sie die interaktive Dokumentation Ihres SEM.
3. Öffnen Sie den Reiter „Coupling“ in der interaktiven Dokumentation.
4. Wählen Sie „/coupling/apiKey/request“ aus.
5. Wählen sie einen Namen für das externe Gerät aus und fügen diesen in den Request ein.
Syntax: {
"clientName": "<device Name>"
}
Info: Der „device Name“ kann nachträglich am SEM geändert werden.
6. Drücken Sie nun auf „Try it out!“
apiKey auslesen per Swagger
7. Im „Response Body“ sehen Sie den gerade erzeugten apiKey.
8. Speichern Sie den apiKey für die spätere Verwendung.
Es ist nicht möglich den apiKey später erneut auszulesen!
Um die angeschlossen Geräte per API ansteuern zu können, wird die deviceID der Geräte benötigt. Diese kann per Swagger über den Reiter „Devices“ („get devices“) abgefragt werden.
Schaltgerät steuern per Swagger
Um z.B. ein Schaltgerät zusteuern benötigen Sie zuerst die deviceID des Smart Plugs und den apiKey.
1. Öffnen Sie den Reiter „Devices„.
2. Wählen Sie „/devices/{deviceId}/actions/{actionLabel}“ aus.
3. Wählen Sie folgende Werte für die Parameter:
deviceID |
<DeviceID> |
actionLabel |
output |
DtoActionTriggerV1 |
{
"value": 255
}
|
X-Api-Key oder apiKey |
<apiKey> |
4. Drücken Sie auf „Try it out!“
1. Öffnen Sie den Reiter „Devices„.
2. Wählen Sie „/devices/{deviceId}/actions/{actionLabel}“ aus.
3. Wählen Sie folgende Werte für die Parameter:
deviceID |
<DeviceID> |
actionLabel |
output |
DtoActionTriggerV1 |
{
"value": 0
}
|
X-Api-Key oder apiKey |
<apiKey> |
4. Drücken Sie auf „Try it out!“
1. Öffnen Sie den Reiter „Data„.
2. Wählen Sie „/devices/{deviceId}/data/{dataName}“ aus.
3. Wählen Sie folgende Werte für die Parameter:
deviceID |
<DeviceID> |
dataName |
output |
X-Api-Key oder apiKey |
<apiKey> |
4. Drücken Sie auf „Try it out!“
Response
5. In der „Response“ befindet sich der Schaltzustand des Schaltgeräts:
value |
Schaltzustand |
0 |
Schaltgerät ist ausgeschaltet |
255 |
Schaltgerät ist eingeschaltet |
1. Öffnen Sie den Reiter „Data„.
2. Wählen Sie „/devices/{deviceId}/data/{dataName}“ aus.
3. Wählen Sie folgende Werte für die Parameter:
deviceID |
<DeviceID> |
dataName |
power |
X-Api-Key oder apiKey |
<apiKey> |
4. Drücken Sie auf „Try it out!“
Response
5. In der „Response“ befindet sich die Leistung des Schaltgeräts:
value |
|
x |
Leistung in W |
1. Öffnen Sie den Reiter „Data„.
2. Wählen Sie „/devices/{deviceId}/data/{dataName}“ aus.
3. Wählen Sie folgende Werte für die Parameter:
deviceID |
<DeviceID> |
dataName |
kWh |
X-Api-Key oder apiKey |
<apiKey> |
4. Drücken Sie auf „Try it out!“
Response
5. In der „Response“ befindet sich der Verbrauch in kWh des Schaltgeräts:
value |
|
x |
Verbrauch in kWh |
ALLGEMEINE INFORMATIONEN.
FAQ/HÄUFIGE FRAGEN:
In den Systemeinstellungen des SEM können Sie unter dem Menüpunkt „Schutz“ den Unterpunkt „Unsichere SEM-API-Zugriffe“ einschalten. Daraufhin können Systeme eine unverschlüsselte Verbindung über „http“ mit dem SEM aufbauen.
Wir empfehlen, grundsätzlich die sichere Verbindung (https) eingestellt zu lassen, um Daten verschlüsselt zu übertragen!