再生回数 API

毎日の再生集計。

JSONは最大200行を返し、レート制限はありません。format=csv（またはAccept text/csvでapplication/jsonなし）はday_fromからday_toまでの一致する行をすべてCSVでストリームし、固定ヘッダー行（PlaybackAggregateCsv）付きです。day_toはデフォルトで今日、day_fromは30日前、最大366日、それ以外はinvalid_requestです。CSV形式のみplayback-export-org（1分あたり30）とplayback-export-ip（1分あたり60）の予算を消費します。

どちらの形式も、計測される API リクエスト1回です。レスポンスには Vary Accept が付きます。スクリーンに限定された呼び出し元（docs/screen-scope.md）は screen_id を送信する必要があり、それはスコープ内のスクリーンでなければなりません（そうでない場合は outside_screen_scope）。CSV形式にも同じルールが適用されます。

再生ごとの記録：呼び出しプロジェクトの受理されたplayback.media_started（またはレガシーplayback.video_started）ごとに1行、受理されたplayback.application_started（release_idセット、メディアフィールドは空）ごとに1行、最古順にreceived_atで、同順位は挿入順。from（含む）とto（除く）はreceived_atを境界とし、toはデフォルトで現在、fromはtoの24時間前、範囲は最大31日（そうでなければinvalid_request）。

最新の5秒はまだ返されません：有効な終了時刻は最大で現在時刻から5秒引いたもの（遅延解消）です。ライブテイルはカーソルの後ろでコミットされた行をスキップしません。screen_id、media_id、playlist_id（開始が表示されたplaylist）、タグ（再生受信時のスクリーンタグ）でフィルターします。

playlist_idページは制限行数未満、またはゼロの場合もあります。長期間他のプレイリストの再生がスキャンされた場合はnext_cursor。nullは範囲の終了を示します。

JSONは最大limit行（デフォルト200、最大1000）のページでnext_cursorを持ち、範囲の終わりでnullです。同じフィルターでカーソルとして返してください。order=desc（またはbefore）は同じ範囲内で最新を先にページングし、next_cursorは返された最古行のカーソルで範囲の開始でnull、before（排他）として同じフィルターで返します。order=ascとbeforeはinvalid_requestでorder名付きで拒否され、最新優先ページのカーソルはcursor名付きで拒否されます。

最新順ページは、制限行数未満、またはゼロの場合もあり、next_cursor を含みます。null は終了を示します。

後のページは、前のページで存在した行をスキップせず、繰り返しもしません。ただし、未確認レポート後にPlayerが再送した開始（同じplay_id、直後に受信）は後のページに再度現れることがあります。CSVストリームは範囲のカーソルから末尾までのすべての再生をCSV（PlaybackPlayCsv）で新しい順にリストします。format=csv（またはapplication/jsonなしのAccept text/csv）はCSVでストリームし、limitは拒否されます。

メータリングはリクエストごとです：各 JSON ページは API リクエストクレジットを1つ消費し、範囲全体の CSV ストリームは1つ消費します。すべての再生リクエスト（ページまたはストリーム）は playback-export-org（1分あたり30）と playback-export-ip（1分あたり60）の予算を消費します。

ストリームは各書き込みを15秒で区切り、クライアント切断で終了します。200ヘッダー後に失敗すると接続は中止されるため、正常終了まで読み取ったエクスポートは完了です。レスポンスは Vary Accept を含みます。再生はプランのイベント保持期間（出荷時は30日、プランベースは7日または90日）で保持されます。

スクリーンに限定された呼び出し元（docs/screen-scope.md）は screen_id を送信する必要があり、それはスコープ内のスクリーンでなければなりません（そうでない場合は outside_screen_scope）。CSV形式にも同じルールが適用されます。

呼び出しプロジェクトのUTC日単位の再生合計。日別集計から読み込み：by=dayは日ごと1行（screen_idまたはmedia_idで1スクリーンまたは1メディアに絞り込み）、by=screenとby=mediaは最も多いスクリーンまたはメディアをランク付け（最大100）、by=screen_dayはトップスクリーンの日系列（最大10）。day_toは今日（UTC）デフォルト、day_fromは29日前。

日系列は最大366日（スクリーンまたはメディアに絞ると92日）、ランキングは最大92です。カウントにはプレイロールアップが存在する前に記録された開始も含まれます。

ロールアップは取り込み後最大約21分遅れます。truncated が true の場合は、ウィンドウのスライスが1回の読み取りに大きすぎてランキングが構築されたことを示します：各スライスの最良キーをカバーします。レート制限なし。1回のメーター付きAPIリクエスト。

スクリーンに限定された呼び出し元（docs/screen-scope.md）は screen_id を送信する必要があり、それはスコープ内のスクリーンでなければなりません（そうでない場合は outside_screen_scope）。CSV形式にも同じルールが適用されます。

スクリーンが行った再生のうち、バックエンドに届いた数と、届かなかった再生の場所を示します。プレーヤーはメディアの再生開始に番号を付けるため、届かなかった開始があると番号に欠番が生じます。たとえば、スクリーンが24時間のレポートキューを超えてオフラインのままだった場合や、キューがレポートを破棄した場合です。

day_from から day_to まで（両端を含む）の UTC の日について、応答には次の値が含まれます。day_to のデフォルトは UTC の今日、day_from のデフォルトはその29日前で、期間は最大92日です。measured_plays は届いた番号付きの再生の数、missing_plays はプレーヤーが飛ばした番号の数、completeness は measured_plays を両者の合計で割った値（両方が 0 の場合は null）、days は該当する日ごとの同じ3つの値（古い順で、欠番はその直後の再生の UTC 日に数えます）、gaps は欠番を新しい順に並べたもので、それぞれ screen_id、day、from と to（欠番の前後にある再生の開始時刻）、missing_plays を持ちます。screen_id を指定すると days と gaps が1つのスクリーンに絞り込まれます。limit（デフォルト100件、最大500件）は gaps の件数を制限し、さらにある場合は truncated が true になります。

オフになっているスクリーンは再生を行わず、欠番も生じません。番号のない再生（古いプレーヤー、再生番号の導入前に保存された再生開始）は計測されません。これらは GET /api/playback/totals の play_count には含まれますが、ここに示す数値のいずれにも含まれません。レート制限はありません。従量課金の API リクエスト1件として計上されます。

スクリーンに限定された呼び出し元（docs/screen-scope.md）は screen_id を送信する必要があり、それはスコープ内のスクリーンでなければなりません（そうでない場合は outside_screen_scope）。CSV形式にも同じルールが適用されます。