API Comptes de lecture

Agrégats quotidiens de lecture.

JSON retourne au plus 200 lignes et n’est pas limité en débit. format=csv (ou Accept text/csv sans application/json) diffuse chaque ligne correspondante entre day_from et day_to (jours UTC inclus ; day_to par défaut aujourd’hui et day_from 30 jours avant ; au plus 366 jours, sinon invalid_request) en CSV avec une ligne d’en-tête fixe (PlaybackAggregateCsv) ; seule la forme CSV dépense les budgets playback-export-org (30 par minute) et playback-export-ip (60 par minute).

Chaque forme est une requête d’API mesurée. Les réponses portent Vary Accept. Un appelant limité aux écrans (docs/screen-scope.md) doit envoyer screen_id, qui doit être un écran de son périmètre (sinon outside_screen_scope) ; les formes CSV suivent la même règle.

Enregistrements par lecture : une ligne par playback.media_started accepté (ou playback.video_started ancien) et une ligne par playback.application_started accepté (release_id défini, champs médias vides) du projet appelant, du plus ancien au plus récent selon received_at, égalités selon insertion. bornes from (incluse) et to (exclue) sur received_at ; to par défaut à maintenant, from à 24 heures avant to, et la plage au maximum 31 jours (sinon invalid_request).

Les 5 dernières secondes ne sont pas encore retournées : la fin effective est au plus maintenant moins 5 secondes (délai de stabilisation), donc une queue en direct ne saute jamais une ligne qui s’engage derrière son curseur. screen_id, media_id, playlist_id (la liste de lecture dont le début a été montré), et tag (une étiquette d’écran portée par l’écran lors de la réception de la lecture) filtrent.

Une page playlist_id peut contenir moins de lignes que la limite, voire aucune, avec un next_cursor quand une longue série de lectures d’autres listes a été parcourue ; null met toujours fin à la plage.

JSON est une page d'au plus limit lignes (par défaut 200, au plus 1000) avec next_cursor, null à la fin de la plage ; renvoyez-le comme cursor avec les mêmes filtres. order=desc (ou before) pagine les plus récentes en premier dans la même plage : next_cursor est alors le curseur de la ligne la plus ancienne retournée, null au début de la plage, et est renvoyé comme before (exclusif) avec les mêmes filtres ; order=asc avec before est refusé avec invalid_request nommant order, et cursor avec une page newest-first nommant cursor.

Une page la plus récente en premier peut contenir moins de lignes que la limite, voire aucune, avec un next_cursor ; null met toujours fin à la liste.

Une page ultérieure ne saute jamais une ligne qui existait lorsque la page antérieure a été lue et ne répète pas une ligne, sauf qu’un démarrage du Player renvoyé après un rapport non accusé de réception (le même play_id, reçu un instant plus tard) peut apparaître à nouveau sur une page ultérieure ; le flux CSV le liste une fois. format=csv (ou Accept text/csv sans application/json) diffuse chaque lecture du curseur à la fin de la plage en CSV (PlaybackPlayCsv), le plus récent en bas avant avec order=desc ; la limite est refusée avec CSV.

La mesure se fait par requête : chaque page JSON coûte un crédit de requête API, tandis qu’un flux CSV couvrant toute la plage en coûte un seul. Chaque requête de lectures (page ou flux) utilise les budgets playback-export-org (30 par minute) et playback-export-ip (60 par minute).

Un flux limite chaque écriture (15 secondes) et se termine à la déconnexion du client ; s’il échoue après l’en-tête 200, la connexion est interrompue, donc une exportation qui lit jusqu’à une fin propre est complète. Les réponses portent Vary Accept. Les lectures sont conservées pour la rétention d’événements du forfait (30 jours est le minimum livré ; la rétention selon le forfait utilise la fenêtre propre de 7 ou 90 jours).

Un appelant limité aux écrans (docs/screen-scope.md) doit envoyer screen_id, qui doit être un écran de son périmètre (sinon outside_screen_scope) ; les formes CSV suivent la même règle.

Totaux de lecture du projet appelant sur des jours UTC inclusifs, lus depuis les totaux quotidiens : by=day renvoie une ligne par jour avec lectures (screen_id ou media_id restreint à un écran ou média), by=screen et by=media classent les écrans ou médias les plus actifs (top, au plus 100), et by=screen_day renvoie la série journalière des écrans principaux (top au plus 10). day_to par défaut aujourd’hui (UTC) et day_from 29 jours avant.

Une série de jours couvre au maximum 366 jours (92 lorsqu’elle est restreinte à un écran ou un média) ; un classement au maximum 92. Les comptes incluent chaque démarrage enregistré par le projet, y compris ceux stockés avant l’existence des rollups de lecture.

Les rollups suivent l’ingestion jusqu’à environ 21 minutes. truncated est vrai lorsqu’un classement a été construit à partir de tranches d’une fenêtre trop grande pour une seule lecture : il couvre les meilleures clés de chaque tranche. Pas de limitation de débit. Une requête API mesurée.

Un appelant limité aux écrans (docs/screen-scope.md) doit envoyer screen_id, qui doit être un écran de son périmètre (sinon outside_screen_scope) ; les formes CSV suivent la même règle.

Parmi les lectures effectuées par les écrans, combien sont parvenues au backend, et où se situent les lectures manquantes. Les Players numérotent les débuts de lecture de leurs médias; un début qui n'est jamais arrivé laisse donc un trou dans la numérotation, par exemple lorsqu'un écran reste hors ligne au-delà de sa file de rapports de 24 heures ou que la file abandonne des rapports.

Sur les jours UTC compris entre day_from et day_to, bornes incluses (day_to vaut par défaut aujourd'hui, en UTC, et day_from 29 jours avant; la période couvre au plus 92 jours), la réponse contient measured_plays, les lectures numérotées qui sont arrivées; missing_plays, les numéros que les Players ont sautés; completeness, measured_plays divisé par leur somme, null lorsque les deux valent 0; days, les trois mêmes chiffres pour chaque jour qui en compte, du plus ancien au plus récent, un trou étant compté au jour UTC de la lecture qui le suit; et gaps, les trous du plus récent au plus ancien, chacun avec son screen_id, son day, from et to (les heures de début des lectures de part et d'autre du trou) et missing_plays. screen_id restreint days et gaps à un seul écran; limit (100 par défaut, 500 au plus) plafonne gaps, et truncated vaut true lorsqu'il en existe davantage.

Un écran éteint ne produit aucune lecture et ne laisse aucune lacune. Les lectures sans numéro (anciens Players, débuts de lecture enregistrés avant les numéros de lecture) ne sont pas mesurées : elles figurent dans play_count de GET /api/playback/totals et dans aucun de ces chiffres. Sans limite de débit. Une requête d'API mesurée.

Un appelant limité aux écrans (docs/screen-scope.md) doit envoyer screen_id, qui doit être un écran de son périmètre (sinon outside_screen_scope) ; les formes CSV suivent la même règle.