Wiedergabezahlen-API

Tägliche Wiedergabeaggregate.

JSON gibt höchstens 200 Zeilen zurück und ist nicht rate-limitiert. format=csv (oder Accept text/csv ohne application/json) streamt jede passende Zeile innerhalb von day_from bis day_to (einschließlich UTC-Tage; Standard day_to heute und day_from 30 Tage früher; höchstens 366 Tage, sonst invalid_request) als CSV mit einer festen Kopfzeile (PlaybackAggregateCsv); nur die CSV-Form verbraucht die Budgets playback-export-org (30 pro Minute) und playback-export-ip (60 pro Minute).

Beide Formen sind eine gemessene API-Anfrage. Antworten tragen Vary Accept. Ein auf Bildschirme beschränkter Aufrufer (docs/screen-scope.md) muss screen_id senden, und es muss ein Bildschirm innerhalb seines Bereichs sein (sonst outside_screen_scope); die CSV-Formen folgen derselben Regel.

Pro Wiedergabeaufzeichnung: eine Zeile pro akzeptiertem playback.media_started (oder veraltetem playback.video_started) und eine Zeile pro akzeptiertem playback.application_started (release_id gesetzt, Medienfelder leer) des aufrufenden Projekts, älteste zuerst nach received_at, bei Gleichstand nach Einfügung. Von (einschließlich) und bis (ausschließlich) begrenzt received_at; bis standardmäßig jetzt, von bis 24 Stunden vor bis, und der Bereich beträgt höchstens 31 Tage (sonst invalid_request).

Die neuesten 5 Sekunden werden noch nicht zurückgegeben: Das effektive Ende ist höchstens jetzt minus 5 Sekunden (settle lag), sodass ein Live-Tail niemals eine hinter seinem Cursor liegende Zeile überspringt. Gefiltert werden screen_id, media_id, playlist_id (die Playlist, von der der Start angezeigt wurde) und tag (ein Bildschirm-Tag, den der Bildschirm beim Empfang der Wiedergabe trug).

Eine playlist_id-Seite kann weniger als limit Zeilen enthalten, sogar keine, mit einem next_cursor, wenn ein langer Abschnitt von Wiedergaben anderer Playlists durchsucht wurde; null beendet dennoch den Bereich.

JSON ist eine Seite mit höchstens limit Zeilen (Standard 200, höchstens 1000) mit next_cursor, null am Ende des Bereichs; geben Sie ihn mit denselben Filtern als cursor zurück. order=desc (oder before) zeigt innerhalb desselben Bereichs die neuesten zuerst: next_cursor ist dann der Cursor der ältesten zurückgegebenen Zeile, null am Anfang des Bereichs, und wird als before (exklusiv) mit denselben Filtern zurückgegeben; order=asc mit before wird mit invalid_request abgelehnt, das order nennt, und cursor mit einer newest-first-Seite nennt cursor.

Eine nach Neuheit sortierte Seite kann weniger als die Limit-Zeilen enthalten, sogar keine, mit einem next_cursor; null beendet sie dennoch.

Eine spätere Seite überspringt niemals eine Zeile, die beim Lesen der früheren Seite existierte, und wiederholt keine, außer dass ein Start, den der Player nach einem nicht bestätigten Bericht erneut sendete (die gleiche play_id, kurz danach empfangen), auf einer späteren Seite erneut erscheinen kann; der CSV-Stream listet sie einmal auf. format=csv (oder Accept text/csv ohne application/json) streamt jeden Play vom Cursor bis zum Ende des Bereichs als CSV (PlaybackPlayCsv), neueste zuerst unten vor mit order=desc; Limit wird mit CSV abgelehnt.

Die Abrechnung erfolgt pro Anfrage: Jede JSON-Seite kostet einen API-Anfrage-Credit, während ein CSV-Stream des gesamten Bereichs einen kostet. Jede Abfrage für Wiedergaben (Seite oder Stream) verbraucht die Budgets playback-export-org (30 pro Minute) und playback-export-ip (60 pro Minute).

Ein Stream begrenzt jeden Schreibvorgang (15 Sekunden) und endet, wenn der Client die Verbindung trennt; schlägt er nach dem 200-Header fehl, wird die Verbindung abgebrochen, sodass ein Export, der bis zum sauberen Ende liest, vollständig ist. Antworten enthalten Vary Accept. Wiedergaben werden für die Ereignisaufbewahrung des Plans aufbewahrt (30 Tage sind der ausgelieferte Mindestwert; planbasierte Aufbewahrung verwendet das eigene 7- oder 90-Tage-Fenster des Plans).

Ein auf Bildschirme beschränkter Aufrufer (docs/screen-scope.md) muss screen_id senden, und es muss ein Bildschirm innerhalb seines Bereichs sein (sonst outside_screen_scope); die CSV-Formen folgen derselben Regel.

Wiedergabesummen des aufrufenden Projekts über inklusive UTC-Tage, gelesen aus den Tageszusammenfassungen: by=day gibt eine Zeile pro Tag mit Wiedergaben zurück (screen_id oder media_id schränkt auf einen Bildschirm oder ein Medium ein), by=screen und by=media sortieren die meistgenutzten Bildschirme oder Medien (Top, höchstens 100), und by=screen_day gibt die Tagesreihe der Top-Bildschirme zurück (Top höchstens 10). day_to standardmäßig heute (UTC) und day_from 29 Tage davor.

Eine Tagesreihe umfasst höchstens 366 Tage (92 bei Eingrenzung auf einen Bildschirm oder Medien); ein Ranking höchstens 92. Die Zählungen umfassen jeden Start, den das Projekt aufgezeichnet hat, einschließlich der vor der Einführung von Play-Rollups gespeicherten.

Rollups folgen der Erfassung um bis zu etwa 21 Minuten. truncated ist true, wenn ein Ranking aus Ausschnitten eines Fensters erstellt wurde, das zu groß für einen Lesevorgang ist: Es umfasst die besten Schlüssel jedes Ausschnitts. Nicht rate-limitiert. Eine gemessene API-Anfrage.

Ein auf Bildschirme beschränkter Aufrufer (docs/screen-scope.md) muss screen_id senden, und es muss ein Bildschirm innerhalb seines Bereichs sein (sonst outside_screen_scope); die CSV-Formen folgen derselben Regel.

Wie viele der von den Bildschirmen gemachten Wiedergaben das Backend erreicht haben und wo die fehlenden lagen. Player nummerieren ihre Medienstarts, sodass ein Start, der nie angekommen ist, eine Lücke in der Nummerierung hinterlässt, zum Beispiel wenn ein Bildschirm über die 24 Stunden seiner Berichtswarteschlange hinaus offline bleibt oder die Warteschlange Berichte verwirft.

Für die UTC-Tage day_from bis day_to (jeweils einschließlich; day_to ist standardmäßig heute, UTC, und day_from 29 Tage davor; der Zeitraum umfasst höchstens 92 Tage) enthält die Antwort measured_plays, die nummerierten Wiedergaben, die angekommen sind; missing_plays, die Nummern, die die Player übersprungen haben; completeness, measured_plays geteilt durch ihre Summe, null, wenn beide 0 sind; days, dieselben drei Zahlen für jeden Tag, der welche hat, älteste zuerst, wobei eine Lücke am UTC-Tag der darauffolgenden Wiedergabe gezählt wird; und gaps, die Lücken, neueste zuerst, jeweils mit screen_id, day, from und to (den Startzeiten der Wiedergaben auf beiden Seiten der Lücke) sowie missing_plays. screen_id schränkt days und gaps auf einen Bildschirm ein; limit (standardmäßig 100, höchstens 500) begrenzt gaps, und truncated ist true, wenn mehr vorhanden sind.

Ein ausgeschalteter Bildschirm erzeugt keine Wiedergaben und hinterlässt keine Lücke. Wiedergaben ohne Nummer (ältere Player, Starts, die vor den Wiedergabenummern gespeichert wurden) werden nicht gemessen: Sie sind in play_count von GET /api/playback/totals enthalten und in keiner dieser Zahlen. Keine Ratenbegrenzung. Eine abgerechnete API-Anfrage.

Ein auf Bildschirme beschränkter Aufrufer (docs/screen-scope.md) muss screen_id senden, und es muss ein Bildschirm innerhalb seines Bereichs sein (sonst outside_screen_scope); die CSV-Formen folgen derselben Regel.