Hinweis
Zur erleichterten Nutzung der URLEndpoints Schnittstelle liegt die JavaScript API vor. Diese ist gesondert dokumentiert und eignet sich für alle, die die URLEndpoints Schnittstelle per JavaScript (also z.B. per Anwendung im Browser/App) nutzen möchten.
1.Einleitung
HS-Objekte (HomeServer-Objekte) können über eine URL per HTTPS-Aufruf abgerufen bzw. verändert werden. Jedes HS-Objekt bekommt dazu einen eindeutigen Schlüssel (ID) im Experten zugewiesen.
Als Alternative zum Zugriff über HTTPS stehen die HS-Objekte ebenfalls über eine Verbindung per WebSocket (WS) zur Verfügung. Bei dieser Verbindung können auch alle HS-Objekte, außer Kameras, abonniert werden.
Als Alternative zum Zugriff über HTTPS stehen die HS-Objekte ebenfalls über eine Verbindung per WebSocket (WS) zur Verfügung. Bei dieser Verbindung können auch alle HS-Objekte, außer Kameras, abonniert werden.
2.Authentifizierung
Die Authentifizierung findet per HTTP-Authentifizierung (Basic Authentication) statt. Schlägt die Authentifizierung fehl, findet kein Aufbau einer stehenden Verbindung statt und der HS/FS antwortet mit Statuscode 403 (Forbidden). Ist die Anfrage nicht vollständig, antwortet der HS/FS mit Statuscode 400 (Bad Request).
Nach fehlgeschlagener Authentifizierung ist die IP-Adresse des Clients für 5 Sekunden gesperrt. In dieser Zeit liefert das Gerät auf Anfragen immer den Statuscode 503 zurück.
Nach fehlgeschlagener Authentifizierung ist die IP-Adresse des Clients für 5 Sekunden gesperrt. In dieser Zeit liefert das Gerät auf Anfragen immer den Statuscode 503 zurück.
3.Startverhalten
Wenn das Gerät startet, ist der HTTP-Server bereits vor Abschluss der Initialisierung verfügbar. In dieser Zeit liefert das Gerät den Statuscode 503 auf alle Anfragen. Zusätzlich enthält die Antwort den HTTP-Header "Retry-After". Der Client sollte dieses Feld auswerten und nach der angegebenen Zeit in Sekunden einen erneuten Versuch starten.
4.Voraussetzungen
Die Voraussetzungen für die Nutzung der URL-Endpoints sind:
- HomeServer/FacilityServer ab Firmware Version 4.7
- HS/FS-Experte ab Version 4.7
5.Überblick
5.1.Unterstützte HS-Objekte
5.2.Metadaten
Zu jedem HS-Objekt können Metadaten abgefragt werden. Diese enthalten Informationen zum jeweiligen HS-Objekt. Die verfügbaren Metadaten hängen vom jeweiligen Typ des HS-Objekts ab.
Folgende Metadaten stehen bei allen Objekten zur Verfügung:
Die interne ID ist im Experten nicht sicht- und änderbar. Bei der Metadatenabfrage wird diese mitgeliefert.
Weiterhin kann jedes HS-Objekt zusätzliche spezifische Metadaten besitzen.
Folgende Metadaten stehen bei allen Objekten zur Verfügung:
- ID: Innerhalb des Objekttyps eindeutige ID.
- interne ID: eindeutiger Schlüssel, wird im HS/FS-Experte automatisch vergeben.
- Bezeichnung: Die Bezeichnung des Objekts.
- Beschreibung (optional): Eine detaillierte Beschreibung des jeweiligen Objekts.
- Tags (optional): Eine durch Kommata getrennte Liste von Schlüsselwörtern.
Die interne ID ist im Experten nicht sicht- und änderbar. Bei der Metadatenabfrage wird diese mitgeliefert.
Weiterhin kann jedes HS-Objekt zusätzliche spezifische Metadaten besitzen.
5.3.Benutzerrechte
Der Zugriff auf die Endpunkte wird in der Benutzerverwaltung des HS/FS-Experte benutzerspezifisch konfiguriert. Die Rechte werden für "lesen" und "schreiben" separat vergeben. Es stehen jeweils 16 Gruppen zur Verfügung.
5.4.Objektschlüssel
Um identifizierbar zu sein, verfügt jedes HS-Objekt über zwei eindeutige Objektschlüssel (ID und interne ID). Die ID besteht aus einem Präfix, der den Objekttyp definiert, und einer innerhalb des Objekttyps eindeutigen Objekt-ID.
5.4.1.Präfix
Das Präfix für jeden Objekt-Typ (nicht änderbar) festgelegt. Er besteht aus einem Kürzel aus zwei Buchstaben.
5.4.2.ID
Die ID kann im HS/FS-Experte für das jeweilige Objekt festgelegt werden.
Groß-/Klein-Schreibung wird ignoriert.
Bei Verwendung als Objektschlüssel muss sie an den von einem '@'-Zeichen gefolgten Präfix angehängt werden.
Groß-/Klein-Schreibung wird ignoriert.
Bei Verwendung als Objektschlüssel muss sie an den von einem '@'-Zeichen gefolgten Präfix angehängt werden.
5.4.3.Interne ID
Die interne ID wird automatisch vergeben, ist eine Nummer und kann nicht geändert werden. Bei Verwendung als Objektschlüssel muss sie an den von einem ':' (Doppelpunkt) gefolgten Präfix angehängt werden.
5.4.4.Beispiel
Ein Kommunikationsobjekt (Präfix CO) mit der ID 1_1_1 und der internen ID 47 kann über folgende zwei Objektschlüssel angesprochen werden:
- CO@1_1_1 (Verwendung der ID)
- CO:47 (Verwendung der internen ID)
5.5.Statuscodes
In den Antwortpaketen vom HS/FS sind immer Statuscodes vorhanden:
Code | Bedeutung |
---|---|
0 | Alles in Ordnung. |
400 | Ungültige Anfrage (Forbidden). |
403 | Zugriff verweigert (Bad Request). |
404 | Das angefragte HS-Objekt existiert in dem aufgerufenen Kontext nicht. |
500 | Beim Erzeugen der Antwort ist im Server ein Fehler aufgetreten. |
901 | Der angegebene Schlüssel ist ungültig. |
902 | reserviert |
903 | Die Objekt-Parameter sind ungültig. |
904 | Das Objekt ist nicht abonniert. |
5.6.Zugriffsmöglichkeiten auf Endpoints
Um die HS-Objekte abzurufen und zu verändern bietet die Firmware zwei Möglichkeiten:
- HTTPS
Der Zugriff auf den HS/FS erfolgt per HTTPS durch das Aufrufen von URLs durch den Client. - WebSocket
Der Client öffnet einen WebSocket zum HS/FS und kann über diese stehende Verbindung kommunizieren.
Um die Nutzung des WebSocket in Anwendungen zu erleichtern, wird die URL-Endpoints JavaScript API bereitgestellt.
6.Zugriff über HTTPS
6.1.Authentifizierung
Die Authentifizierung kann per HTTP-Authentifizierung (Basic Authentication) oder Parameter stattfinden. Schlägt die Authentifizierung fehl, antwortet der HS/FS mit Statuscode 403 (Forbidden). Ist die Anfrage nicht vollständig antwortet der HS/FS mit Statuscode 400 (Bad Request).
6.1.1.HTTP-Authentifizierung (Basic Authentication)
Der Client sendet die Authentifizierung mit dem Authorization-Header in der Form Benutzername:Passwort Base64-codiert an den HS/FS. Der genaue Ablauf des Verfahrens kann dem RFC 2617 entnommen werden.
6.1.2.Authentifizierung über Parameter (Base64-codiert)
Dem Query String der URL wird der Parameter authorization angehängt. Dieser enthält die Authentifizierung in der Form Benutzername+Passwort Base64-codiert.
6.1.3.Beispiel - Authentifizierung über Parameter (Base64-codiert)
https://192.168.0.11/endpoints/call?key=CO@1_1_1&method=get&authorization=BASE64(USERNAME+PASSWORD) |
6.2.Kommunikation/Nachrichten zwischen HS/FS und Client
Beim Zugriff per HTTPS gibt es die folgenden Kommandos:
- call
Methoden-Aufruf eines HS-Objekts. - select
Abfrage einer Liste von HS-Objekten.
6.2.1.Methoden-Aufruf (call)
Aufruf einer Methode eines HS-Objekts.
6.2.1.1.Aufbau der HTTP-Anfrage an den HomeServer/FacilityServer
Der Pfad der URL lautet
Die HTTP-Anfragemethode ist GET.
/endpoints/call
. An diesen Pfad wird ein Query String angehängt. Der Query String enthält den Objektschlüssel des HS-Objekts (key). Außerdem noch den Namen (method) und ggf. die jeweiligen Parameter der aufgerufenen Methode.Die HTTP-Anfragemethode ist GET.
6.2.1.2.Beispiel - HTTP-Anfrage um den Wert eines Kommunikationsobjekts abzurufen
GET /endpoints/call?key=CO@1_1_1&method=get HTTP/1.1\r\n |
6.2.1.3.Aufbau der Antwort des HomeServer/FacilityServer
Der HS/FS antwortet mit einer JSON Struktur im Nachrichtenrumpf/Body.
Folgende Felder sind in der JSON Struktur enthalten:
Folgende Felder sind in der JSON Struktur enthalten:
- code: Statuscode.
- type: Typ der Anfrage. In diesem Fall immer call.
- request: Objekt mit Informationen zur Anfrage.
- key: Objektschlüssel des HS-Objekts.
- method: Name der aufgerufenen Methode.
- data (optional): Datenobjekt mit zurückgelieferten Werten der Methode. Ist nicht bei allen Methoden vorhanden.
6.2.2.Abfrage von Objektschlüsseln (select)
Abfrage einer Liste von HS-Objekten anhand bestimmter Merkmale.
6.2.2.1.Aufbau der HTTP-Anfrage an den HomeServer/FacilityServer
Der Pfad der URL lautet
/endpoints/select
. An diesen Pfad wird ein Query String angehängt. Der Query String enthält folgende Parameter:- key: Objektschlüssel durch den die Ergebnismenge eingegrenzt wird. Durch Angabe eines Sterns kann nach einer beliebigen ID gesucht werden:
- CO@* liefert alle K.-Objekte mit Schlüssel.
- CO:* liefert alle K.-Objekte.
- CO@abc* liefert alle K.-Objekte deren ID mit abc beginnt.
- tags (optional): Eine mit Leerzeichen (Achtung: muss als "+" codiert werden) getrennte Liste von Strings. Die Begriffe werden in den Tags des HS-Objekts gesucht. Der Suchbegriff muss übereinstimmen. Mehrere Begriffe werden UND-verknüpft.
- search (optional): Eine mit Leerzeichen (Achtung: muss als "+" codiert werden) getrennte Liste von Suchbegriffen. Die Suchbegriffe werden in der Bezeichnung und der Beschreibung eines Objekts gesucht. Mehrere Suchbegriffe werden UND-verknüpft.
- from (optional): Startposition in der Ergebnismenge (Standardwert: 0).
- count (optional): Anzahl an Elementen, die maximal ausgeliefert werden (Standardwert: 1000).
- meta (optional): Wenn true werden die Metadaten der HS-Objekte mit ausgeliefert (Standardwert: false).
6.2.2.2.Beispiel - Abfrage aller Kommunikationsobjekte mit zwei bestimmten Tags
GET /endpoints/select?key=CO:%2A&tags=BM+light HTTP/1.1\r\n |
6.2.2.3.Aufbau der Antwort des HomeServer/FacilityServer
Der HS/FS antwortet mit einer JSON Struktur im Nachrichtenrumpf/Body.
Folgende Felder sind in der JSON Struktur enthalten:
Folgende Felder sind in der JSON Struktur enthalten:
- code: Statuscode.
- type: Typ der Anfrage. In diesem Fall immer select.
- data: Objekt das die Daten der Antwort enthält.
- items: Array der HS-Objekte auf die die Anfrage zutrifft.
- key: Objektschlüssel des HS-Objekts.
- caption: Bezeichnung des HS-Objekts.
- meta (optional): Metadaten des HS-Objekts, wenn bei der Anfrage Metadaten angefordert wurden.
- code: Statuscode.
- items: Array der HS-Objekte auf die die Anfrage zutrifft.
7.Zugriff über Websocket
Über die stehende Websocket Verbindung werden die Daten im JSON Format ausgetauscht.
7.1.Verbindungsaufbau
Der Client baut eine WebSocket-Verbindung (Protokoll-Version 13/RFC 6455) zum Endpunkt /endpoints/ws auf.
7.2.Authentifizierung
Die Authentifizierung kann per HTTP-Authentifizierung (Basic Authentication) oder Parameter stattfinden. Schlägt die Authentifizierung fehl, findet kein Aufbau einer stehenden Verbindung statt und der HS/FS antwortet mit Statuscode 403 (Forbidden). Ist die Anfrage nicht vollständig antwortet der HS/FS mit Statuscode 400 (Bad Request).
7.2.1.HTTP-Authentifizierung (Basic Authentication)
Der Client sendet die Authentifizierung mit dem Authorization-Header in der Form Benutzername:Passwort Base64-codiert an den HS/FS. Der genaue Ablauf des Verfahrens kann dem RFC 2617 entnommen werden.
7.2.2.Beispiel - HTTP-Authentifizierung (Basic Authentication)
GET /endpoints/ws HTTP/1.1\r\n |
7.3.Kommunikation/Nachrichten zwischen HS/FS und Client
Beim Zugriff per Websocket gibt es die folgenden Kommandos und Ereignisse:
- Kommandos:
- call
Methoden-Aufruf eines HS-Objekts. - select
Abfrage einer Liste von HS-Objekten. - subscribe
Abonnieren von HS-Objekten. - unsubscribe
Auflösen eines Abonnements.
- call
- Ereignisse:
- push
Wird bei Änderung eines HS-Objekts ausgelöst, wenn dieses abonniert wurde.
- push
7.3.1.Methoden-Aufruf (call)
Aufruf einer Methode eines HS-Objekts.
7.3.1.1.Aufbau der Anfrage an den HomeServer/FacilityServer (JSON Struktur)
- type: Typ der Anfrage. In diesem Fall immer call.
- param: Objekt das die Parameter zum Aufruf der Methode enthält.
- key: Objektschlüssel des HS-Objekts das aufgerufen wird.
- method: Name der Methode die aufgerufen wird.
- context (optional): Der angegebene Kontext wird der Antwort hinzugefügt.
7.3.1.2.Beispiel - Wert eines K.-Objekts abfragen
{ |
7.3.1.3.Aufbau der Antwort vom HomeServer/FacilityServer (JSON Struktur)
- code: Statuscode.
- type: Typ der Anfrage. In diesem Fall immer call.
- request: Objekt mit Informationen zur Anfrage.
- key: Objektschlüssel des HS-Objekts.
- method: Name der aufgerufenen Methode.
- context (optional): Wenn in der Anfrage der Kontext angegeben wurde, wird er hier zurückgeliefert.
- data (optional): Datenobjekt mit zurückgelieferten Werten der Methode. Ist nicht bei allen Methoden vorhanden.
7.3.2.Abfrage von Objekt-Schlüsseln (select)
7.3.2.1.Aufbau der Anfrage an den HomeServer/FacilityServer (JSON Struktur)
- type: Typ der Anfrage. In diesem Fall immer select.
- param: Objekt, das die Parameter der Abfrage enthält.
- key: Objektschlüssel, durch den die Ergebnismenge eingegrenzt wird. Durch Angabe eines Sterns kann nach einer beliebigen ID gesucht werden:
- CO@* liefert alle K.-Objekte mit Schlüssel.
- CO:* liefert alle K.-Objekte.
- CO@abc* liefert alle K.-Objekte deren ID mit abc beginnt.
- tags (optional): Ein Array von Strings. Die Begriffe werden in den Tags des HS-Objekts gesucht. Der Suchbegriff muss übereinstimmen. Mehrere Begriffe werden UND-verknüpft.
- search (optional): Ein Array von Suchbegriffen. Die Suchbegriffe werden in der Bezeichnung und der Beschreibung eines Objekts gesucht. Mehrere Suchbegriffe werden UND-verknüpft.
- from (optional): Startposition in der Ergebnismenge (Standardwert: 0).
- count (optional): Anzahl an Elementen, die maximal ausgeliefert werden (Standardwert: 1000).
- meta (optional): Wenn true, werden die Metadaten der HS-Objekte mit ausgeliefert (Standardwert: false).
- context (optional): Der angegebene Kontext wird der Antwort hinzugefügt.
- key: Objektschlüssel, durch den die Ergebnismenge eingegrenzt wird. Durch Angabe eines Sterns kann nach einer beliebigen ID gesucht werden:
7.3.2.2.Beispiel - Abfrage aller Szenen mit dem in der Bezeichnung oder Beschreibung vorkommenden Suchbegriff "light"
{ |
7.3.2.3.Aufbau der Antwort vom HomeServer/FacilityServer (JSON Struktur)
- code: Statuscode.
- type: Typ der Anfrage. In diesem Fall immer select.
- request: Objekt mit Informationen zur Anfrage.
- context (optional): Wenn in der Anfrage der Kontext angegeben wurde, wird er hier zurückgeliefert.
- data: Objekt, das die Daten der Antwort enthält.
- items: Array der HS-Objekte, auf die die Anfrage zutrifft.
- key: Objektschlüssel des HS-Objekts.
- caption: Bezeichnung des HS-Objekts.
- meta (optional): Metadaten des HS-Objekts, wenn bei der Anfrage Metadaten angefordert wurden.
- code: Statuscode.
- items: Array der HS-Objekte, auf die die Anfrage zutrifft.
7.3.3.Abonnieren von HS-Objekten (subscribe)
7.3.3.1.Aufbau der Anfrage an den HomeServer/FacilityServer (JSON Struktur)
- type: Typ der Anfrage. In diesem Fall immer subscribe.
- param: Objekt, das die Parameter der Abfrage enthält.
- keys: Array von Objektschlüsseln aller zu abonnierenden HS-Objekte. Durch Angabe eines Sterns können mehrere HS-Objekte mit einem Objektschlüssel abonniert werden:
- CO@* abonniert alle K.-Objekte mit Schlüssel.
- CO:* abonniert alle K.-Objekte.
- CO@abc* abonniert alle K.-Objekte deren ID mit abc beginnt.
- SC:123 abonniert die Szene mit der internen ID 123
- context (optional): Der angegebene Kontext wird der Antwort hinzugefügt.
- keys: Array von Objektschlüsseln aller zu abonnierenden HS-Objekte. Durch Angabe eines Sterns können mehrere HS-Objekte mit einem Objektschlüssel abonniert werden:
7.3.3.2.Beispiel - Abonnieren
{ |
7.3.3.3.Aufbau der Antwort vom HomeServer/FacilityServer (JSON Struktur)
- code: Statuscode.
- type: Typ der Anfrage. In diesem Fall immer subscribe.
- request: Objekt mit Informationen zur Anfrage.
- context (optional): Wenn in der Anfrage der Kontext angegeben wurde, wird er hier zurückgeliefert.
- data: Objekt, das die Daten der Antwort enthält.
- items: Array von Antwortobjekten auf die Anfrage.
- key: Objektschlüssel des HS-Objekts.
- code: Statuscode.
- data (optional): Daten des abonnierten HS-Objekts. Abhängig vom Objekttyp.
- items: Array von Antwortobjekten auf die Anfrage.
7.3.3.4.Beispiel - Antwort auf die obige Anfrage
{ |
7.3.4.Abonnement kündigen (unsubscribe)
7.3.4.1.Aufbau der Anfrage an den HomeServer/FacilityServer (JSON Struktur)
- type: Typ der Anfrage. In diesem Fall immer unsubscribe.
- param: Objekt, das die Parameter der Abfrage enthält.
- keys: Array von Objektschlüsseln aller nicht weiter zu abonnierenden HS-Objekte. Durch Angabe eines Sterns kann bei mehreren HS-Objekten mit einem Objektschlüssel das Abonnement gekündigt werden:
- CO@* kündigt das Abonnement für alle K.-Objekte mit Schlüssel.
- CO:* kündigt das Abonnement für alle K.-Objekte.
- CO@abc* kündigt das Abonnement für alle K.-Objekte deren ID mit abc beginnt.
- SC:123 kündigt das Abonnement für die Szene mit der internen ID 123
- context (optional): Der angegebene Kontext wird der Antwort hinzugefügt.
- keys: Array von Objektschlüsseln aller nicht weiter zu abonnierenden HS-Objekte. Durch Angabe eines Sterns kann bei mehreren HS-Objekten mit einem Objektschlüssel das Abonnement gekündigt werden:
7.3.4.2.Beispiel - Kündigung eines Abonnements
{ |
7.3.4.3.Aufbau der Antwort vom HomeServer/FacilityServer (JSON Struktur)
- code: Statuscode.
- type: Typ der Anfrage. In diesem Fall immer unsubscribe.
- request: Objekt mit Informationen zur Anfrage.
- context (optional): Wenn in der Anfrage der Kontext angegeben wurde, wird er hier zurückgeliefert.
- data: Objekt, das die Daten der Antwort enthält.
- items: Array von Antwortobjekten auf die Anfrage.
- key: Objektschlüssel des HS-Objekts.
- code: Statuscode.
- items: Array von Antwortobjekten auf die Anfrage.
7.3.5.Wertänderung (push)
Wenn ein HS-Objekt abonniert wurde und sich das HS-Objekt während der Laufzeit des HS/FS ändert, wird ein Paket vom HomeServer/FacilityServer gesendet.
7.3.5.1.Aufbau des Pakets vom HomeServer/FacilityServer (JSON Struktur)
- code: Statuscode.
- type: Typ der Nachricht. In diesem Fall immer push.
- subscription: Objekt mit Informationen zum Abonnement.
- key: Objektschlüssel des abonnierten HS-Objekts.
- data: Daten des abonnierten HS-Objekts. Abhängig vom Objekttyp.
8.HS-Objekte
8.1.Datenarchive
Präfix: DA
8.1.1.Abonnement
8.1.1.2.Datenobjekt beim Hinzufügen eines Eintrags in das Archiv
Das Datenobjekt hat folgende Felder:
- first: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des ältesten Eintrags im Datenarchiv.
- last: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des jüngsten Eintrags im Datenarchiv.
- count: Anzahl der Einträge im Datenarchiv.
8.1.2.Methoden
8.1.2.1.Methode: meta
Abruf von Metadaten eines Datenarchivs.
8.1.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- keys: Array mit dem/den beiden Objektschlüssel(n) des Datenarchivs.
- caption: Bezeichnung des Datenarchivs.
- description: Beschreibung des Datenarchivs.
- tags: Array von Tags zum Datenarchiv.
- size: Maximale Größe des Ringpuffers des Datenarchivs.
- stat: Objekt, das Informationen über den Inhalt des Datenarchivs enthält. Es hat folgende Felder:
- first: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des ältesten Eintrags im Datenarchiv.
- last: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des jüngsten Eintrags im Datenarchiv.
- count: Anzahl der Einträge im Datenarchiv.
- cols: Array von Spaltenobjekten. Jedes Spaltenobjekt repräsentiert eine Spalte im Datenarchiv. Ein Spaltenobjekt hat folgende Felder:
- idx: Index der Spalte.
- key: Schlüssel der Spalte.
- text: Bezeichnung der Spalte.
8.1.2.2.Methode: get
Abruf von Daten eines Datenarchivs.
8.1.2.2.1.Parameter
- startat: Startzeitpunkt, ab dem die Daten geliefert werden sollen, als String. Das Format des Strings lautet YYMMDDHHMM. (YY = Jahr; MM = Monat; DD = Tag; HH = Stunden; MM = Minuten; z.B. 1607030805 = 3.7.2016 8:05 Uhr)
- cnt: Anzahl der Datenblöcke, die ausgeliefert werden sollen.
- size: Größe eines Datenblocks in Minuten. (Zum Beispiel mit den Parametern cnt = 24 und size = 60 würde die Antwort 24 Einträge über einen Gesamt-Zeitraum von 24 Stunden liefern.)
- cols: Array von Spalten, die abgerufen werden sollen. Die Spalte kann entweder über ihren Schlüssel oder ihren Index angegeben werden. Dem Index muss eine Raute (#) vorangestellt sein. (Beispielsweise liefert der Parameter cols = ["#1", "#2", "#4"] die Spalten 1, 2 und 4 des Archivs. cols = ["DEBIT", "CREDIT"] liefert die Spalten mit den Schlüsseln DEBIT und CREDIT.)
8.1.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- columns: Objekt, das alle angeforderten Spalten enthält. Als Felder dienen die Spaltenschlüssel.
- Spaltenschlüssel: Objekt, das Informationen zu einer Spalten enthält. Es hat folgende Felder:
- sum: Array von Summen aller Werte, die in dem jeweiligen (Block-)Zeitraum aufgezeichnet wurden.
- cnt: Array von den Anzahlen der Werte, aus denen die Summe gebildet wurde.
- min: Array von Minimalwerten, die in dem jeweiligen (Block-) Zeitraum aufgezeichnet wurden.
- max: Array von Maximalwerten, die in dem jeweiligen (Block-) Zeitraum aufgezeichnet wurden.
- error: Zeigt mit einem Wert größer Null an, dass bei der Berechnung der Archivdaten ein Fehler aufgetreten ist. Z.B. wenn für den angefragten Zeitraum keine Daten vorhanden sind.
- Spaltenschlüssel: Objekt, das Informationen zu einer Spalten enthält. Es hat folgende Felder:
8.1.2.2.3.Beispiel
Anfrage HTTPS: https://192.168.0.11/endpoints/call?key=DA@arch_temp&method=get&startat=1601010000&cnt=3&size=60&cols=CREDIT+DEBIT Anfrage WebSocket: { Antwort: { |
8.2.Kameraarchive
Präfix: CA
8.2.1.Abonnement
8.2.1.2.Datenobjekt beim Hinzufügen eines Eintrags in das Kameraarchiv
Das Datenobjekt hat folgende Felder:
- first:
Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des ältesten Bilds im Kameraarchiv. - last:
Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des jüngsten Bilds im Kameraarchiv. - count:
Anzahl der Bilder im Kameraarchiv. - pic_id:
ID des hinzugefügten Bilds. Wird für einen Abruf mittels get_picture oder get_picture_raw benötigt.
8.2.2.Methoden
8.2.2.1.Methode: meta
Abruf von Metadaten eines Kameraarchivs.
8.2.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- keys: Array mit dem/den beiden Objektschlüssel(n) des Kameraarchivs.
- caption: Bezeichnung des Kameraarchivs.
- description: Beschreibung des Kameraarchivs.
- tags: Array von Tags zum Kameraarchivs.
- size: Maximale Größe des Ringpuffers des Kameraarchivs.
- size_in_bytes: Maximale Größe des Kameraarchivs in Bytes.
- space: Größe der im Kameraarchiv archivierten Bilder in Bytes.
- stat: Objekt, das Informationen über den Inhalt des Kameraarchivs enthält. Es hat folgende Felder:
- first: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des ältesten Bilds im Kameraarchivs.
- last: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des jüngsten Bilds im Kameraarchivs.
- count: Anzahl der Bilder im Kameraarchiv.
8.2.2.2.Methode: get_list
Abruf der Einträge eines Kameraarchivs.
8.2.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- items: Array mit einem Objekt für jeden Eintrag im Kameraarchiv. Ein Objekt hat folgende Felder:
- ts: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des Eintrags.
- pic_id: ID des Bilds. Wird für einen Abruf mittels get_picture oder get_picture_raw benötigt
8.3.Kameras
Präfix: CP
8.3.2.Methoden
8.3.2.1.Methode: meta
Abruf von Metadaten einer Kamera.
8.3.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- keys: Array mit dem/den beiden Objektschlüssel(n) der Kamera.
- caption: Bezeichnung der Kamera.
- description: Beschreibung der Kamera.
- tags: Array von Tags zur Kamera.
- host: Adresse der Kamera.
- port: IP-Port der Kamera.
- path: Pfad unter der das Bild abgerufen wird.
- width: Im HS/FS-Experte definierte Breite des Bilds.
- height: Im HS/FS-Experte definierte Höhe des Bilds.
8.4.Kommunikationsobjekte
Präfix: CO
8.4.1.Abonnement
8.4.2.Methoden
8.4.2.1.Methode: meta
Abruf von Metadaten eines K.-Objekts.
8.4.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- keys: Array mit dem/den beiden Objektschlüssel(n) des K.-Objekts.
- caption: Bezeichnung des K.-Objekts.
- description: Beschreibung des K.-Objekts.
- tags: Array von Tags zum K.-Objekts.
- format: Datenformat des K-Objekts als ID. Folgende Datenformate sind möglich:
ID Datenformat 1 1 Bit 2 8 Bit (0..100) 3 8 Bit (RTR) 4 16 Bit (Gleitkomma) 5 2 Bit 9 4 Byte 10 8 Bit (unsigned) oder Dali 11 8 Bit (signed) 12 16 Bit (unsigned) 13 16 Bit (signed) 14 32 Bit (unsigned) oder Sammelrückmeldeobjekt 15 32 Bit (signed) 16 4 Bit 17 3 Byte 20 3 Byte (Zeit) 21 3 Byte (Datum) 22 14 Byte (String) - minValue: Minimal zulässiger Wert. Hat den Wert 0, wenn Format 14 Byte ist.
- maxValue: Maximal zulässiger Wert. Hat den Wert 0, wenn Format 14 Byte ist.
- list: Array von Werten. Mit den Methoden list_prev und list_next kann das K.-Objekt auf die einzelnen Werte gesetzt werden. Nicht gesetzt, wenn das Format 14 Byte ist.
- offset: Wert zur schrittweisen Veränderung des Werts mit Hilfe der Methoden offset_plus und offset_minus. Hat den Wert 0, wenn Format 14 Byte ist.
- grpadr: Gruppenadresse (z.B. 1/1/1) entsprechend der Definition im HS/FS-Experte.
8.4.2.2.Methode: get
Abruf des aktuellen Werts eines K.-Objekts.
8.4.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- value: Wert des K.-Objekts. Abhängig vom Typ des K.-Objekts ist dies ein im Format Base64 kodierter String (beim Typ 14-Byte Text) oder eine Zahl.
8.4.2.2.3.Beispiel - Abruf eines K.-Objekts vom Typ 14-Byte Text. Der aktuelle Wert (value) ist "Abc123XYZ".
Anfrage HTTPS: https://192.168.0.11/endpoints/call?key=CO@text&method=get Anfrage WebSocket: { Antwort: { |
8.4.2.3.Methode: set
Setzen des Werts eines K.-Objekts.
8.4.2.3.1.Parameter
- value: Wert, auf den das K.-Objekt gesetzt wird. Abhängig vom Typ des K.-Objekts muss dies ein String (beim Typ 14-Byte Text) oder eine Zahl sein.
- encoding (optional): Hat das K.-Objekt den Typ 14-Byte Text, kann hier angegeben werden, wie der übermittelte String (Parameter value) kodiert wird. Fehlt dieser Parameter, muss der String im Format Base64 kodiert sein. Alternativ kann auch als Kodierung ascii gewählt werden.
8.4.2.4.Methode: toggle
Umschalten des Werts eines K.-Objekts zwischen 0 und dem angegeben Wert. Diese Methode ist nicht zulässig bei K.-Objekten vom Typ 14 Byte (String).
8.4.2.5.Methode: add
Erhöhen des Werts eines K.-Objekts um den angegeben Wert. Diese Methode ist nicht zulässig bei K.-Objekten vom Typ 14 Byte (String).
8.4.2.6.Methode: offset_plus
Erhöhen des Werts eines K.-Objekts um die jeweilige Schrittgröße. Diese Methode ist nicht zulässig bei K.-Objekten vom Typ 14 Byte (String).
8.4.2.7.Methode: offset_minus
Vermindern des Werts eines K.-Objekts um die jeweilige Schrittgröße. Diese Methode ist nicht zulässig bei K.-Objekten vom Typ 14 Byte (String).
8.4.2.8.Methode: list_next
Den Wert des K-Objekts auf den nächst-größeren Wert in der Liste setzen. Diese Methode ist nicht zulässig bei K.-Objekten vom Typ 14 Byte (String).
8.5.Meldungsarchive
Präfix: MA
8.5.1.Abonnement
8.5.1.2.Datenobjekt beim Hinzufügen eines Eintrags in das Archiv
Das Datenobjekt hat folgendes Feld:
- first: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des ältesten Eintrags im Meldungsarchiv.
- last: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des jüngsten Eintrags im Meldungsarchiv.
- count: Anzahl der Einträge im Meldungsarchiv.
- token: Im Experte definiertes Kürzel des hinzugefügten Eintrags.
- text: Im Experte definierter Text des hinzugefügten Eintrags.
8.5.2.Methoden
8.5.2.1.Methode: meta
Abruf von Metadaten eines Meldungsarchivs.
8.5.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- keys: Array mit dem/den beiden Objektschlüssel(n) des Datenarchivs.
- caption: Bezeichnung des Datenarchivs.
- description: Beschreibung des Datenarchivs.
- tags: Array von Tags zum Datenarchiv.
- size: Maximale Größe des Ringpuffers des Datenarchivs.
- tokens: Array aller möglichen Kürzel (Meldungen).
8.5.2.2.Methode: get
Abruf von Meldungen eines Meldungsarchivs.
8.5.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- items: Array mit Objekten. Ein Objekt entspricht einem Eintrag im Meldungsarchiv. Die Anzahl der Einträge ist abhängig vom Parameter count. Ein Objekt hat folgende Felder:
- ts: Unix-Zeitstempel des Eintrags (in Sekunden, Millisekunden als Kommawert).
- token: Im Experte definiertes Kürzel des Eintrags.
- text: Im Experte definierter Text des Eintrags.
8.6.Sequenzen
Präfix: SQ
8.6.2.Methoden
8.6.2.1.Methode: meta
Abruf von Metadaten einer Sequenz.
8.6.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- keys: Array mit dem/den beiden Objektschlüssel(n) der Sequenz.
- caption: Bezeichnung der Sequenz.
- description: Beschreibung der Sequenz.
- tags: Array von Tags zur Sequenz.
- restart: Wenn true, kann die Sequenz während des Ablaufs neu gestartet werden.
8.7.Szenen
Präfix: SC
8.7.2.Methoden
8.7.2.1.Methode: meta
Abruf von Metadaten einer Szene.
8.7.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- keys: Array mit dem/den beiden Objektschlüssel(n) der Szene.
- caption: Bezeichnung der Szene.
- description: Beschreibung der Szene.
- tags: Array von Tags zur Szene.
- actors: Array von Objektschlüsseln der in der Szene enthaltenen K.-Objekte.
8.7.2.2.Methode: get_items
Liefert alle in einer Szene enthaltenen Aktoren.
8.7.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS ist ein Array von Aktorobjekten. Jedes dieser Objekte hat folgende Felder:
- key: Objektschlüssel des verwendeten K.-Objekts.
- value: In der Szene gespeicherter Wert.
- learn: true, wenn der Wert durch Lernen verändert werden kann.
8.7.2.5.Methode: offset_plus
Erhöhen der Werte aller in einer Szene vorhandenen K.-Objekte um die jeweilige Schrittgröße.
8.7.2.6.Methode: offset_minus
Vermindern der Werte aller in einer Szene vorhandenen K.-Objekte um die jeweilige Schrittgröße.
8.8.Universal-Zeitschaltuhren
Präfix: TI
8.8.1.Abonnement
8.8.1.2.Datenobjekt wenn die Zeitschaltuhr verändert wurde
Das Datenobjekt hat folgende Felder:
- ts: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) der Änderung.
- active: true, wenn die Zeitschaltuhr aktiv ist, ansonsten false.
- modified: true, wenn wenn die Zeitschaltuhr verändert (d.h. ein Ereignis angelegt, geändert oder gelöscht) wurde.
8.8.2.Methoden
8.8.2.1.Methode: meta
Abruf von Metadaten einer Universal-Zeitschaltuhr.
8.8.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- keys: Array mit dem/den beiden Objektschlüssel(n) der Zeitschaltuhr.
- caption: Bezeichnung der Zeitschaltuhr.
- description: Beschreibung der Zeitschaltuhr.
- tags: Array von Tags zur Zeitschaltuhr.
- actions: Array der in der Zeitschaltuhr hinterlegten Aktionen. Jede Aktion wird durch ein Objekt repräsentiert. Dieses hat folgende Felder:
- id: ID der Aktion.
- text: Bezeichnung der Aktion
- commands: Anzahl der hinterlegten Befehle.
8.8.2.5.Methode: get_events
Liefert eine Auflistung aller Ereignisse einer Universal-Zeitschaltuhr.
8.8.2.5.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- items: Array mit Ereignisobjekten.
8.8.2.6.Methode: add_event
Fügt einer Zeitschaltuhr ein Ereignis hinzu.
8.8.2.6.1.Parameter
Diese Methode benötigt als Parameter die Felder eines Ereignisobjekts.
8.8.2.7.Methode: set_event
Modifiziert ein bestehendes Ereignis.
8.8.2.7.1.Parameter
Diese Methode benötigt als Parameter die Felder eines Ereignisobjekts. Außerdem hat sie noch folgenden Parameter:
- event_id: ID (Nummer) des Ereignisses.
8.8.2.8.Methode: del_event
Löscht ein bestehendes Ereignis.
8.8.2.8.1.Parameter
- event_id: ID (Nummer) des Ereignisses.
8.8.2.9.Methode: simulate
Simuliert die Berechnung der Schaltzeitpunkte einer Universal-Zeitschaltuhr für die nächsten Tage. Diese Funktion steht nur für URL-Endpoints zur Verfügung.
8.8.2.9.1.Parameter
- days: Anzahl der Tage, die berechnet werden sollen. Dies können maximal 28 Tage sein.
8.8.2.9.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- items: Array mit den berechneten Schaltzeitpunkten für die angegebenen Tage. Ein Schaltzeitpunktobjekt hat folgende Felder:
- event_id: ID (Nummer) des Ereignisses.
- ts: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert), an dem das Ereignis ausgelöst wird (Uhrzeit HS/FS). Der Zeitpunkt kann durch das Feld random noch beeinflusst werden.
- random: Zeitbereich in Minuten, in dem das Ereignis ausgelöst werden kann. Der Zeitpunkt liegt dann im Bereich zwischen ts - (random * 60) und ts + (random * 60).
8.8.3.Ereignisobjekt
Das Ereignisobjekt hat folgende Felder:
- date_type: Gibt an, ob das Datum des Ereignisses durch einen Wochentag (date_type=1), einen Zeitraum (date_type=2) oder ein Einzeldatum (date_type=3) bestimmt wird.
- weekdays: Array mit aktivierten Wochentagen. (0=Montag, 1=Dienstag,..., 6=Sonntag)
Ist nur vorhanden, wenn date_type=1 (Wochentag) ist. - date1: Erster Tag, an dem das Ereignis ausgelöst werden soll, als String. Das Format des Strings lautet YYMMDD (YY = Jahr; MM = Monat; DD = Tag; z.B. 160703 = 3.7.2016)
Ist nur vorhanden, wenn date_type=2 (Zeitraum) ist. - date2: Letzter Tag, an dem das Ereignis ausgelöst werden soll, als String. Das Format des Strings lautet YYMMDD (YY = Jahr; MM = Monat; DD = Tag; z.B. 160703 = 3.7.2016)
Ist nur vorhanden, wenn date_type=2 (Zeitraum) ist. - day: Tag (1-31), an dem das Ereignis ausgelöst werden soll. Ist das Feld nicht vorhanden, wird an jedem Tag ausgelöst, an dem der Monat und das Jahr übereinstimmen.
Ist nur vorhanden, wenn date_type=3 (Einzeldatum) ist. - month: Monat (1-12), in dem das Ereignis ausgelöst werden soll. Ist das Feld nicht vorhanden, wird in jedem Monat ausgelöst, in dem der Tag und das Jahr übereinstimmen.
Ist nur vorhanden, wenn date_type=3 (Einzeldatum) ist. - year: Jahr (0-99 entspricht 2000 bis 2099), in dem das Ereignis ausgelöst werden soll. Ist das Feld nicht vorhanden, wird in jedem Jahr ausgelöst, in dem der Tag und und der Monat übereinstimmen.
Ist nur vorhanden, wenn date_type=3 (Einzeldatum) ist. - time_type: Gibt an, ob das Ereignis zu einer bestimmten Uhrzeit (time_type=1) oder abhängig von Sonnenaufgang (time_type=2) oder Sonnenuntergang (time_type=3) ausgelöst werden soll.
- time: Uhrzeit als als String. Das Format des Strings lautet HHMM. (HH = Stunden; MM = Minuten; z.B. 0700 = 7:00 Uhr)
Ist nur vorhanden, wenn time_type=1 (Uhrzeit) ist. - offset: Anzahl in Minuten, in dem das Ereignis vor (negativer Wert), oder nach dem Sonnenaufgang/Sonnenuntergang ausgelöst werden soll.
Ist nur vorhanden wenn time_type=2 (Sonnenaufgang) oder time_type=3 (Sonnenuntergang) ist. - random: Max. Anzahl in Minuten, die dem Auslösezeitpunkt des Ereignisses zufällig zugefügt oder abgezogen werden.
- filter: Bestimmt, ob ein Ereignis immer (filter=0), nur an normalen Tagen (kein Feiertag, kein Urlaubstag) (filter=1), nur an Feiertagen (filter=2), nur an Urlaubstagen (filter=3) oder nie (filter=4) ausgelöst werden soll.
- action: ID der Aktion, die ausgelöst werden soll. Alle in der Zeitschaltuhr definierten Aktionen werden beim Abruf der Metadaten übermittelt.
8.8.3.1.Beispiele
Der Zeitschaltuhr mit dem Objektschlüssel TI@UZSU1 wird ein Ereignis hinzugefügt. Dieses führt die Aktion mit der ID 1 an Werktagen (Montag-Freitag), wenn kein Feiertag oder Urlaubstag ist, um 12:00 Uhr aus:
Der Zeitschaltuhr mit dem Objektschlüssel TI@UZSU1 wird ein Ereignis hinzugefügt. Dieses führt die Aktion mit der ID 1 jeden Samstag und Sonntag zwischen 9:30 Uhr und 10:30 Uhr aus:
Der Zeitschaltuhr mit dem Objektschlüssel TI@UZSU1 wird ein Ereignis hinzugefügt. Dieses führt die Aktion mit der ID 1 jeden Tag im April 2016, jeweils eine Stunde nach Sonnenaufgang, aus:
{ |
Der Zeitschaltuhr mit dem Objektschlüssel TI@UZSU1 wird ein Ereignis hinzugefügt. Dieses führt die Aktion mit der ID 1 jeden Samstag und Sonntag zwischen 9:30 Uhr und 10:30 Uhr aus:
{ |
Der Zeitschaltuhr mit dem Objektschlüssel TI@UZSU1 wird ein Ereignis hinzugefügt. Dieses führt die Aktion mit der ID 1 jeden Tag im April 2016, jeweils eine Stunde nach Sonnenaufgang, aus:
{ |
8.9.Urlaubskalender
Präfix: VC
8.9.1.Abonnement
8.9.1.1.Datenobjekt beim Abonnieren oder wenn der Kalender geändert wird
Das Datenobjekt hat folgende Felder:
- active: true, wenn der Kalender aktiviert ist, ansonsten false.
- from: Start des Zeitraums als String. Das Format des Strings lautet YYYYMMDD (YYYY = Jahr; MM = Monat; DD = Tag; z.B. 20160703 = 3.7.2016).
- to: Ende des Zeitraums als String. Das Format des Strings lautet YYYYMMDD (YYYY = Jahr; MM = Monat; DD = Tag; z.B. 20160703 = 3.7.2016).
8.9.2.Methoden
8.9.2.1.Methode: meta
Abruf von Metadaten eines Urlaubskalenders.
8.9.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgendes Felder:
- keys: Array mit dem/den beiden Objektschlüssel(n) des Urlaubskalenders.
- caption: Bezeichnung des Urlaubskalenders.
- description: Beschreibung des Urlaubskalenders.
- tags: Array von Tags zum Urlaubskalender.
8.9.2.2.Methode: get
Liefert den aktuellen Zustand eines Urlaubskalenders.
8.9.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
- active: true, wenn der Kalender aktiviert ist, ansonsten false.
- from: Start des Zeitraums als String. Das Format des Strings lautet YYYYMMDD (YYYY = Jahr; MM = Monat; DD = Tag; z.B. 20160703 = 3.7.2016).
- to: Ende des Zeitraums als String. Das Format des Strings lautet YYYYMMDD (YYYY = Jahr; MM = Monat; DD = Tag; z.B. 20160703 = 3.7.2016).
8.9.2.3.Methode: set
Setzen eines Urlaubskalenders.
8.9.2.3.1.Parameter
- active: true aktiviert den Kalender. false deaktiviert den Kalender.
- from: Start des Zeitraums als String. Das Format des Strings lautet YYYYMMDD (YYYY = Jahr; MM = Monat; DD = Tag; z.B. 20160703 = 3.7.2016).
- to: Ende des Zeitraums als String. Das Format des Strings lautet YYYYMMDD (YYYY = Jahr; MM = Monat; DD = Tag; z.B. 20160703 = 3.7.2016).