API de Conteos de reproducción

Agregados diarios de reproducción.

JSON devuelve a lo sumo 200 filas y no tiene límite de tasa. format=csv (o Accept text/csv sin application/json) transmite cada fila coincidente dentro de day_from a day_to (días UTC inclusivos; por defecto day_to hoy y day_from 30 días antes; máximo 366 días, sino invalid_request) como CSV con una fila fija de encabezado (PlaybackAggregateCsv); solo el formulario CSV consume los presupuestos playback-export-org (30 por minuto) y playback-export-ip (60 por minuto).

Cualquiera de las dos formas es una solicitud API medida. Las respuestas llevan Vary Accept. Un llamador limitado a pantallas (docs/screen-scope.md) debe enviar screen_id y debe ser una pantalla dentro de su alcance (de lo contrario outside_screen_scope); las formas CSV siguen la misma regla.

Registros por reproducción: una fila por cada playback.media_started aceptado (o playback.video_started heredado) y una fila por cada playback.application_started aceptado (release_id establecido, campos de medios vacíos) del proyecto que llama, el más antiguo primero por received_at, empates por inserción. desde (inclusive) y hasta (exclusivo) límite received_at; hasta por defecto ahora, desde hasta 24 horas antes de hasta, y el rango es como máximo 31 días (invalid_request de lo contrario).

Los últimos 5 segundos aún no se devuelven: el to efectivo es como máximo ahora menos 5 segundos (retraso de asentamiento), por lo que una cola en vivo nunca omite una fila que se compromete detrás de su cursor. Filtran screen_id, media_id, playlist_id (la lista de reproducción desde la que se mostró el inicio) y tag (una etiqueta de pantalla que la pantalla tenía cuando se recibió la reproducción).

Una página de playlist_id puede contener menos filas que el límite, incluso ninguna, con un next_cursor cuando se escaneó un largo tramo de reproducciones de otras listas; null aún termina el rango.

JSON es una página de a lo sumo limit filas (por defecto 200, máximo 1000) con next_cursor, null al final del rango; devuélvalo como cursor con los mismos filtros. order=desc (o before) pagina los más nuevos primero dentro del mismo rango: next_cursor es entonces el cursor de la fila más antigua devuelta, null al inicio del rango, y se devuelve como before (exclusivo) con los mismos filtros; order=asc con before se rechaza con invalid_request nombrando order, y cursor con una página newest-first nombrando cursor.

Una página con lo más nuevo primero puede contener menos filas que el límite, incluso ninguna, con un next_cursor; null aún termina la lista.

Una página posterior nunca omite una fila que existía cuando se leyó la página anterior y no repite una, excepto que un inicio que el Player reenvió tras un reporte no reconocido (el mismo play_id, recibido un momento después) puede aparecer de nuevo en una página posterior; el flujo CSV la lista una vez. format=csv (o Aceptar text/csv sin application/json) transmite cada reproducción desde el cursor hasta el final del rango como CSV (PlaybackPlayCsv), más recientes primero abajo antes con order=desc; se rechaza limit con CSV.

La medición es por solicitud: cada página JSON cuesta un crédito de solicitud API, mientras que un flujo CSV de todo el rango cuesta uno. Cada solicitud de reproducciones (página o flujo) consume los presupuestos playback-export-org (30 por minuto) y playback-export-ip (60 por minuto).

Un flujo delimita cada escritura (15 segundos) y termina cuando el cliente se desconecta; si falla después del encabezado 200, la conexión se aborta, por lo que una exportación que lee hasta un final limpio está completa. Las respuestas llevan Vary Accept. Las reproducciones se mantienen por la retención de eventos del plan (30 días es el mínimo entregado; la retención basada en el plan usa la ventana propia de 7 o 90 días del plan).

Un llamador limitado a pantallas (docs/screen-scope.md) debe enviar screen_id y debe ser una pantalla dentro de su alcance (de lo contrario outside_screen_scope); las formas CSV siguen la misma regla.

Totales de reproducción del proyecto que llama durante días UTC inclusivos, leídos de los resúmenes diarios: by=day devuelve una fila por día con reproducciones (screen_id o media_id lo limita a una pantalla o medio), by=screen y by=media clasifican las pantallas o medios más activos (top, máximo 100), y by=screen_day devuelve la serie diaria de las pantallas principales (top máximo 10). day_to por defecto es hoy (UTC) y day_from 29 días antes.

Una serie de días abarca como máximo 366 días (92 cuando se limita a una pantalla o medio); un ranking como máximo 92. Los conteos incluyen cada inicio que el proyecto ha registrado, incluidos los almacenados antes de que existieran los rollups de reproducción.

Los rollups siguen la ingestión hasta aproximadamente 21 minutos. truncated es verdadero cuando un ranking se construyó a partir de fragmentos de una ventana demasiado grande para una lectura: cubre las mejores claves de cada fragmento. No tiene límite de tasa. Una solicitud de API medida.

Un llamador limitado a pantallas (docs/screen-scope.md) debe enviar screen_id y debe ser una pantalla dentro de su alcance (de lo contrario outside_screen_scope); las formas CSV siguen la misma regla.

Cuántas de las reproducciones que realizaron las pantallas llegaron al backend y dónde estaban las que no llegaron. Los Players numeran los inicios de sus elementos multimedia, así que un inicio que nunca llegó deja un hueco en la numeración, por ejemplo cuando una pantalla permanece sin conexión más allá de su cola de informes de 24 horas o la cola descarta informes.

En los días UTC inclusivos de day_from a day_to (day_to es por defecto hoy, en UTC, y day_from 29 días antes; la ventana abarca como máximo 92 días), la respuesta contiene measured_plays, las reproducciones numeradas que llegaron; missing_plays, los números que los Players omitieron; completeness, measured_plays dividido entre su suma, null cuando ambos son 0; days, las mismas tres cifras de cada día que tenga alguna reproducción medida o faltante, del más antiguo al más reciente, con un hueco contado en el día UTC de la reproducción que le sigue; y gaps, los huecos del más reciente al más antiguo, cada uno con su screen_id, su day, from y to (las horas de inicio de las reproducciones a cada lado del hueco) y missing_plays. screen_id limita days y gaps a una pantalla; limit (100 por defecto, máximo 500) establece el máximo de gaps, y truncated es true cuando hay más.

Una pantalla apagada no realiza reproducciones ni deja huecos. Las reproducciones sin número (Players antiguos, inicios almacenados antes de los números de reproducción) no se miden: están en play_count de GET /api/playback/totals y en ninguna de estas cifras. Sin límite de frecuencia. Una solicitud de API medida.

Un llamador limitado a pantallas (docs/screen-scope.md) debe enviar screen_id y debe ser una pantalla dentro de su alcance (de lo contrario outside_screen_scope); las formas CSV siguen la misma regla.