HTTP API Dokumentation Version 1.1.069

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

HTTP API Dokumentation Version 1.1.069

Inhaltsverzeichnis 1

Allgemeine Informationen ..................................................................................................................................................... 4

1.1

HTTP API ........................................................................................................................................................4

1.2

API-Key ...........................................................................................................................................................4

1.3

Ausgabeformat .............................................................................................................................................4

1.4

Wichtige Daten ..............................................................................................................................................4

1.5

Systemmanager ............................................................................................................................................5

1.5.1

Systemmanager öffnen ...........................................................................................................................5

1.6

Wiedergabelisten vs. Warteschlangen.......................................................................................................5

1.7

Unterstützung ...............................................................................................................................................5

2

Funktionsbeschreibung.......................................................................................................................................................... 5

3

Grundfunktionalität ................................................................................................................................................................ 6

3.1

Räume ............................................................................................................................................................6

3.2

Zonen .............................................................................................................................................................6

3.3

Räume und Zonen ........................................................................................................................................6

3.4

Haussperre ....................................................................................................................................................6

3.4.1

Haussperre über die API .........................................................................................................................6

4

Web Service Location .............................................................................................................................................................. 7

5

API Antwort Format ................................................................................................................................................................ 7

5.1 6

7

API Antwort Codes .................................................................................................................................................................. 7

6.1.1

Antwort Code bei erfolgreicher Anfrage ...............................................................................................7

6.1.2

Fehler IDs...................................................................................................................................................7

Allgemeine Abfragen .............................................................................................................................................................. 8

7.1

8

Beispiel ...........................................................................................................................................................7

Räume Abfragen ...........................................................................................................................................8

7.1.1

über Systemmanager ..............................................................................................................................8

7.1.2

über API .....................................................................................................................................................8

7.2

Zonen Abfragen ............................................................................................................................................9

7.3

Player Status Abfragen ............................................................................................................................. 10

7.4

Zonen Abfrage und Player Status kombiniert ....................................................................................... 11

Zone steuern ......................................................................................................................................................................... 12

8.1

Wiedergabe stoppen ................................................................................................................................. 12

8.2

Wiedergabe starten ................................................................................................................................... 12

8.3

vorheriger Titel .......................................................................................................................................... 13

8.4

nächster Titel.............................................................................................................................................. 13

8.5

Zufallswiedergabe ..................................................................................................................................... 14

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 2 von 23

HTTP API Dokumentation Version 1.1.069 8.6

Endloswiedergabe ..................................................................................................................................... 14

8.7

Lautstärke erhöhen ................................................................................................................................... 15

8.8

Lautstärke verringern ............................................................................................................................... 15

8.9

Lautstärke einstellen ................................................................................................................................. 16

8.10

alle Zonen stoppen.................................................................................................................................... 16

9

Räume steuern ...................................................................................................................................................................... 17

9.1

Lautstärke erhöhen ................................................................................................................................... 17

9.2

Lautstärke verringern ............................................................................................................................... 17

9.3

Lautstärke einstellen ................................................................................................................................. 18

9.4

Raum stoppen............................................................................................................................................ 18

10

Raum / Zonen Zuordnung ................................................................................................................................................... 19

10.1

Raum zu einer Zone hinzufügen ............................................................................................................. 19

10.2

Raum aus einer Zone entfernen ............................................................................................................. 19

11

Musik Wiedergabe ................................................................................................................................................................ 20

11.1

Musik in der Zone abspielen .................................................................................................................... 20

11.2

Musik in einem Raum abspielen ............................................................................................................. 21

11.3

Fehlerbehandlung ..................................................................................................................................... 22

11.4

Warteschlange einer Zone leeren ........................................................................................................... 22

11.5

Haussperre aktivieren............................................................................................................................... 23

11.6

Haussperre deaktivieren .......................................................................................................................... 23

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 3 von 23

HTTP API Dokumentation Version 1.1.069

1 Allgemeine Informationen 1.1 HTTP API Die HTTP API (application programming interface) von veoovibes ermöglicht einen automatisierten, maschinengeeigneten Zugriff zur Steuerung von veoovibes. Der Zugriff erfolgt via HTTP, die Antworten werden als JSON, XML oder PHP zurück geliefert.

1.2 API-Key Jede veoovibes Installation verfügt über einen eigenen einzigartigen API-Key. Dieser wird benötigt um die jeweilige veoovibes Installation zu steuern. Der API-Key muss bei allen Abfragen im Parameter „api_key“ übermittelt werden. Geschieht dieses nicht oder wird ein ungültiger API-Key verwendet, wird der Befehl nicht ausgeführt und die API meldet den Fehlercode “20” (siehe API Antwort Codes).

1.3 Ausgabeformat Alle Anfragen und Rückgabewerte sind UTF-8 kodiert. Standardmäßig erfolgt die Rückgabe der API-Schnittstelle im JSON-Format. Das Format kann jedoch geändert werden (siehe API Antwort Format). In diesem Dokument werden alle Ausgaben als JSON dargestellt.

1.4 Wichtige Daten Alle wichtigen Daten, welche Sie für die Kommunikation mit der veoovibes Schnittstelle benötigen finden Sie im Systemmanager unter dem Menüpunkt API.

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 4 von 23

HTTP API Dokumentation Version 1.1.069

1.5 Systemmanager Der Systemmanager von veoovibes ist ein eigener Service, welcher auf jeder veoovibes Installation vorhanden ist. Darüber können Wartungsaufgaben und Systemdiagnosen durchgeführt werden. Auch werden über den Systemmanager die API Einstellungen festgelegt.

1.5.1

Systemmanager öffnen

Den Systemmanager können Sie über die veoovibes Oberfläche über: „veoovibes Einstellungen -> System -> Systemmanager öffnen“ aufrufen.

1.6 Wiedergabelisten vs. Warteschlangen In veoovibes werden die Begriffe Wiedergabelisten und Warteschlangen verwendet. Wiedergabelisten sind vom Endbenutzer erstelle Listen, welche eine beliebige Anzahl von Musiktiteln enthalten. Warteschlangen gibt es pro Zone, diese stellen die abzuspielenden Titel der Zone dar.

1.7 Unterstützung Sie benötigen Hilfe? Unser Support-Team steht Ihnen mit Rat und Tat zur Seite. Bitte senden Sie Ihre Anfragen per EMail an: [email protected] oder besuchen Sie http://support.veoovibes.com

2 Funktionsbeschreibung

Mit der veoovibes HTTP API, können Sie Ihr veoovibes Multiroom Audio System über Netzwerkkomponenten steuern und so problemlos in Automatisierungsprozesse einbinden.

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 5 von 23

HTTP API Dokumentation Version 1.1.069

3 Grundfunktionalität 3.1 Räume In veoovibes können derzeit bis zu 8 Räume konfiguriert werden. Jeder Raum kann entweder direkt angeschlossen (Soundkarte), per AirPlay oder via DLNA angesteuert werden. Die AirPlay und DLNA Unterstützung muss jedoch in den Einstellungen jeweils einzeln aktiviert werden.

3.2 Zonen Analog zu den 8 Räumen gibt es auch 8 Zonen. Diese Zonen spielen die Musik und beinhalten zugleich auch die Warteschlangen, sowie weitere Einstellungen (Zufallswiedergabe, Warteschlange wiederholen).

3.3 Räume und Zonen Die in veoovibes konfigurierten Räume werden in Zonen gruppiert. Die Zonen spielen die Musik ab, die mit der Zone verbundenen Räume geben die Musik auf das jeweilige Ausgabegerät aus. Somit ist sichergestellt, dass die Räume beliebig zu einer Zone hinzugefügt bzw. entfernt werden können.

Zone 1

Zone2

Zone2

Wiedergabe: Webradio

Wiedergabe: gestoppt

Wiedergabe: gestoppt

Raum: Wohnzimmer

Raum: Küche

Raum: Badezimmer

Ausgabe: Soundkarte

Ausgabe: Soundkarte

Ausgabe: Soundkarte

Raum: Schlafzimmer Ausgabe: Soundkarte

3.4 Haussperre Bei der Haussperre in veoovibes handelt es sich um eine Funktion, welche der Endbenutzer aktivieren kann um die Wiedergabe in allen Räumen / Zonen zu stoppen. Zudem werden während einer aktiven Haussperre die Wecker und Timer deaktiviert. Der Endbenutzer muss, bevor er veoovibes wieder wie gewohnt verwenden kann, die Sperre aufheben.

3.4.1

Haussperre über die API

Werden Befehle über die API an veoovibes gesendet, so wird hierbei vom System automatisch geprüft, ob die Sperre aktiv ist. Ist dies der Fall, so wird die Haussperre automatisch aufgehoben und im Anschluss wird der eigentliche Befehl ausgeführt. Hinweis: Durch das Deaktivieren der Haussperre kann sich die Befehlsausführung bzw. Rückmeldung um ein paar Sekunden verzögern.

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 6 von 23

HTTP API Dokumentation Version 1.1.069

4 Web Service Location Die folgende Basis URI (Uniform Resource Identifier) wird für alle weiteren Befehle benötigt. Platzhalter

Wert



IP-Adresse von veoovibes (Hostname kann verwendet werden, wird aber nicht empfohlen) API-Key, dieser kann aus den Einstellungen von veoovibes ausgelesen werden

Basis URI

http:///api/v1/?api_key= Hinweis: Der API-Key MUSS bei jeder Anfrage übermittelt werden. Fehlt der API-Key oder ist dieser ungültig, wird die Anfrage vom System nicht verarbeitet.

5 API Antwort Format Alle Antworten erfolgen standardmäßig in JSON, es kann jedoch über den URL Parameter output das Format geändert werden. Beschreibung

Content-Type

Erweiterung

JSON (Standard) XML PHP

application/json;charset=UTF-8 text/xml;charset=UTF-8 text/plain;charset=UTF-8

json xml Php

5.1 Beispiel Antworten als XML Ausgabe erhalten

http:///api/v1//?api_key=&output=xml

6 API Antwort Codes Jede Anfrage / jeder Befehl an die Schnittstelle wird mit folgenden Angaben (im gewählten Format, siehe „API Antwort Format“) beantwortet: Name

Wert

status code error_message

Kann entweder “succeeded” (erfolgreich) oder “failed” (fehlgeschlagen) sein Sollte immer 0 sein, außer es trat ein Fehler auf, dann wird hier die Fehler ID ausgegeben Beinhaltet die Fehlermedung (sofern vorhanden), trat kein Fehler auf, bleibt diese leer

6.1.1

Antwort Code bei erfolgreicher Anfrage

Bei erfolgreichen Abfragen wird zusätzlich auch folgender Wert übertragen: Name

Wert

result

Enthält die angeforderten Daten oder einen Status Text

6.1.2

Fehler IDs

Code

Bedeutung

Beschreibung

1 2 3 10 20

Exception Http Method Required Parameter API disabled Access Token

Ein allgemeiner Fehler ist aufgetreten Die angeforderte http Methode wird für diese Anfrage nicht unterstützt Ein benötigter Parameter wurde nicht übergeben oder dessen Wert war leer Die API ist deaktiviert, wenden Sie sich an den Support Ungültiger oder fehlender API Key

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 7 von 23

HTTP API Dokumentation Version 1.1.069

7 Allgemeine Abfragen 7.1 Räume Abfragen 7.1.1

über Systemmanager

Eine Liste aller im System verfügbaren Räume, kann im Systemmanager eingesehen werden. Dort werden der Name und dessen ID angezeigt. Alternativ zu dieser einfachen Möglichkeit, steht auch ein entsprechender API Befehl zur Verfügung, welche alle Räume, deren IDs und weitere Details anzeigt.

7.1.2

über API

Gibt eine Liste mit allen im System konfigurierten Räumen zurück. Die Rückgabe enthält die API Antwort Codes und das Element result, welche alle Räume auflistet. Das Element result beinhaltet für jeden Raum folgende Werte: Wert

Bezeichnung

id_room type name current_volume is_available

Die Datenbank ID des Raums Definiert die Anschlussart des Raums. Mögliche Werte: “Soundkarte”, “Airplay”, “DNLA” Der vom Benutzer definierte Anzeigename für den Raum Die aktuell eingestellte Lautstärke für den Raum, Wertbereich: 0 – 100 Gibt an, ob der Raum verfügbar ist, mögliche Werte sind “true” oder “false”

Aufruf

http:///api/v1/listrooms/?api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": { "22": { "id_room": 22, "type": "Soundkarte", "name": "Wohnzimmer", "current_volume": 20, "is_available": true }, "23": { "id_room": 23, "type": "Soundkarte", "name": "Schlafzimmer", "current_volume": 16, "is_available": true }, "24": { "id_room": 24, "type": "Soundkarte", "name": "Küche", "current_volume": 16, "is_available": true } }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 8 von 23

HTTP API Dokumentation Version 1.1.069

7.2 Zonen Abfragen Gibt eine Liste mit der aktuellen Zonenkonfiguration zurück. Die Rückgabe enthält die API Antwort Codes und das Element result, welche alle Zonen auflistet. Das Element result beinhaltet für jede Zone folgende Werte: Wert

Bezeichnung

id_zone rooms room_detail

Die Datenbank ID der Zone Eine kommagetrennte Liste der IDs der Räume Ein Array pro Raum mit denselben Angaben wie unter “Räume Abfragen” (listrooms)

Aufruf

http:///api/v1/listzones/?api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": { "2": { "id_zone": 2, "rooms": "22,23", "room_detail": { "22": { "id_room": 22, "type": "Soundkarte", "name": "Wohnzimmer", "current_volume": 20, "is_available": true }, "23": { "id_room": 23, "type": "Soundkarte", "name": "Schlafzimmer", "current_volume": 16, "is_available": true } } }, "3": { "id_zone": 3, "rooms": "24", "room_detail": { "24": { "id_room": 24, "type": "Soundkarte", "name": "Küche", "current_volume": 16, "is_available": true } } } } }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 9 von 23

HTTP API Dokumentation Version 1.1.069

7.3 Player Status Abfragen Gibt eine Auflistung aller Informationen über den Wiedergabestatus inkl. Metadaten für alle Zonen aus. Aufruf

http:///api/v1/player_status/?api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": { "2": { "id_zone": 2, "player": { "mediatime_total": "03:56", "mediatime_now": "01:03", "mediatime_progress": 26.9138, "is_playing": 1, "zone_volume": 11, "random": 0, "repeat": 0, "status_code": "playing", "status": "Wiedergabe", "album": "", "artist": "Hi-Lights", "title": "Soul Limbo", "cover": "arts/artist/4424830be6c2f865ebd41ea1659955ae.jpg", "is_radio": false, "radio_name": "", "type": "" } }, "3": { "id_zone": 3, "player": { "mediatime_total": "", "mediatime_now": "", "mediatime_progress": 100, "is_playing": 0, "zone_volume": 16, "random": 0, "repeat": 0, "status_code": "stopped", "status": "Wiedergabe gestoppt", "album": "", "artist": "", "title": "", "cover": "", "is_radio": false, "radio_name": "", "type": "" } } } }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 10 von 23

HTTP API Dokumentation Version 1.1.069

7.4 Zonen Abfrage und Player Status kombiniert Gibt eine kombinierte Antwort aus den beiden Einzelabfragen „Zonen Abfragen“ und „Player Status Abfragen“ zurück. Aufruf

http:///api/v1/listzones_player_status/?api_key= Rückgabe (JSON) – ! Ausgabe gekürzt !

{ "status": "succeeded", "code": 0, "error_message": "", "result": { "2": { "id_zone": 2, "rooms": "22,23", "room_detail": { "28": { "id_room": 28, "type": "Soundkarte", "name": "Wohnzimmer", "current_volume": 20, "is_available": true }, "26": { "id_room": 23, "type": "Soundkarte", "name": "Schlafzimmer", "current_volume": 16, "is_available": true } }, "player": { "mediatime_total": "03:25", "mediatime_now": "03:22", "mediatime_progress": 98.4041, "is_playing": 1, "zone_volume": 11, "random": 0, "repeat": 0, "status_code": "playing", "status": "Wiedergabe", "album": "", "artist": "Eva Cassidy", "title": "Ain't No Sunshine", "cover": "arts/artist/7535226ce5fb311de812d0d6777cfcd7.jpg", "is_radio": false, "radio_name": "", "type": "" } } } }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 11 von 23

HTTP API Dokumentation Version 1.1.069

8 Zone steuern Einer dieser beiden Parameter wird für alle folgenden Aufrufe der Zonensteuerung benötigt. Name

Platzhalter

Wert

zone



Die ID der zu steuernden Zone, siehe “Zonen Abfragen” Parameter ab Version 1.0.865 verfügbar

zoneroom



Alternativ zu , wenn die Zone-ID nicht bekannt ist, kann auch die RaumID angegeben werden. Hinweis: Wird verwendet, wird der Wert von ignoriert (insofern angegeben).

8.1 Wiedergabe stoppen Stoppt die Wiedergabe der angegebenen Zone. Aufruf über Zonenparameter

http:///api/v1/stop/?zone=&api_key= Aufruf über Raumparameter

http:///api/v1/stop/?zoneroom=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

8.2 Wiedergabe starten Setzt die Wiedergabe an der letzten Position der Warteschlange fort. Aufruf über Zonenparameter

http:///api/v1/play/?zone=&api_key= Aufruf über Raumparameter

http:///api/v1/play/?zoneroom=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 12 von 23

HTTP API Dokumentation Version 1.1.069

8.3 vorheriger Titel Den vorherigen Titel der Warteschlange abspielen. Aufruf über Zonenparameter

http:///api/v1/prev/?zone=&api_key= Aufruf über Raumparameter

http:///api/v1/prev/?zoneroom=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

8.4 nächster Titel Den nächsten Titel der Warteschlange abspielen. Aufruf über Zonenparameter

http:///api/v1/next/?zone=&api_key= Aufruf über Raumparameter

http:///api/v1/next/?zoneroom=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 13 von 23

HTTP API Dokumentation Version 1.1.069

8.5 Zufallswiedergabe Die Zufallswiedergabe der Zone für die aktuelle Warteschlange aktivieren / deaktivieren. Aufruf über Zonenparameter

http:///api/v1/random/?zone=&api_key= Aufruf über Raumparameter

http:///api/v1/random/?zoneroom=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

8.6 Endloswiedergabe Die Einträge der Warteschlange wiederholen aktivieren / deaktivieren. Aufruf über Zonenparameter

http:///api/v1/repeat/?zone=&api_key= Aufruf über Raumparameter

http:///api/v1/repeat/?zoneroom=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 14 von 23

HTTP API Dokumentation Version 1.1.069

8.7 Lautstärke erhöhen Lautstärke aller mit der Zone verbundenen Räumen schrittweise erhöhen. Aufruf über Zonenparameter

http:///api/v1/vol_up/?zone=&api_key= Aufruf über Raumparameter

http:///api/v1/vol_up/?zoneroom=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

8.8 Lautstärke verringern Lautstärke aller mit der Zone verbundenen Räumen schrittweise verringern. Aufruf über Zonenparameter

http:///api/v1/vol_down/?zone=&api_key= Aufruf über Raumparameter

http:///api/v1/vol_down/?zoneroom=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 15 von 23

HTTP API Dokumentation Version 1.1.069

8.9 Lautstärke einstellen Setzt die Lautstärke aller mit der Zone verbundenen Räume auf einen Wert zwischen 0 – 100%. Die Räume werden dabei prozentuell aufgrund Ihrer letzten Einstellung (vorherige Raumlautstärke) angepasst Platzhalter

Wert



Ein Wert zwischen 0 und 100 als Ganzzahl

Aufruf über Zonenparameter

http:///api/v1/vol_set/?zone=&vol=&api_key= Aufruf über Raumparameter

http:///api/v1/vol_set/?zoneroom=&vol=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

8.10 alle Zonen stoppen Stoppt die Wiedergabe in allen Zonen. Aufruf

http:///api/v1/stop_all/?api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 16 von 23

HTTP API Dokumentation Version 1.1.069

9 Räume steuern Dieser Parameter wird für alle folgenden Aufrufe für die Raumsteuerung benötigt. Platzhalter

Wert



Die ID des zu steuernden Raumes, siehe “Räume Abfragen”

9.1 Lautstärke erhöhen Lautstärke des angegebenen Raumes schrittweise erhöhen. Hinweis: Ist der Raum als einziger Raum mit der Zone verbunden, so wird die Zonenlautstärke mit der neuen Lautstärke des Raums gleichgesetzt. Aufruf

http:///api/v1/room_vol_up/?room=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

9.2 Lautstärke verringern Lautstärke des angegebenen Raumes schrittweise verringern. Hinweis: Ist der Raum als einziger Raum mit der Zone verbunden, so wird die Zonenlautstärke mit der neuen Lautstärke des Raums gleichgesetzt. Aufruf

http:///api/v1/room_vol_down/?room=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 17 von 23

HTTP API Dokumentation Version 1.1.069

9.3 Lautstärke einstellen Lautstärke des angegebenen Raumes auf einen Wert zwischen 0 – 100% einstellen. Platzhalter

Wert



Ein Wert zwischen 0 und 100 als Ganzzahl

Hinweis: Ist der Raum als einziger Raum mit der Zone verbunden, so wird die Zonenlautstärke mit der neuen Lautstärke des Raums gleichgesetzt. Aufruf

http:///api/v1/room_vol_set/?room=&vol=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

9.4 Raum stoppen Da die Zone die Musik steuert, ist es im Normalfall erforderlich, die mit dem Raum verbundene Zone zu stoppen. Diese Funktion ermöglicht Ihnen die Zone aufgrund des angegebenen Raums zu stoppen ohne vorher die dazugehörige Zone abzufragen. Dabei kann entschieden werden, ob die gesamte Zone gestoppt werden soll oder ob der angegebene Raum aus der Zone entfernt werden soll. Platzhalter

Wert



Die ID des zu steuernden Raumes, siehe “Räume Abfragen” 1 = (Standard) Den Raum aus der aktuellen Zone entfernen – somit wird der Raum gestoppt und verliert gleichzeitig jedoch die Warteschlange aufgrund der neuen Zone. 2 = Die für den Raum zuständige Zone stoppen, somit werden ev. weitere verbunden Räume ebenfalls nichts mehr Wiedergeben.



Hinweis: Ist der Raum als einziger Raum mit der Zone verbunden, so wird unabhängig von der Angabe unter die Zone gestoppt, damit die aktuelle Warteschlange nicht verloren geht. Aufruf

http:///api/v1/stop_room/?room=&action=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 18 von 23

HTTP API Dokumentation Version 1.1.069

10 Raum / Zonen Zuordnung 10.1 Raum zu einer Zone hinzufügen Fügt einen Raum einer Zone hinzu. Platzhalter

Wert



Die ID des Raumes, siehe “Räume Abfragen” Die ID der Zone, siehe “Zonen Abfragen”

Aufruf

http:///api/v1/add_room_to_zone/?room=&zone=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" } Befindet sich der Raum bereits in der angegebenen Zone, so erhalten Sie folgende Rückmeldung: { "status": "failed", "code": 1, "error_message": "selected room is already assigned to this zone" }

10.2 Raum aus einer Zone entfernen Entfernt einen Raum aus einer Zone. Platzhalter

Wert



Die ID des Raumes, siehe “Räume Abfragen”

Aufruf

http:///api/v1/remove_room_from_zone/?room=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 19 von 23

HTTP API Dokumentation Version 1.1.069

11 Musik Wiedergabe Für die Musikwiedergabe müssen im Systemmanager die „Programme“ festgelegt werden, welche hier über den Befehl „Musik Wiedergeben“ abgespielt werden können. Dabei gilt es zu beachten, dass max. 12 Programmgruppen angelegt werden können. Jede Programmgruppe kann bis zu 12 „Speicherplätze“ enthalten. Pro Speicherplatz kann jeweils ein „Radiosender“ oder ein „pers. Radiosender“ oder eine „Wiedergabeliste“ hinterlegt werden.

11.1 Musik in der Zone abspielen Für das Abspielen von einem Speicherplatz in einer Zone. Alle mit der Zone verbunden Räume geben diesen Speicherplatz wieder. Platzhalter zone group prog

Wert

Die ID der Zone, siehe “Zonen Abfragen” Die ID der zur verwendenden Programmgruppe Die ID des Speicherplatzes innerhalb der Programmgruppe Parameter ab Version 1.0.865 verfügbar

zoneroom



Alternativ zu , wenn die Zone-ID nicht bekannt ist, kann auch die RaumID angegeben werden. Hinweis: Wird verwendet, wird der Wert von ignoriert (insofern angegeben).

Aufruf über Zonenparameter

http:///api/v1/music_zone/?group=&prog=&zone=&api_key= Aufruf über Raumparameter

http:///api/v1/music_zone/?group=&prog=&zoneroom=& api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 20 von 23

HTTP API Dokumentation Version 1.1.069

11.2 Musik in einem Raum abspielen Für das Abspielen von einem Speicherplatz in einem Raum. Dabei gilt folgende Logik: Ist der Raum der einzige in der Zone, so wird der angegebene Speicherplatz in die Warteschlange aufgenommen und abgespielt. Befinden sich in der Zone des angegebenen Raumes mehrere Räume, so wird der Raum aus der Zone entfernt und der angegebene Speicherplatz wiedergegeben. Platzhalter

Wert



Die ID des zu steuernden Raumes, siehe “Räume Abfragen” Die ID der zur verwendenden Programmgruppe Die ID des Speicherplatzes innerhalb der Programmgruppe

Aufruf

http:///api/v1/music_room/?group=&prog=&room=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 21 von 23

HTTP API Dokumentation Version 1.1.069

11.3 Fehlerbehandlung Wird über „Musik in einer Zone abspielen“ oder „Musik in einem Raum abspielen“ ein Speicherplatz aufgerufen welcher keinem Radiosender, pers. Radiosender oder einer Wiedergabeliste zugeordnet ist, so erhalten Sie über die API eine Fehlermeldung. Rückgabe / Fehlermeldung (JSON) { "status": "failed", "code": 1, "error_message": "group / prog not defined" } Da die Speicherplätze aufgrund der einfacheren Verwaltung durch den Endkunden auch geändert bzw. gelöscht werden können, erfolgt in diesem speziellen Fall eine akustische Rückmeldung an den Benutzer! Zusätzlich zur obigen Fehlermeldung erfolgt eine Sprachausgabe in der Zone oder dem gewählten Raum mit dem Inhalt: „Dieser Programmplatz kann nicht wiedergegeben werden. Bitte überprüfen Sie die Einstellungen“.

11.4 Warteschlange einer Zone leeren Leert / Löscht die komplette Warteschlange der angegebenen Zone. Platzhalter

Wert



Die ID der Zone, siehe “Zonen Abfragen”

Aufruf

http:///api/v1/empty_queue/?zone=&api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 22 von 23

HTTP API Dokumentation Version 1.1.069

11.5 Haussperre aktivieren Aktiviert die Haussperre. Mehr Informationen zur Haussperre unter „Grundfunktionalität“. Aufruf

http:///api/v1/lock_system/?api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

11.6 Haussperre deaktivieren Deaktiviert die Haussperre. Mehr Informationen zur Haussperre unter „Grundfunktionalität“. Aufruf

http:///api/v1/unlock_system/?api_key= Rückgabe (JSON)

{ "status": "succeeded", "code": 0, "error_message": "", "result": "OK" }

inveoo GmbH | Schloss Oberweis 5 | A-4664 Oberweis T: +43 7612 64372 | F: +43 7612 64372 - 80 | [email protected] | www.inveoo.com

Seite 23 von 23