API Eventi progetto

Elenca gli eventi duraturi del progetto in ordine crescente di sequenza

La paginazione è contigua: passa il next_cursor restituito come after per continuare esattamente da dove la pagina si è fermata. next_cursor è il cursore dell’ultimo evento restituito mentre eventi più recenti esistono già, e null alla fine della cronologia. Il limite predefinito è 50 e accetta 1-200; un valore fuori da questo intervallo è rifiutato con invalid_request e un membro errors[] che nomina limit.

L’impaginazione offset non è supportata. source=log elenca invece il log del Player: i report di condizione inviati dai Player (runtime.reported) in ordine crescente di ricezione, filtrati per screen_id e severità in una finestra da a (default ultime 24 ore, massimo 31 giorni).

I suoi cursori sono opachi: lg1_ o ev1_ a seconda di dove il server tiene il log Player, quindi restituisci quello che una pagina ha restituito; un cursore dell’altro tipo è rifiutato con invalid_request che nomina il campo. I record log Player non hanno sequenza, non sono su GET /stream/project e non sono consegnati ai webhook.

Un record è riconosciuto quando la coda del log del lettore lo accetta ed è conservato per la conservazione eventi del progetto. Segue un sondaggio con l’ultimo cursore e la finestra predefinita. I record del log del lettore non sono nella lista predefinita (source=project). from e to sono rifiutati con invalid_request a meno che source non sia log.

La lista dei progetti prende screen_id, playlist_id e application_id per leggere gli eventi di uno schermo, playlist o app, tutti limitati al progetto della credenziale (un id indica quali eventi leggere, mai di chi): screen_id mantiene gli eventi la cui risorsa è quello schermo; playlist_id gli eventi la cui risorsa è quella playlist più gli eventi che la nominano come details.playlist_id (uno schermo che la usa); application_id gli eventi la cui risorsa è quell’app più quelli la cui risorsa la porta come application_id (i suoi rilasci e voci chiave/valore).

Un valore che non è un ID del suo tipo è rifiutato con invalid_request che nomina il campo; playlist_id e application_id sono rifiutati con source=log, i cui record appartengono solo a uno schermo.

Entrambe le fonti utilizzano resource_id, tipo e gravità (minimo), combinati tra loro, con i filtri id e con la paginazione; un record di log del Player è un record runtime.reported il cui resource è il suo schermo, quindi un resource_id che non è quello schermo o un tipo che esclude runtime.reported restituisce una pagina vuota. Le pagine before (o order=desc) mostrano prima le più recenti: next_cursor è quindi il cursore dell’elemento più vecchio restituito e viene passato indietro come before per continuare con elementi più vecchi.

Senza from, una pagina source=log newest-first supera le 24 ore predefinite fino al record più vecchio conservato dal progetto, al massimo 31 giorni sotto il limite superiore della pagina per richiesta. Una pagina source=log newest-first può contenere meno di limit record, anche nessuno, con next_cursor; null la termina comunque, alla fine del log conservato.

Un chiamante limitato agli schermi (docs/screen-scope.md) legge un feed filtrato: eventi degli schermi dentro il suo ambito, delle cartelle di schermi che può vedere (le proprie, quelle sopra e quelle al loro interno; screen.moved solo quando la destinazione è dentro il suo ambito), di campagne, playlist, contenuti multimediali, applicazioni e schede, e delle revisioni playlist_change.

Ogni altro evento viene escluso, quindi una pagina può contenere meno eventi di limit, anche nessuno, con un next_cursor; continua a paginare con esso. source=log richiede uno screen_id dentro il suo ambito. Gli eventi sul progetto stesso non vengono inviati.

Flusso di ascolto del progetto con replay. I record del log del lettore (runtime.reported) si leggono con GET /api/events?source=log e non sono su questo flusso. L’apertura di questa richiesta costa 1 credito come subscribe di ascolto. Le intestazioni dei crediti sono omesse. Gli eventi fatturati successivi costano 1 credito ciascuno; screen.*, runtime.*, alert_mute.* e application.event sono esenti.

Heartbeat e preambolo retry non sono fatturati. stream.cursor e stream.resync_required sono fatturati. L’idempotenza di addebito è sse-event:<project_id>:<sequence>, quindi la riconnessione e replay sono gratuiti. Un evento fatturato non pagato non è scritto e lo stream si chiude.

Uno stream aperto con una sessione dashboard non addebita nulla (né l’apertura né i suoi eventi), come le richieste API del dashboard; occupa comunque uno degli slot stream del progetto. Un chiamante limitato agli schermi (docs/screen-scope.md) riceve lo stesso feed filtrato di GET /api/events: non viene inviato alcun frame per un evento scartato e stream.cursor continua a far avanzare la posizione.

L’ambito viene letto all’apertura dello stream e l’albero delle cartelle di nuovo a ogni evento di spostamento o di cartella; un ambito ristretto si applica a uno stream aperto quando si riconnette.