HTTP-API-Dokumentation
In der HTTP-API-Dokumentation erfahren Sie, wie Sie Ihre Video-Anzeigetafel fernsteuern können – sei es über ein Gerät wie ein Stream Deck, einen cURL-Befehl über die Kommandozeile oder über eine Software, die Sie selbst entwickeln.
Was ist eine API und eine HTTP-API?
Eine API (Application Programming Interface) ist ein Element, das anderen Systemen eine Möglichkeit bietet, mit ihm zu interagieren. Es gibt viele Arten von APIs, weshalb ich es als „Element“ bezeichnet habe, und es kann viele Arten von Interaktionen ermöglichen: Sie können Daten an die API senden, Daten von diesem System abrufen oder es fernsteuern.
In unserem Fall haben wir eine HTTP-API implementiert. Das bedeutet, wir verfügen über eine Art Webserver, der darauf wartet, Ihre Anfragen entgegenzunehmen, so als würden Sie eine Webseite aufrufen, und je nach eingegebener Adresse bestimmte Aktionen ausführt.
Das Wichtige hierbei ist, dass es sich um einen Webserver handelt. Sie können also HTTP-API-Anfragen mit jedem Programm senden, das Webseiten anfordern kann (Ihr bevorzugter Browser, die Anwendung curl unter Linux und macOS usw.). Und was noch wichtiger ist: Sie können dies von jedem Computer, Tablet oder Mobiltelefon aus tun, das sich im selben Netzwerk befindet. Dies ermöglicht es Ihnen, mehrere LDSscoreboards (oder LDSperimetral) von einem zentralen Punkt aus zu steuern – Ihrer Steuerzentrale.
Um diese HTTP-API aufzurufen, müssen Sie eine URL abfragen (URL ist der Name für die Adresse, die sich aus Protokoll, Computer, Port und Anfrage zusammensetzt), so als wäre es eine „Webseite“. Aber wo ist diese Webseite? Ich bringe hier einiges durcheinander! Der einfachste Weg ist, die gewünschte Anfrage in Ihrem bevorzugten Browser zu öffnen. Die einzugebende Adresse hat folgende Form: https://IP_DES_COMPUTERS:KONFIGURIERTER_PORT/ANFRAGE
Zusammenfassend lässt sich also sagen:
- Die IP des Computers hängt von der Netzwerkkonfiguration des Geräts ab. Wir empfehlen, eine feste IP zu vergeben, um zu verhindern, dass sie sich ändert und die Anfragen versehentlich an einen anderen Computer gesendet werden.
- Der Port ist in der Terminalkonfiguration angegeben und mit einem roten Pfeil markiert.
- Die Anfrage hängt von dem Befehl ab, den Sie an LDSscoreboard senden möchten (wir werden dies in Kürze sehen).
Über diese HTTP-API-Dokumentation lernen Sie, wie Sie die Video-Anzeigetafel auf einfache Weise fernsteuern können.
Im gezeigten Fall ist die IP unseres Computers 192.168.1.35 und der konfigurierte Port ist 8086.
API-Beschreibung
Das Ziel ist eine API für alle LDSscoreboard-Steuerungsbefehle mit Ausnahme der Inhaltsbearbeitung. Auf diese Weise können Sie alle gewünschten Bildschirme zentral steuern, Werbeinhalte veröffentlichen oder Elemente als Lesezeichen speichern.
Foliensteuerung
| Befehl | Parameter |
|---|---|
| /pcontrol/list_slides | Ruft die Liste der auf der geladenen Anzeigetafel verfügbaren Folien ab |
| /pcontrol/show_slide/ | Bewirkt, dass die angegebene Folie auf dem Bildschirm angezeigt wird. name_slide = Name der anzuzeigenden Folie |
Zählersteuerung
| Befehl | Parameter |
|---|---|
| /pcontrol/list_counters | Ruft die Liste der auf der aktiven Anzeigetafel definierten Zähler ab |
| /pcontrol/increment_counter/COUNTER_NAME | Erhöht den als Parameter übergebenen Zähler. counter_name = Name des Zählers, auf dem die Operation ausgeführt werden soll |
| /pcontrol/decrement_counter/COUNTER_NAME | Verringert den als Parameter übergebenen Zähler. counter_name = Name des Zählers, auf dem die Operation ausgeführt werden soll |
| /pcontrol/set_counter/COUNTER_NAME/VALUE | Weist einem bestimmten Zähler einen Wert zu. counter_name = Name des Zählers, auf dem die Operation ausgeführt werden soll. value = zuzuweisender numerischer Wert |
| /pcontrol/get_counter_value/COUNTER_NAME | Ruft den Wert eines Zählers ab. counter_name = Name des Zählers, auf dem die Operation ausgeführt werden soll. value = zuzuweisender numerischer Wert |
Spielerkader
| Befehl | Parameter |
|---|---|
| /roster/get_local_team_name | Prüft den Namen des Heimteams |
| /roster/get_guest_team_name | Prüft den Namen des Gastteams |
| /roster/get_team_players_count/[local|guest] | Gibt die Anzahl der Spieler im Heim- oder Gastteam zurück |
| /roster/get_player_information/PLAYER_INDEX[local|guest] | Gibt die Informationen des angegebenen Spielers zurück (Name, Nummer etc.) |
| /roster/increment_player_score/[local|guest] /PLAYER_INDEX | Erhöht den Punktestand des Spielers mit dem angegebenen Index |
| /roster/decrement_player_score/[local|guest] /PLAYER_INDEX | Verringert den Punktestand des Spielers mit dem angegebenen Index |
| /roster/get_player_score/[local|guest] /PLAYER_INDEX | Ruft den Punktestand des Spielers mit dem angegebenen Index ab |
| /roster/increment_player_fauls/[local|guest] /PLAYER_INDEX | Erhöht die Fouls des Spielers mit dem angegebenen Index |
| /roster/decrement_player_fauls/[local|guest] /PLAYER_INDEX | Verringert die Fouls des Spielers mit dem angegebenen Index |
| /roster/get_player_faults/[local|guest] /PLAYER_INDEX | Ruft die Fouls des Spielers mit dem angegebenen Index ab |
| /roster/increment_player_cautions/[local|guest] /PLAYER_INDEX | Erhöht die Verwarnungen des Spielers mit dem angegebenen Index |
| /roster/decrement_player_cautions/[local|guest] /PLAYER_INDEX | Verringert die Verwarnungen des Spielers mit dem angegebenen Index |
| /roster/get_player_cautions/[local|guest] /PLAYER_INDEX | Ruft die Verwarnungen des Spielers mit dem angegebenen Index ab |
Timer-Steuerung
| Befehl | Parameter |
|---|---|
| /pcontrol/list_timers | Ruft die Liste der auf der aktiven Anzeigetafel verfügbaren Timer ab |
| /pcontrol/start_timer/TIMER_NAME | Startet den Timer in der definierten Richtung. name_timer = Name des Timers (oder Chronometers), auf dem die Operation ausgeführt werden soll |
| /pcontrol/stop_timer/TIMER_NAME | Stoppt den Timer. Der Wert wird nicht verändert. name_timer = Name des Timers (oder Chronometers), auf dem die Operation ausgeführt werden soll |
| /pcontrol/reset_timer/TIMER_NAME | Setzt den Timer auf den in der Konfiguration definierten Anfangswert zurück. name_timer = Name des Timers (oder Chronometers), auf dem die Operation ausgeführt werden soll |
| /pcontrol/get_timer_time/TIMER_NAME | Ruft den Wert eines Timers ab. name_timer = Name des Timers (oder Chronometers), auf dem die Operation ausgeführt werden soll |
Dynamische Labels und automatische Zähler
| Befehl | Parameter |
|---|---|
| /gc/list_dynamic_labels | Ruft die Liste der dynamischen Labels auf der geladenen Anzeigetafel ab |
| /gc/get_dynamic_label/VAR | Ruft den Wert der dynamischen Variablen ab. VAR = Bezeichner der abzufragenden Variablen |
| /gc/set_dynamic_label/VAR/ARG1 | Ändert den Wert der dynamischen Variablen. VAR = Bezeichner der zuzuweisenden Variablen, ARG1 = Neuer zuzuweisender Wert |
| /gc/get_automatic_variable/VAR | Ruft den Wert einer automatischen Variablen ab. Diese Variablen werden bei Verwendung des Spielerkaders berechnet. VAR = Variablenname. Bestehende Variablen: local_team_score : Punktestand Heimteam, local_team_fauls: Fouls Heimteam, local_team_fauls_resetable: Fouls Heimteam (rücksetzbar), guest_team_score: Punktestand Gastteam, guest_team_fauls: Fouls Gastteam, guest_team_fauls_resettable: Fouls Gastteam (rücksetzbar). |
| /gc/reset_automatic_variable/VAR | Setzt den Zähler für rücksetzbare automatische Variablen auf Null. VAR: Name der rücksetzbaren Variablen (local_team_fauls_resetable oder guest_team_fauls_resetable) |
Vektorverwaltung
| Befehl | Parameter |
|---|---|
| /pcontrol/list_vectors | Ruft die Liste der in der aktuell aktiven Anzeigetafel verfügbaren Vektoren ab |
| /pcontrol/increment_vector_element/VECTOR_ID/INDEX/INCREMENT_VALUE | Erhöht den Wert des Elements an der Position INDEX im Vektor VECTOR_ID. Die Erhöhung wird durch INCREMENT_VALUE bestimmt |
| /pcontrol/set_vector_element_value/VECTOR_ID/INDEX/VALUE | Setzt den Wert des Elements an der Position INDEX im Vektor VECTOR_ID. Der neue Wert wird durch VALUE bestimmt |
| /pcontrol/get_vector_element_value/VECTOR_ID/INDEX | Ruft den Wert des Elements an der Position INDEX im Vektor VECTOR_ID ab |
| /pcontrol/get_vector_length/VECTOR_ID | Ruft die Anzahl der Elemente des Vektors ab, also die definierte Größe |
Anwendungsbeispiel für die LDSscoreboard HTTP API
Lassen Sie uns ein Beispiel betrachten, um den in dieser Dokumentation beschriebenen Vorgang zur HTTP API besser zu verstehen. Angenommen, wir haben einen Marker definiert, der eine Folie namens „slide1“ enthält. Um das System anzuweisen, „slide1“ zu öffnen, müssen wir die IP des Computers und den Port kennen, da uns der Name bereits bekannt ist.
Wenn wir das Bild oben auf der Seite betrachten, sehen wir, dass wir die IP 192.168.1.35 und den Port 8080 haben. Wir sollten also eine HTTP-Anfrage (die Seite öffnen) an die Adresse http://192.168.1.35:8080/pcontrol/show_slide/slide1 senden.
Dazu können wir einen Browser öffnen und die Adresse in die Adressleiste eingeben:
Wenn LDSscoreboard anschließend läuft, sollten Sie sehen, dass die Folie namens „slide1“ aktiviert wird.
WICHTIG
Wenn der Name der Folie ein Leerzeichen enthält, da dies ein Sonderzeichen ist, müssen wir es durch %20 ersetzen. Das bedeutet, dass „my slide“ als „my%20slide“ übersetzt wird.
Tools zum Ausführen von HTTP-API-Aufrufen
Natürlich sind Sie nicht darauf beschränkt, HTTP-Aufrufe über einen Browser tätigen zu müssen. Wir haben dies so gemacht, weil es ein Tool ist, das Sie sicherlich zur Hand haben und kennen, aber es gibt viele andere Wege, dies zu tun.
curl
curl ist ein Open-Source-Tool für HTTP-Anfragen. Es ist unter Linux, OSX sowie auf den neuesten Versionen von Windows 10 verfügbar. Die Verwendung ist sehr einfach, wie im folgenden Bild zu sehen ist:
JavaScript
Sie können ein Programm in Javascript unter Verwendung von jQuery erstellen, mit dem ein HTTP-Aufruf erfolgt, zum Beispiel mit diesem Code:
timer_identifier="my timer";
$.getJSON(`/pcontrol/start_
.done(function (data) )
.fail(function (err) );
und jede Programmiersprache ermöglicht es Ihnen, diese Art von Aufrufen zu tätigen.