API de Contagens de reprodução

Agregados diários de reprodução.

JSON retorna no máximo 200 linhas e não tem limite de taxa. format=csv (ou Accept text/csv sem application/json) transmite cada linha correspondente dentro de day_from a day_to (dias UTC inclusivos; padrão day_to hoje e day_from 30 dias antes; no máximo 366 dias, caso contrário invalid_request) como CSV com uma linha de cabeçalho fixa (PlaybackAggregateCsv); somente o formato CSV consome os orçamentos playback-export-org (30 por minuto) e playback-export-ip (60 por minuto).

Qualquer uma das formas é uma requisição de API medida. As respostas trazem Vary Accept. Um chamador limitado a telas (docs/screen-scope.md) deve enviar screen_id, e ele deve ser uma tela dentro do seu escopo (caso contrário, outside_screen_scope); as formas CSV seguem a mesma regra.

Registros por reprodução: uma linha por playback.media_started aceito (ou playback.video_started legado) e uma linha por playback.application_started aceito (release_id definido, campos de mídia vazios) do projeto solicitante, do mais antigo para o mais recente por received_at, empates por inserção. from (inclusivo) e to (exclusivo) delimitam received_at; to padrão é agora, from é 24 horas antes de to, e o intervalo é no máximo 31 dias (invalid_request caso contrário).

Os últimos 5 segundos ainda não são retornados: o effective to é no máximo agora menos 5 segundos (atraso de estabilização), então uma cauda ao vivo nunca pula uma linha que se compromete atrás do seu cursor. screen_id, media_id, playlist_id (a playlist de onde o início foi mostrado) e tag (uma tag da tela quando a reprodução foi recebida) filtram.

Uma página de playlist_id pode conter menos que o limite de linhas, até nenhuma, com next_cursor quando um longo trecho de reproduções de outras playlists foi escaneado; null ainda encerra o intervalo.

JSON é uma página de no máximo limit linhas (padrão 200, no máximo 1000) com next_cursor, null no fim do intervalo; devolva como cursor com os mesmos filtros. order=desc (ou before) pagina os mais novos primeiro dentro do mesmo intervalo: next_cursor é então o cursor da linha mais antiga retornada, null no início do intervalo, e é devolvido como before (exclusivo) com os mesmos filtros; order=asc com before é recusado com invalid_request nomeando order, e cursor com uma página newest-first nomeando cursor.

Uma página mais recente pode conter menos que o limite de linhas, até nenhuma, com um next_cursor; null ainda encerra.

Uma página posterior nunca pula uma linha que existia quando a página anterior foi lida e não repete uma, exceto que um início que o Player reenviou após um relatório não reconhecido (o mesmo play_id, recebido um momento depois) pode aparecer novamente em uma página posterior; o fluxo CSV lista isso uma vez. format=csv (ou Accept text/csv sem application/json) transmite cada reprodução do cursor até o fim do intervalo como CSV (PlaybackPlayCsv), mais recentes primeiro abaixo antes com order=desc; limite é recusado com CSV.

A medição é por requisição: cada página JSON custa um crédito de requisição API, enquanto um fluxo CSV de toda a faixa custa um. Cada requisição de plays (página ou fluxo) consome os orçamentos playback-export-org (30 por minuto) e playback-export-ip (60 por minuto).

Um stream limita cada escrita (15 segundos) e termina quando o cliente desconecta; se falhar após o cabeçalho 200 a conexão é abortada, então uma exportação que lê até um fim limpo está completa. Respostas carregam Vary Accept. As reproduções são mantidas pelo período de retenção de eventos do plano (30 dias é o mínimo padrão; retenção baseada no plano usa a janela própria de 7 ou 90 dias).

Um chamador limitado a telas (docs/screen-scope.md) deve enviar screen_id, e ele deve ser uma tela dentro do seu escopo (caso contrário, outside_screen_scope); as formas CSV seguem a mesma regra.

Totais de reprodução do projeto solicitante por dias UTC inclusivos, lidos dos resumos diários: by=day retorna uma linha por dia com reproduções (screen_id ou media_id limita a uma tela ou mídia), by=screen e by=media classificam as telas ou mídias mais ativas (top, no máximo 100), e by=screen_day retorna a série diária das telas principais (top no máximo 10). day_to padrão é hoje (UTC) e day_from é 29 dias antes.

Uma série de dias abrange no máximo 366 dias (92 quando restrita a uma tela ou mídia); um ranking no máximo 92. As contagens incluem todos os inícios que o projeto registrou, incluindo os armazenados antes da existência dos rollups de reprodução.

Rollups seguem a ingestão por até cerca de 21 minutos. truncated é verdadeiro quando um ranking foi construído a partir de fatias de uma janela muito grande para uma leitura: cobre as melhores chaves de cada fatia. Não tem limite de taxa. Uma solicitação de API medida.

Um chamador limitado a telas (docs/screen-scope.md) deve enviar screen_id, e ele deve ser uma tela dentro do seu escopo (caso contrário, outside_screen_scope); as formas CSV seguem a mesma regra.

Quantas das reproduções feitas pelas telas chegaram ao backend e onde estavam as que faltaram. Os players numeram os inícios de mídia, então um início que nunca chegou deixa uma lacuna na numeração, por exemplo quando uma tela fica offline além da fila de relatórios de 24 horas ou a fila descarta relatórios.

Nos dias UTC de day_from a day_to, inclusive (day_to tem como padrão hoje, em UTC, e day_from, 29 dias antes dele; a janela abrange no máximo 92 dias), a resposta traz measured_plays, as reproduções numeradas que chegaram; missing_plays, os números que os players pularam; completeness, measured_plays dividido pela soma dos dois, null quando ambos são 0; days, os mesmos três números para cada dia que tiver algum, mais antigos primeiro, com a lacuna contada no dia UTC da reprodução seguinte; e gaps, as lacunas mais recentes primeiro, cada uma com seu screen_id, seu day, from e to (os horários de início das reproduções de cada lado dela) e missing_plays. screen_id restringe days e gaps a uma tela; limit (padrão 100, no máximo 500) limita gaps, e truncated é true quando existem mais.

Uma tela desligada não gera reproduções e não deixa lacunas. Reproduções sem número (players mais antigos, inícios armazenados antes dos números de reprodução) não são medidas: estão em play_count de GET /api/playback/totals e em nenhum destes números. Sem limite de taxa. Uma requisição de API medida.

Um chamador limitado a telas (docs/screen-scope.md) deve enviar screen_id, e ele deve ser uma tela dentro do seu escopo (caso contrário, outside_screen_scope); as formas CSV seguem a mesma regra.