API Conteggi riproduzioni

Aggregati giornalieri di riproduzione.

JSON restituisce al massimo 200 righe e non è limitato da rate. format=csv (o Accept text/csv senza application/json) trasmette ogni riga corrispondente dentro day_from a day_to (giorni UTC inclusi; default day_to oggi e day_from 30 giorni prima; massimo 366 giorni, altrimenti invalid_request) come CSV con riga intestazione fissa (PlaybackAggregateCsv); solo la forma CSV consuma i budget playback-export-org (30 al minuto) e playback-export-ip (60 al minuto).

Entrambe le forme sono una richiesta API conteggiata. Le risposte includono Vary Accept. Un chiamante limitato agli schermi (docs/screen-scope.md) deve inviare screen_id, che deve essere uno schermo dentro il suo ambito (altrimenti outside_screen_scope); le forme CSV seguono la stessa regola.

Record per riproduzione: una riga per ogni playback.media_started accettato (o playback.video_started legacy) e una riga per ogni playback.application_started accettato (release_id impostato, campi media vuoti) del progetto chiamante, dal più vecchio per received_at, in caso di parità per inserimento. Da (incluso) e a (escluso) limite received_at; a predefinito ora, da a 24 ore prima di a, e l’intervallo è al massimo 31 giorni (invalid_request altrimenti).

Gli ultimi 5 secondi non sono ancora restituiti: il to effettivo è al massimo ora meno 5 secondi (settle lag), quindi una coda live non salta mai una riga che si impegna dietro il suo cursore. Filtrano screen_id, media_id, playlist_id (la playlist da cui è stato mostrato l’inizio) e tag (un tag schermo che lo schermo aveva quando è stato ricevuto il play).

Una pagina playlist_id può contenere meno di limit righe, anche nessuna, con next_cursor quando è stata scansionata una lunga serie di riproduzioni di altre playlist; null indica comunque la fine dell’intervallo.

JSON è una pagina di al massimo limit righe (default 200, massimo 1000) con next_cursor, null alla fine dell’intervallo; restituiscilo come cursor con gli stessi filtri. order=desc (o before) pagina i più recenti per primi nello stesso intervallo: next_cursor è allora il cursore della riga più vecchia restituita, null all’inizio dell’intervallo, e viene restituito come before (esclusivo) con gli stessi filtri; order=asc con before è rifiutato con invalid_request che nomina order, e cursor con una pagina newest-first che nomina cursor.

Una pagina più recente può contenere meno di limit righe, anche nessuna, con next_cursor; null indica comunque la fine.

Una pagina successiva non salta mai una riga esistente quando la pagina precedente è stata letta e non ne ripete una, tranne che un avvio che il Player ha reinviato dopo un report non riconosciuto (lo stesso play_id, ricevuto poco dopo) può apparire di nuovo in una pagina successiva; il flusso CSV lo elenca una volta. format=csv (o Accept text/csv senza application/json) trasmette ogni riproduzione dal cursore alla fine dell’intervallo come CSV (PlaybackPlayCsv), più recente prima sotto con order=desc; limit è rifiutato con CSV.

La misurazione è per richiesta: ogni pagina JSON costa un credito richiesta API, mentre un flusso CSV dell’intervallo completo costa uno. Ogni richiesta plays (pagina o flusso) consuma i budget playback-export-org (30 al minuto) e playback-export-ip (60 al minuto).

Uno stream limita ogni scrittura (15 secondi) e termina quando il client si disconnette; se fallisce dopo l’header 200 la connessione è abortita, quindi un export che legge fino a una fine pulita è completo. Le risposte portano Vary Accept. Le riproduzioni sono conservate per la durata di conservazione eventi del piano (30 giorni è il minimo fornito; la conservazione basata sul piano usa la finestra di 7 o 90 giorni del piano).

Un chiamante limitato agli schermi (docs/screen-scope.md) deve inviare screen_id, che deve essere uno schermo dentro il suo ambito (altrimenti outside_screen_scope); le forme CSV seguono la stessa regola.

Totali di riproduzione del progetto chiamante su giorni UTC inclusivi, letti dai rollup giornalieri: by=day restituisce una riga per giorno con riproduzioni (screen_id o media_id limita a uno schermo o media), by=screen e by=media classificano gli schermi o media più attivi (top, massimo 100), e by=screen_day restituisce la serie giornaliera degli schermi top (top massimo 10). day_to predefinito oggi (UTC) e day_from 29 giorni prima.

Una serie di giorni copre al massimo 366 giorni (92 se limitata a uno schermo o media); un ranking al massimo 92. I conteggi includono ogni inizio registrato dal progetto, inclusi quelli memorizzati prima che esistessero i rollup di riproduzione.

I rollup seguono l’ingestione fino a circa 21 minuti. truncated è true quando un ranking è stato costruito da fette di una finestra troppo grande per una lettura: copre le migliori chiavi di ogni fetta. Non è limitato da rate limit. Una richiesta API conteggiata.

Un chiamante limitato agli schermi (docs/screen-scope.md) deve inviare screen_id, che deve essere uno schermo dentro il suo ambito (altrimenti outside_screen_scope); le forme CSV seguono la stessa regola.

Quante delle riproduzioni effettuate dagli schermi sono arrivate al backend e dove si trovavano quelle mancanti. I Player numerano gli avvii dei contenuti multimediali, quindi un avvio che non è mai arrivato lascia un buco nella numerazione, ad esempio quando uno schermo resta offline oltre la sua coda di report di 24 ore o la coda scarta dei report.

Nei giorni UTC da day_from a day_to inclusi (day_to è per impostazione predefinita oggi, in UTC, e day_from 29 giorni prima; la finestra copre al massimo 92 giorni) la risposta contiene measured_plays, le riproduzioni numerate arrivate; missing_plays, i numeri saltati dai Player; completeness, il rapporto tra measured_plays e la loro somma, null quando entrambi sono 0; days, gli stessi tre valori per ogni giorno che ne ha, dal più vecchio, con un buco contato nel giorno UTC della riproduzione successiva; e gaps, i buchi dal più recente, ciascuno con screen_id, day, from e to (gli orari di avvio delle riproduzioni ai due lati del buco) e missing_plays. screen_id restringe days e gaps a un solo schermo; limit (predefinito 100, al massimo 500) limita gaps, e truncated è true quando ne esistono altri.

Uno schermo spento non genera riproduzioni e non lascia lacune. Le riproduzioni senza numero (Player meno recenti, avvii memorizzati prima dei numeri di riproduzione) non vengono misurate: rientrano in play_count di GET /api/playback/totals e in nessuno di questi valori. Senza limiti di frequenza. Una richiesta API conteggiata.

Un chiamante limitato agli schermi (docs/screen-scope.md) deve inviare screen_id, che deve essere uno schermo dentro il suo ambito (altrimenti outside_screen_scope); le forme CSV seguono la stessa regola.