播放计数 API

每日播放汇总。

JSON 最多返回 200 行且无速率限制。format=csv（或 Accept text/csv 无 application/json）流式传输 day_from 到 day_to（含 UTC 天；默认 day_to 为今天，day_from 为 30 天前；最多 366 天，否则 invalid_request）内所有匹配行，格式为带固定表头行的 CSV（PlaybackAggregateCsv）；仅 CSV 形式消耗 playback-export-org（每分钟 30 次）和 playback-export-ip（每分钟 60 次）预算。

两种形式都是一次计量的 API 请求。响应带有 Vary Accept。限定屏幕范围的调用方（docs/screen-scope.md）必须发送 screen_id，并且它必须是其范围内的屏幕（否则为 outside_screen_scope）；CSV 形式遵循同样的规则。

每次播放记录：调用项目中每个接受的 playback.media_started（或旧版 playback.video_started）和每个接受的 playback.application_started（设置了 release_id，媒体字段为空）各一行，按 received_at 由旧到新排序，插入时并列按顺序。from（包含）和 to（不包含）限定 received_at；to 默认为现在，from 默认为 to 之前 24 小时，范围最多 31 天（否则为 invalid_request）。

最新5秒未返回：有效结束时间最多为当前时间减5秒（结算延迟），因此实时尾部不会跳过提交在其游标后的行。筛选条件包括 screen_id、media_id、playlist_id（开始显示的播放列表）和标签（播放接收时屏幕携带的标签）。

playlist_id 页面可能包含少于限制行数的内容，甚至为空；当扫描到长时间播放其他播放列表时会有 next_cursor，null 仍表示范围结束。

JSON 是最多 limit 行（默认 200，最多 1000）的一页，带 next_cursor，范围末尾为 null；用相同过滤器传回作为 cursor。order=desc（或 before）在同一范围内按最新优先分页：next_cursor 是返回的最旧行游标，范围起始为 null，传回作为 before（排除）和相同过滤器；order=asc 搭配 before 拒绝，返回 invalid_request 并指明 order，游标带最新优先页命名 cursor。

最新优先的页面可能包含少于限制行数，甚至没有数据，但会有 next_cursor；null 表示结束。

后续页面不会跳过早先页面存在的行，也不会重复行，除非播放器在未确认报告后重新发送的开始（相同 play_id，稍后收到）可能在后续页面再次出现；CSV 流以 CSV 格式（PlaybackPlayCsv）从游标到范围结束列出每个播放，最新的在前，使用 order=desc；CSV 不接受 limit。

计量按请求计算：每个 JSON 页面消耗一个 API 请求额度，而整个范围的一个 CSV 流消耗一个。每个播放请求（页面或流）消耗 playback-export-org（每分钟 30 次）和 playback-export-ip（每分钟 60 次）预算。

流限定每次写入（15 秒），客户端断开时结束；200 头后失败则连接中止，故读取到干净结尾的导出即完整。响应携带 Vary Accept。播放保留期为计划的事件保留期（出厂为 30 天；基于计划的保留使用计划自身的 7 或 90 天窗口）。

限定屏幕范围的调用方（docs/screen-scope.md）必须发送 screen_id，并且它必须是其范围内的屏幕（否则为 outside_screen_scope）；CSV 形式遵循同样的规则。

播放调用项目在包含的 UTC 天数内的总计，从每日汇总读取：by=day 返回每天一行播放数据（screen_id 或 media_id 可缩小到单个屏幕或媒体），by=screen 和 by=media 排名最繁忙的屏幕或媒体（最多 100 个），by=screen_day 返回顶级屏幕的每日序列（最多 10 个）。day_to 默认为今天（UTC），day_from 默认为 29 天前。

日期序列最多跨 366 天（缩小到屏幕或媒体时为 92 天）；排名最多 92。计数包括项目记录的所有启动次数，包括播放汇总出现前存储的。

汇总数据在摄取后最多延迟约 21 分钟。当排名基于过大窗口的切片构建时，truncated 为 true：它覆盖每个切片的最佳键。无速率限制。一次计量的 API 请求。

限定屏幕范围的调用方（docs/screen-scope.md）必须发送 screen_id，并且它必须是其范围内的屏幕（否则为 outside_screen_scope）；CSV 形式遵循同样的规则。

屏幕产生的播放中有多少到达了后端，以及缺失的播放出现在哪里。Player 会为每次媒体播放开始编号，因此从未到达的开始记录会在编号中留下空缺，例如屏幕离线时间超出其 24 小时报告队列，或队列丢弃了报告时。

在 day_from 至 day_to（含首尾）的 UTC 日期范围内（day_to 默认为今天的 UTC 日期，day_from 默认为其之前 29 天；窗口最多跨 92 天），响应包含：measured_plays，即已到达的带编号播放；missing_plays，即 Player 跳过的编号；completeness，即 measured_plays 占二者之和的比例，二者均为 0 时为 null；days，即有数据的每一天的同样三项数字，按最早在前排列，空缺计入其后一次播放所在的 UTC 日；gaps，即按最新在前排列的空缺，每项包含其 screen_id、day、from 和 to（空缺两侧播放的开始时间）以及 missing_plays。screen_id 可将 days 和 gaps 限定到某一个屏幕；limit（默认 100，最大 500）限制 gaps 的数量，存在更多时 truncated 为 true。

关闭的屏幕不会产生播放，也不会留下缺口。没有编号的播放（较旧的 Player，以及在播放编号出现之前存储的开始记录）不参与测量：它们计入 GET /api/playback/totals 的 play_count，但不属于这些数字中的任何一项。不受速率限制。计为一次计量 API 请求。

限定屏幕范围的调用方（docs/screen-scope.md）必须发送 screen_id，并且它必须是其范围内的屏幕（否则为 outside_screen_scope）；CSV 形式遵循同样的规则。