API HTTP di LDSperimetral

Versione: 1.58.1

Ultimo aggiornamento: 2026-11-12

Questo manuale descrive i servizi implementati per il controllo del player e la misurazione onTV. Tutti gli esempi sono puramente illustrativi.

Indice

• Configurazione e accesso
• Richieste e risposte
• Rotte del player
• Parametri
• Dati del player
• Rotte e dati onTV
• Esempi
• Limitazioni

Configurazione e accesso

Utilizzare un'installazione funzionante di LDSperimetral su Windows con il relativo runtime .NET Framework 4.7.2 e la normale configurazione del player. L'applicazione deve essere in esecuzione. L'API è ospitata dall'applicazione stessa, non da un server separato.

Nella finestra di configurazione del terminale, abilitare il controllo remoto del player per il servizio del player. Abilitare separatamente il misuratore onTV per il servizio di statistiche. Salvare e applicare la configurazione del terminale. La finestra rifiuta la porta se coincide con quella della rete di sincronizzazione. Le relative impostazioni memorizzate in config/terminals.xml sono remote_player_enabled, on_tv_meter_enabled e port. Entrambi i flag di attivazione sono impostati su false per predefinita. Il valore predefinito nel codice per port è 8083; un'installazione esistente può utilizzare un'altra porta.

Sostituire HOST con l'indirizzo del computer del player e PORT con la sua porta HTTP configurata. Usare 127.0.0.1 esclusivamente da quel computer. L'host si collega a http://0.0.0.0:PORT/; questo non è una destinazione per i client. Le autorizzazioni URL di Windows, le regole del firewall e la raggiungibilità di rete possono influire sull'accesso. All'avvio potrebbe essere richiesta l'autorizzazione per aprire la porta TCP del firewall e concedere una prenotazione URL in Windows. Seguire le istruzioni dell'applicazione, incluso il riavvio quando richiesto.

Il servizio utilizza HTTP semplice e un WebHttpBinding predefinito. In questi servizi non sono implementati chiavi API, login, autorizzazioni per singolo comando o elenchi consentiti di IP client. I client raggiungibili possono inviare comandi di riproduzione e misurazione. Limitare l'accesso alla rete ai client attendibili. Le prenotazioni URL di Windows autorizzano il processo del server a rimanere in ascolto; non autenticano i chiamanti dell'API. Questo host non fornisce alcuna configurazione HTTPS o CORS. L'accesso cross-origin tramite browser non è un'interfaccia garantita.

Richieste e risposte

Tutte le rotte sottostanti utilizzano GET, inclusi i comandi che modificano lo stato. Aggiungere ciascuna rotta all'URL di base del servizio. Non è dichiarato alcun corpo di richiesta o parametro di query. I segnaposto racchiusi tra graffe sono segmenti di percorso obbligatori, a meno che la rotta non descriva esplicitamente il carattere jolly di interruzione dell'overlay. Non inviare le parentesi graffe letteralmente.

Le risposte utilizzano la serializzazione JSON di WCF e un oggetto comune:

Gli errori dell'applicazione vengono restituiti all'interno di questo contenitore senza modificare esplicitamente lo stato HTTP. Di conseguenza, un errore dell'applicazione serializzato normalmente rimane una risposta di successo HTTP. Ispezionare sempre status e successivamente il campo result atteso. Un errore di trasporto o di routing WCF può avere un corpo differente e non deve essere interpretato come un contenitore garantito. I test si aspettano un codice HTTP 404 per una rotta sconosciuta e 405 per un metodo non supportato; queste aspettative non sono state verificate su un host in esecuzione per questo manuale.

Per i comandi booleani, status: 0 e result: true indicano che il percorso del comando è stato elaborato. Non provano la riuscita dell'output audiovisivo o il completamento di una transizione. Alcuni metodi sottostanti intercettano gli errori o non eseguono alcuna azione in assenza di un rendering. Interrogare get_reproduction_state dopo un comando e attendere lo stato desiderato con un timeout definito dal client. Non sono previsti ID di comando, endpoint di completamento, notifiche push o scadenze di transizione specificate. Non inviare ripetutamente un comando mentre si è in attesa del suo effetto.

Ad eccezione di ping, le operazioni del player passano attraverso il dispatcher della finestra di controllo quando disponibile. Questo serializza l'accesso al controllo sul thread dell'interfaccia utente (UI), ma non rende le richieste HTTP separate una transazione atomica. Le operazioni statistiche non utilizzano questo helper di dispacciamento del player.

Rotte del player

Tutti i percorsi in questa tabella sono relativi a /ws/remoteplayer/.

La rotta dell'overlay specificata per nome è più specifica rispetto a quella con carattere jolly. Un nome di overlay inesistente restituisce SEQUENCE_NOT_FOUND; non si tratta di una richiesta di arresto. Il routing con carattere jolly con coda vuota e altri casi limite di percorsi codificati richiedono comunque la validazione da parte dell'host.

Parametri

Codificare in percentuale (percent-encode) ciascun segmento di percorso stringa come UTF-8. Ad esempio, Demo Show diventa Demo%20Show; codificare un carattere + letterale come %2B, # come %23, ? come %3F e % come %25. Non codificare i separatori tra i segmenti della rotta. Gli helper degli URL utilizzano Uri.EscapeDataString per i riferimenti di avvio. Slash codificati, backslash e percorsi completi del file system possono essere influenzati dallo stack HTTP di Windows e non sono verificati qui. È preferibile utilizzare un nome univoco o un nome base privo di separatori di percorso. L'assenza di segmenti obbligatori può causare il fallimento del routing WCF prima della validazione dell'applicazione.

Dati del player

I nomi dei campi sottostanti corrispondono esattamente ai nomi del contratto JSON. L'ordine delle proprietà dell'oggetto non è significativo. I campi dei file contengono riferimenti memorizzati e possono esporre informazioni sul file system; non dare per scontato che si tratti di URL di download pubblici.

I valori temporali sono stringhe JSON, non numeri o intervalli di tempo formattati. Entrambi i campi temporali sono "0" in assenza di una sequenza attiva. La loro interpolazione utilizza la cultura del server; non dare per scontato un separatore decimale invariante o una precisione di misurazione al millisecondo. I valori di file/nome copiati dal modello possono essere null. Un errore dell'applicazione può restituire risultati nulli, vuoti o parzialmente popolati; controllare status prima di utilizzarli.

Rotte e dati onTV

Tutti i percorsi in questa tabella sono relativi a /ws/statsmeter/. Mantenere l'ortografia mesures esattamente come mostrato.

Questi comandi contrassegnano i periodi di misurazione. Non avviano né interrompono la riproduzione della playlist e non rilevano un segnale di trasmissione. Il controller restituisce un intervallo predefinito, o un elenco vuoto per l'operazione sugli elenchi, in assenza di un rendering. Un rendering privo di un misuratore di statistiche può restituire null; l'avvio e l'arresto incontrano quindi la dereferenziazione di logging del servizio e segnalano un errore interno. Questa può essere una risposta OK priva di una misurazione effettiva.

Il marcatore non impostato è una data con anno 1970, inizializzata al 1° gennaio 1970. Un intervallo aperto ha una fine non impostata. L'assenza di un intervallo registrato produce un oggetto predefinito con entrambe le date non impostate. L'arresto ripetuto lascia inalterato un intervallo chiuso. Le date provengono da DateTime.Now sul server. WCF utilizza la rappresentazione /Date(milliseconds[+or-offset])/, con un possibile escape degli slash in JSON; non si tratta di un contratto ISO 8601. L'offset opzionale e la gestione locale/non specificata di DateTime devono essere verificati sull'host di distribuzione. Non interpretare il valore sentinella come un timestamp misurato reale.

L'accumulo dei millisecondi utilizza una conversione a intero a 32 bit prima dell'arrotondamento. Cronologie lunghe possono superare tale intervallo. Non trattare questo valore come un contatore di durata a precisione illimitata o come una cronologia di durata garantita tra i riavvi. Le intercettazioni delle statistiche segnalano INTERNAL_ERROR; il loro messaggio può rimanere nullo.

Esempi

Tutte le richieste e i valori JSON in questa sezione sono illustrativi. L'host, i nomi e i riferimenti ai file sono segnaposto privi di dati privati. Le risposte sono contenitori completi, salvo diversa indicazione. L'ordine delle proprietà e gli spazi bianchi JSON possono variare.

Verificare la disponibilità dal computer del player quando la porta configurata è 8083:

curl "http://127.0.0.1:8083/ws/remoteplayer/ping"

{"message":null,"result":true,"status":0}

Elencare le sequenze in una playlist disponibile denominata Demo Show:

curl "http://127.0.0.1:8083/ws/remoteplayer/list_playlist_sequences/Demo%20Show"

{"message":null,"result":[{"filename":"demo.sequence","is_on_top":false,"name":"Opening"}],"status":0}

Avviare la sua prima sequenza, quindi interrogare lo stato. Si tratta di due richieste separate:

curl "http://127.0.0.1:8083/ws/remoteplayer/start_sequence/Demo%20Show/0"
curl "http://127.0.0.1:8083/ws/remoteplayer/get_reproduction_state"

Risposta di comando illustrativa:

{"message":null,"result":true,"status":0}

Risposta di stato illustrativa dopo la transizione:

{"message":null,"result":{"is_playing":true,"is_paused":false,"is_render_active":true,"is_quickaction":false,"current_playlist":"Demo Show","current_playlist_file":"demo.playlist","current_sequence":"Opening","current_sequence_index":0,"current_overlay_sequence_name":"","current_overlay_sequence_file":"","current_sequence_elapsed_time":"1000","current_sequence_total_time":"300000"},"status":0}

Indice di sequenza non valido in una playlist esistente:

curl "http://127.0.0.1:8083/ws/remoteplayer/start_sequence/Demo%20Show/-1"

{"message":"Sequence index must identify an existing sequence.","result":false,"status":5}

Query per una playlist mancante:

{"message":"Playlist [Missing] not found.","result":[],"status":4}

Avviare un overlay denominato Demo Overlay, quindi rimuoverlo:

curl "http://127.0.0.1:8083/ws/remoteplayer/start_aot_sequence/Demo%20Overlay"
curl "http://127.0.0.1:8083/ws/remoteplayer/start_aot_sequence/"

Impostare la luminosità globale al 50 percento:

curl "http://127.0.0.1:8083/ws/remoteplayer/set_global_brightness/50"

Aprire, ispezionare e chiudere un intervallo onTV, quindi leggere i totali:

curl "http://127.0.0.1:8083/ws/statsmeter/start_on_tv_interval"
curl "http://127.0.0.1:8083/ws/statsmeter/state_on_tv_interval"
curl "http://127.0.0.1:8083/ws/statsmeter/stop_on_tv_interval"
curl "http://127.0.0.1:8083/ws/statsmeter/get_mesures_statistics"

Risposta statistica illustrativa dopo un intervallo completato di cinque secondi:

{"message":null,"result":{"intervals_recorded":1,"total_seconds_in_tv":5},"status":0}

Limitazioni

Gli offset di data, il routing con caratteri jolly, i corpi di errore HTTP e l'accesso specifico della distribuzione richiedono una validazione sull'installazione di destinazione.

Questo livello API non implementa alcun limite di frequenza (rate limit), isolamento dei client, transazione di richiesta, garanzia generale di idempotenza o garanzia di completamento audiovisivo. I comandi utilizzano GET, pertanto l'anteprima dei link, il prefetching, la memorizzazione nella cache (caching) e i tentativi automatici possono risultare non sicuri per i comandi. Utilizzare un client che invia richieste solo quando intenzionale e che non riutilizza risposte di query memorizzate nella cache. Il codice del server non stabilisce un contratto di controllo della cache (cache-control).

L'interfaccia HTML onTV, i metadati WCF e gli endpoint mex sono separati dalle operazioni JSON documentate qui. Non costituiscono rotte di comandi aggiuntive per il player. In questi due contratti JSON non è dichiarata alcuna operazione di caricamento, modifica di playlist, download di file, lettura della luminosità o sottoscrizione di eventi.