Documentazione HTTP API
Attraverso la documentazione della HTTP API imparerai come controllare il tuo tabellone segnapunti video da remoto, sia tramite un dispositivo tipo Stream Deck, una chiamata con comando curl da riga di comando, o tramite un software sviluppato da te.
Cos’è un’API e un’HTTP API?
Un’API (Application Programming Interface) è un elemento che fornisce un modo per altri sistemi di interagire con esso. Esistono molti tipi di API, motivo per cui l’ho definita come “elemento”, e può fornire molti tipi di interazioni: puoi inviare dati, raccogliere dati da quel sistema o controllarlo da remoto.
Nel nostro caso, abbiamo implementato un’HTTP API, il che significa che abbiamo una sorta di server web, in attesa di ricevere le tue richieste come se stessi richiedendo un sito web, ed eseguire azioni in base all’indirizzo digitato.
Quindi, il punto importante qui è che si tratta di un server web, quindi puoi inviare richieste HTTP API utilizzando qualsiasi programma in grado di richiedere pagine web (il tuo browser preferito, l’applicazione curl su Linux e OSX, ecc.) e, ancora più importante, puoi farlo da qualsiasi computer, tablet o cellulare presente sulla stessa rete, permettendoti di avere molteplici LDSscoreboards (o LDSperimetral) controllati da un punto centralizzato, il tuo centro di controllo.
Per chiamare questa HTTP API, devi consultare un URL (URL è il nome dato all’indirizzo composto da protocollo, computer, porta e richiesta) come se fosse una “pagina web”. Ma dove si trova quella pagina web? Sto facendo confusione!. Il modo più semplice è aprire la richiesta che desideri con il tuo browser preferito. L’indirizzo da inserire avrà la seguente forma: https://IP_DEL_COMPUTER:PORTA_CONFIGURATA/RICHIESTA
Pertanto, e in sintesi:
- l’IP del computer dipende dalla configurazione di rete dell’attrezzatura. Consigliamo di renderlo fisso per evitare che cambi e che le richieste finiscano su un altro computer senza accorgersene.
- La porta è indicata nella configurazione del terminale, contrassegnata con una freccia rossa.
- La richiesta dipenderà dall’ordine che vuoi dare a LDSscoreboard (lo vedremo a breve).
Attraverso questa documentazione della HTTP API imparerai come controllare il tabellone segnapunti video da remoto in modo semplice.
Nel caso mostrato, l’IP del nostro computer è 192.168.1.35 e la porta configurata è la 8086.
Descrizione API
L’obiettivo è avere un’API per tutti i comandi di controllo di LDSscoreboard ad eccezione dell’editing dei contenuti. In questo modo è possibile controllare centralmente tutti gli schermi desiderati, pubblicare contenuti promozionali o aggiungere elementi ai preferiti.
Controllo slide
| Comando | Parametri |
|---|---|
| /pcontrol/list_slides | Recupera l’elenco delle slide disponibili nel tabellone caricato |
| /pcontrol/show_slide/ | Fa sì che la slide indicata venga visualizzata sullo schermo. name_slide = Nome della slide che desideri mostrare |
Controllo contatore
| Comando | Parametri |
|---|---|
| /pcontrol/list_counters | Recupera l’elenco dei contatori definiti nel tabellone attivo |
| /pcontrol/increment_counter/COUNTER_NAME | Incrementa il contatore passato come parametro counter_name = Nome del contatore su cui operare |
| /pcontrol/decrement_counter/COUNTER_NAME | Decrementa il contatore passato come parametro counter_name = Nome del contatore su cui operare |
| /pcontrol/set_counter/COUNTER_NAME/VALUE | Assegna un valore a un determinato contatore. counter_name = Nome del contatore su cui operare value = valore numerico da assegnare |
| /pcontrol/get_counter_value/COUNTER_NAME | Recupera il valore di un contatore. counter_name = Nome del contatore su cui operare value = valore numerico da assegnare |
Lista giocatori
| Comando | Parametri |
|---|---|
| /roster/get_local_team_name | Controlla il nome della squadra di casa |
| /roster/get_guest_team_name | Controlla il nome della squadra ospite |
| /roster/get_team_players_count/[local|guest] | Restituisce il numero di giocatori nella squadra di casa o ospite |
| /roster/get_player_information/PLAYER_INDEX[local|guest] | Restituisce le informazioni del giocatore indicato (nome, numero, ecc.) |
| /roster/increment_player_score/[local|guest] /PLAYER_INDEX | Aumenta il punteggio associato al giocatore con l’indice indicato |
| /roster/decrement_player_score/[local|guest] /PLAYER_INDEX | Diminuisce il punteggio associato al giocatore con l’indice indicato |
| /roster/get_player_score/[local|guest] /PLAYER_INDEX | Recupera il punteggio associato al giocatore con l’indice indicato |
| /roster/increment_player_fauls/[local|guest] /PLAYER_INDEX | Aumenta i falli associati al giocatore con l’indice indicato |
| /roster/decrement_player_fauls/[local|guest] /PLAYER_INDEX | Diminuisce i falli associati al giocatore con l’indice indicato |
| /roster/get_player_faults/[local|guest] /PLAYER_INDEX | Recupera i falli associati al giocatore con l’indice indicato |
| /roster/increment_player_cautions/[local|guest] /PLAYER_INDEX | Aumenta gli ammonimenti associati al giocatore con l’indice indicato |
| /roster/decrement_player_cautions/[local|guest] /PLAYER_INDEX | Diminuisce gli ammonimenti associati al giocatore con l’indice indicato |
| /roster/get_player_cautions/[local|guest] /PLAYER_INDEX | Recupera gli ammonimenti associati al giocatore con l’indice indicato |
Controllo timer
| Comando | Parametri |
|---|---|
| /pcontrol/list_timers | Recupera l’elenco dei timer disponibili nel tabellone attivo |
| /pcontrol/start_timer/TIMER_NAME | Avvia il timer nella direzione in cui è stato definito. name_timer = Nome del timer (o cronometro) su cui operare |
| /pcontrol/stop_timer/TIMER_NAME | Ferma il timer. Il suo valore non viene alterato. name_timer = Nome del timer (o cronometro) su cui operare |
| /pcontrol/reset_timer/TIMER_NAME | Resetta il timer al valore iniziale definito nella sua configurazione. name_timer = Nome del timer (o cronometro) su cui operare |
| /pcontrol/get_timer_time/TIMER_NAME | Recupera il valore del timer. name_timer = Nome del timer (o cronometro) su cui operare |
Etichette dinamiche e contatori automatici
| Comando | Parametri |
|---|---|
| /gc/list_dynamic_labels | Recupera l’elenco delle etichette dinamiche disponibili nel tabellone caricato |
| /gc/get_dynamic_label/VAR | Recupera il valore assegnato alla variabile dinamica VAR = Identificatore della variabile da interrogare |
| /gc/set_dynamic_label/VAR/ARG1 | Modifica il valore assegnato alla variabile dinamica VAR = Identificatore della variabile da assegnare ARG1 = Nuovo valore da assegnare |
| /gc/get_automatic_variable/VAR | Ottiene il valore di una variabile automatica. Queste variabili vengono calcolate quando si utilizza la lista giocatori. VAR = Nome della variabile Variabili esistenti: local_team_score : punteggio squadra di casa local_team_fauls: falli commessi dalla squadra di casa local_team_fauls_resetable: falli commessi dalla squadra di casa, ma resettabili. guest_team_score: punteggio squadra ospite guest_team_fauls: falli della squadra ospite guest_team_fauls_resettable: falli della squadra ospite, ma resettabili. |
| /gc/reset_automatic_variable/VAR | Resetta il contatore a zero per le variabili automatiche che possono essere resettate. VAR: Nome della variabile resettabile (local_team_fauls_resetable o guest_team_fauls_resetable) |
Gestione vettori
| Comando | Parametri |
|---|---|
| /pcontrol/list_vectors | Recupera l’elenco dei vettori disponibili nel tabellone attualmente attivo |
| /pcontrol/increment_vector_element/VECTOR_ID/INDEX/INCREMENT_VALUE | Incrementa il valore dell’elemento nella posizione INDEX del vettore VECTOR_ID. L’incremento è determinato da INCREMENT_VALUE |
| /pcontrol/set_vector_element_value/VECTOR_ID/INDEX/VALUE | Imposta il valore dell’elemento nella posizione INDEX del vettore VECTOR_ID. Il nuovo valore è determinato da VALUE |
| /pcontrol/get_vector_element_value/VECTOR_ID/INDEX | Ottiene il valore dell’elemento nella posizione INDEX del vettore VECTOR_ID. |
| /pcontrol/get_vector_length/VECTOR_ID | Recupera il numero di elementi del vettore. Vale a dire, la dimensione definita. |
Esempio di utilizzo dell’API HTTP di LDSscoreboard
Vediamo un esempio per comprendere chiaramente il funzionamento descritto in questa documentazione sull’API HTTP. Supponiamo di aver definito un marcatore che contiene una slide chiamata “slide1”; per richiedere al sistema di aprire la slide1, dobbiamo conoscere l’IP del computer e la porta, dato che il nome lo conosciamo già.
Se guardiamo l’immagine nella parte superiore della pagina, vedremo che abbiamo l’IP 192.168.1.35 e la porta 8080, quindi dobbiamo effettuare una richiesta HTTP (aprire la pagina) all’indirizzo http://192.168.1.35:8080/pcontrol/show_slide/slide1
Per farlo, possiamo aprire un browser e inserire l’indirizzo nella barra degli indirizzi:
Successivamente, se LDSscoreboard è in esecuzione, dovremmo vedere la slide chiamata slide1 diventare attiva.
IMPORTANTE
Se il nome della slide contiene uno spazio, trattandosi di un carattere speciale, dobbiamo sostituirlo con %20; ovvero, “my slide” sarà tradotto come “my%20slide”.
Strumenti per effettuare chiamate API HTTP
Naturalmente, non sei limitato a dover effettuare chiamate HTTP da un browser; lo abbiamo fatto in questo modo perché è uno strumento che sicuramente hai a portata di mano e conosci, ma ci sono molti altri modi per farlo.
curl
curl è uno strumento open source per richieste HTTP. È disponibile su Linux, OSX e anche sulle ultime versioni di Windows 10. Il suo utilizzo è molto semplice, come si può vedere nell'immagine seguente:
JavaScript
Puoi creare un programma in Javascript, usando jquery, in cui viene effettuata una chiamata HTTP, ad esempio con questo codice:
timer_identifier="my timer";
$.getJSON(`/pcontrol/start_
.done(function (data) )
.fail(function (err) );
e qualsiasi linguaggio di programmazione ti permetterà di effettuare questo tipo di chiamate.
Pagina aggiornata il 25/04/2024