API Événements du projet

Liste les événements durables du projet par ordre croissant de séquence.

La pagination est contiguë : passez le next_cursor retourné comme after pour continuer exactement là où la page s’est arrêtée. next_cursor est le curseur du dernier événement retourné tant que des événements plus récents existent déjà, et nul à la fin de l’historique. limit par défaut à 50 et accepte 1-200 ; une valeur hors plage est refusée avec invalid_request et un membre errors[] nommant limit.

Le décalage de pagination n’est pas supporté. source=log liste le journal du Player à la place : les rapports de conditions envoyés par les Players (runtime.reported) triés par heure de réception, filtrés par screen_id et gravité sur une fenêtre de à (par défaut les dernières 24 heures, au maximum 31 jours).

Ses curseurs sont opaques : lg1_ ou ev1_ selon l'endroit où le serveur garde le journal du Player, donc renvoyez celui qu'une page a retourné ; un curseur de l'autre type est refusé avec invalid_request nommant le champ. Les enregistrements du journal du Player n'ont pas de séquence, ne sont pas sur GET /stream/project et ne sont pas livrés aux webhooks.

Un enregistrement est reconnu lorsque la file d’attente du journal du lecteur l’accepte et est conservé pour la rétention d’événements du projet. Un sondage avec le dernier curseur et la fenêtre par défaut suit le journal. Les enregistrements du journal du lecteur ne figurent pas dans la liste par défaut (source=project). from et to sont refusés avec invalid_request sauf si source est log.

La liste de projets prend screen_id, playlist_id et application_id pour lire les événements d’un écran, d’une liste de lecture ou d’une application, tous limités au projet des identifiants (un id nomme quels événements lire, jamais à qui) : screen_id garde les événements dont la ressource est cet écran ; playlist_id les événements dont la ressource est cette liste de lecture plus ceux qui la nomment comme details.playlist_id (un écran la prenant) ; application_id les événements dont la ressource est cette application plus ceux dont la ressource la porte comme application_id (ses versions et entrées clé/valeur).

Une valeur qui n’est pas un identifiant de son type est refusée avec invalid_request nommant le champ ; playlist_id et application_id sont refusés avec source=log, dont les enregistrements appartiennent uniquement à un écran.

Les deux sources prennent resource_id, type et gravité (au minimum), combinés entre eux, avec les filtres d’identifiant et la pagination ; un enregistrement de journal Player est un enregistrement runtime.reported dont la ressource est son écran, donc un resource_id qui n’est pas cet écran ou un type qui exclut runtime.reported renvoie une page vide. before (ou order=desc) affiche les plus récents en premier : next_cursor est alors le curseur de l’élément le plus ancien retourné et renvoyé comme before pour continuer vers les éléments plus anciens.

Sans from, une page source=log la plus récente d’abord remonte au-delà des 24 heures par défaut jusqu’au plus ancien enregistrement que la rétention d’événements du projet conserve, au maximum 31 jours sous le bord supérieur de la page par requête. Une page source=log la plus récente d’abord peut contenir moins que limit d’enregistrements, voire aucun, avec un next_cursor ; null la termine toujours, à la fin du journal conservé.

Un appelant limité aux écrans (docs/screen-scope.md) lit un flux filtré : les événements des écrans de son périmètre, des dossiers d’écrans qu’il peut voir (les siens, ceux au-dessus et ceux à l’intérieur ; screen.moved seulement quand la destination est dans son périmètre), des campagnes, des listes de lecture, des médias, des applications et des cartes, et les révisions playlist_change.

Tout autre événement est omis, de sorte qu’une page peut contenir moins d’événements que limit, voire aucun, avec un next_cursor ; continuez la pagination avec celui-ci. source=log exige un screen_id dans son périmètre. Les événements sur le projet lui-même ne sont pas envoyés.

Flux d’écoute du projet rejouable. Les enregistrements du journal du lecteur (runtime.reported) se lisent avec GET /api/events?source=log et ne figurent pas sur ce flux. L’ouverture de cette requête coûte 1 crédit comme abonnement au flux d’écoute. Les en-têtes de crédit sont omis. Les événements facturés suivants coûtent 1 crédit chacun; screen.*, runtime.*, alert_mute.* et application.event en sont exemptés.

Les battements de cœur et le préambule de réessai ne sont jamais facturés. stream.cursor et stream.resync_required sont facturés. L’idempotence de débit est sse-event:<project_id>:<sequence>, donc la reconnexion et la relecture sont gratuites. Un événement facturé non payé n’est pas écrit et le flux se ferme.

Un flux ouvert avec une session du tableau de bord ne facture rien (ni l’ouverture ni ses événements), comme les requêtes d’API du tableau de bord ; il prend quand même l’un des emplacements de flux du projet. Un appelant limité aux écrans (docs/screen-scope.md) reçoit le même flux filtré que GET /api/events : aucune trame n’est envoyée pour un événement écarté et stream.cursor continue d’avancer la position.

Le périmètre est lu à l’ouverture du flux et l’arbre des dossiers de nouveau lors d’un événement de déplacement ou de dossier ; un périmètre réduit s’applique à un flux ouvert quand il se reconnecte.