Video Central

Datensatz-API – Überblick

Die Datensatz-API ist Teil unseres neuen Partnerdatenprodukts Slate Analytics. Im Gegensatz zu anderen Slate-Berichten sind Datensätze nur als Anhang verfügbar (jede Datei enthält neue Daten). Sie können nicht über die Slate-Benutzeroberfläche heruntergeladen werden (sondern sind nur über die API zugänglich) und wurden speziell für die Data Engineers unserer Partner erstellt, um granulare Daten zu nutzen und Analysen durchzuführen. Dieses Thema hilft Data Engineers bei der Einrichtung ihrer Pipelines zum Abrufen von Datensätzen, definiert die Werte in den Datensatzdateien und bietet Beispielabfragen und Vorschläge für die optimale Verwendung dieser Daten durch die Partner.

Praktische Verwendung von Datensätzen

Wir stellen Verbrauchenden Datensätze in Form eines Änderungsprotokolls zur Verfügung. Jedes Ereignis wird nur einmal veröffentlicht. Falls aber Spaltenwerte einer bereits bereitgestellten Zeile aktualisiert werden müssen, veröffentlichen wir eine neue Version des Datensatzes. Die Änderungen werden dann in der nächsten verfügbaren Datei angezeigt. Das Änderungsprotokoll kann nur angehängt werden, um sicherzustellen, dass alle Datenänderungen erfasst werden. Data Engineers können dieses Änderungsprotokoll verwenden, um ihre Datentabellen direkt zu aktualisieren.

Wenn du das Änderungsprotokoll verarbeitest, dann solltest du immer den neuesten Datensatz für eine bestimmte event_id verwenden, basierend auf der last_update_time_utc-Spalte. Dadurch wird sichergestellt, dass du immer die aktuellste Version jedes Datensatzes hast. Wenn ein Datensatz gelöscht werden muss, wird diese Aktion in der Spalte is_deleted angegeben. Ein Wert 1 bedeutet, dass der Datensatz gelöscht wurde, während ein Wert 0 einen aktiven Datensatz darstellt. Dieser Ansatz ermöglicht es dir, neue und sich ändernde Daten effektiv zu verwalten, und stellt sicher, dass deine Datentabellen korrekt und stets auf dem neuesten Stand sind.

Einleitende Informationen zur Datensatz-API

Bevor du eine Anfrage an die Datensatz-API schickst, musst du die grundlegenden Anforderungen für die Authentifizierung und Paginierung verstehen. In diesem Abschnitt wird beschrieben, wie du sicher auf die API zugreifst und dich effizient durch umfangreiche Datensätze bewegst.

Einführung in die Analytics-API
Um Datensätze abzurufen, musst du dich zuerst in die Analytics-API-Suite einbinden. Weitere Details findest du hier.

Die Basis-URI lautet: https://videocentral.amazon.com/apis/v2. Alle Anfragen müssen ein gültiges LWA-Authentifizierungstoken im Autorisierungs-Header der Anfragen enthalten. Beispiel:

Falls der Anfrage-Header nicht das Token enthält oder dieses abgelaufen ist, gibt die Datensatz-API eine nicht autorisierte Ausnahme zurück.

Pagination
Alle Antworten der Slate-API sind paginiert. Paginierungs-Parameter werden durch Anfrage-Parameter angegeben.

Request parameter	Default value	Description
limit	10	Die Anzahl der Dokumente, die auf einer Seite zurückgegeben werden (d. h. die Seitengröße).
offset	0	Die Anzahl der Seiten, die übersprungen werden sollen (d. h. Seitenzahl).

Alle paginierten Antworten enthalten die folgenden Felder:

Field	Description
total	Die Gesamtzahl der Dokumente auf allen Seiten.
next	Die URL zur nächsten Seite. Null, wenn es die letzte Seite ist.

Verwenden der Datensatz-API

Um programmatisch auf Datensätze zuzugreifen, sollten Klienten eine Reihe von API-Aufrufen ausführen, die verfügbare Ressourcen auflisten wie Konten, Gruppen, Unternehmen und Datensätze, bevor sie herunterladbare URLs für die Datendateien abrufen. Diese Sequenz wurde zur Unterstützung der Automatisierung entwickelt und lässt sich in wiederkehrende Daten-Pipelines oder geplante Workflows integrieren.

List accounts
/v2/accounts

Diese Ressource gibt die Liste der Slate-Konten zurück, auf die der Benutzer zugreifen kann. Auf die Gruppe der Konten kann in Slate über die Dropdown-Liste Konten in der oberen rechten Ecke des Portals zugegriffen werden. Du kannst diese Links auch verwenden, um deine Konto-ID oder deine Channel/Studio_ID zu finden.

Beispiel für eine Anfrage

Beispiel für eine Antwort

List groups (business lines)
/v2/accounts{account_id}

Diese Ressource gibt die Gruppen von Geschäftsbereichen (wie Channels) zurück, auf die der Benutzer zugreifen kann.

Beispiel für eine Anfrage

Beispiel für eine Antwort

List businesses
/v2/accounts/{account_id}/{group_id}

Diese Ressource gibt eine Liste der Unternehmen (z. B. bestimmte Channel-Namen) zurück, die für dieses Konto verfügbar sind, abhängig vom jeweiligen Geschäftsbereich.

Beispiel für eine Anfrage

Beispiel für eine Antwort

List available datasets
/v2/accounts/{acccount_id}/{group_id}/{business_id}/datasets

Diese Ressource gibt die Liste der Datensätze zurück, die für einen bestimmten Channel oder ein bestimmtes Studio verfügbar sind. (Die Liste der verfügbaren Datensätze und ihrer Attribute sind in den Datensatzdefinitionen weiter unten in diesem Thema enthalten.) Die Datensätze, die derzeit zum Herunterladen verfügbar sind, sind:

Subscription: Ereignisse im Kundenlebenszyklus, z. B. wenn ein Kunde ein Abonnement abgeschlossen hat.
Playback: Spiele Sitzungsereignisse ab, bei denen sich die Kundschaft mit Inhalten beschäftigt hat.
Catalog: Ereignisse, bei denen sich deine Katalogmetadaten geändert haben, z. B. wenn ein neuer Titel hinzugefügt wurde.

Beispiel für eine Anfrage

Beispiel für eine Antwort

Obtain dataset file(s)
/v2/accounts/{account_id}/{group_id}/{business_id}/datasets/{dataset_id}

Diese Ressource bietet eine Liste von Datensatzdateien. Je nach angefordertem Zeitraum kann die Liste eine große Anzahl von Dateien enthalten. Das Feld total gibt an, wie viele Dateien zu erwarten sind. Nachdem du eine vollständige Ergänzung abgeschlossen hast, kannst du dich auf dem Laufenden halten, indem du weiterhin Dateien mit einer startDateTime, die dem Zeitstempel des letzten Abrufs entspricht, und einer endDateTime, die auf die aktuelle Uhrzeit gesetzt ist, anforderst.

Neue Datensätze werden etwa alle 4 Stunden veröffentlicht und können Ereignisse enthalten, die in den letzten 12 Stunden eingetreten sind. Wir empfehlen, unsere API mehrmals täglich etwa alle 4–6 Stunden aufzurufen, um sicherzustellen, dass deine lokalen Daten so vollständig und aktuell wie möglich sind. Falls es bei der Veröffentlichung zu Verzögerungen kommt, werden wir dies so schnell wie möglich per E-Mail mitteilen.

Die folgende Tabelle beschreibt die verfügbaren Anforderungsparameter für Datensatzdateien.

Request parameter	Description
startDateTime	Es wird empfohlen, vom Zeitpunkt der letzten Anfrage einzustellen. (Format: JJJJ-MM-TTTHH:MM:SSZ – Zeitstempel UTC)
endDateTime	Es wird empfohlen, zum Zeitpunkt der Anfrage / der aktuellen Uhrzeit einzustellen. (Format: JJJJ-MM-TTTHH:MM:SSZ – Zeitstempel UTC)
limit	Die maximale Grenze liegt bei 1000 Links pro Seite.

Hinweis: Unsere maximale Datenspeicherung beträgt 2 Jahre. Anfragen nach Datensätzen mit einem Zeitstempel, der älter als 2 Jahre ist, liefern keine Ergebnisse.

Beispiel für eine Anfrage

Beispiel für eine Antwort

Hinweise:

Die maximale ZIP-Dateigröße beträgt 300 MB. Dateien, die dieses Limit überschreiten, werden in mehrere Dateien aufgeteilt.
Die Gültigkeitsdauer (TTL) einer vorsignierten URL beträgt 60 Minuten.

Datensatzdefinitionen

In den Tabellen in diesem Abschnitt sind die Spalten, Datentypen und Definitionen für jeden der 3 verfügbaren Datensätze aufgeführt.

Subscription dataset

Column	Type	Definition
subscription_event_id (pk)	Zeichenfolge	Die eindeutige Kennung für jedes Abonnementereignis, das über dieses Protokoll verkauft wurde.
subscription_event_type	Zeichenfolge	Die Art des aufgetretenen Abonnementereignisses: Start: Der Kunde bzw. die Kundin hat einen Channel abonniert, den er bzw. sie zuvor nicht gebucht hatte. Renewal: Der Kunde bzw. die Kundin hat einen Channel abonniert und war bereits vor dem Abonnementereignis dieses Channels aktiv. Cancel: Die nutzende Person hat ihr Abonnement gekündigt. Suspend: Das Abonnement des Kunden wurde aufgrund von Zahlungsproblemen (unzureichendes Guthaben oder ungültige Rechnungsinformationen) vorübergehend ausgesetzt. Das Abonnement wird automatisch fortgesetzt und ein Verlängerungsereignis generiert, sobald der Kunde seine Rechnungsinformationen aktualisiert hat und die Zahlung erfolgreich verarbeitet wurde. Active - AR ON: Die nutzende Person ist aktiv und hat die automatische Verlängerung aktiviert. Active - AR OFF: Die nutzende Person ist aktiv, hat aber die automatische Verlängerung deaktiviert.
subscription_event_time_utc	Zeitstempel	Die Uhrzeit, zu der das Abonnementereignis eingetreten ist, standardisiert auf UTC.
subscription_event_time_zone	Zeichenfolge	Die Zeitzone des Abonnement-Marketplace.
cid	Zeichenfolge	Anonymisierte Kundenkennung (CID). Diese Kundenkennung wird für alle Ereignisse in einem einzelnen übergeordneten Channel beibehalten, um einen Stufenwechsel und den Kundenlebenszyklus nachverfolgen zu können.
offer_id	Zeichenfolge	Die ID des spezifischen Abonnementangebots, in dessen Zusammenhang das Ereignis eingetreten ist.
offer_name	Zeichenfolge	Der für Menschen lesbare Name des Angebots.
offer_type	Zeichenfolge	Die Art des Angebots.
offer_marketplace	Zeichenfolge	Der Marketplace, auf dem das Abonnementangebot live war.
offer_billing_type	Zeichenfolge	Die für das Angebot erforderliche Zahlungsart: HO: Hard Offer; Zahlung erforderlich. FT: Free Trial; keine Zahlung erforderlich.
offer_payment_amount	Zeichenfolge	Der Rechnungsbetrag der offer_id.
benefit_id	Zeichenfolge	Die Kennung des Prime-Video-Vorteils, unter dem das Angebot konfiguriert wurde.
channel_label	Zeichenfolge	Der Name des Channels, auf dem das Angebot läuft. Hinweis: Falls in dieser Spalte ein Nullwert angezeigt wird und du Bedenken hast, wende dich bitte an deinen CAM oder PsM.
channel_tier_label	Zeichenfolge	Der Name des Channels, auf dem das Angebot läuft. Hinweis: Falls in dieser Spalte ein Nullwert angezeigt wird und du Bedenken hast, wende dich bitte an deinen CAM oder PsM.
is_promo	int	Gibt an, ob ein Angebot zum Zeitpunkt der Veranstaltung Bestandteil einer Werbeaktion ist (0 = keine Werbeaktion, 1 = eine Werbeaktion).
create_time_utc	Zeitstempel	Die Uhrzeit, zu der der Ereignisprotokolldatensatz erstellt wurde, standardisiert auf UTC.
last_update_time_utc	Zeitstempel	Die Uhrzeit, zu der der Ereignisprotokolldatensatz zuletzt aktualisiert wurde, standardisiert auf UTC.
is_deleted	int	Gibt an, ob ein Datensatz, der zuvor erstellt wurde, gelöscht werden sollte (0 = beibehalten, 1 = löschen).

Playback dataset

Column	Type	Definition
session_id (pk)	Zeichenfolge	Die eindeutige Kennung für die Wiedergabesitzung.
marketplace_id	int	Die eindeutige Kennung für den Wiedergabe-Marketplace.
marketplace_desc	Zeichenfolge	Eine freundliche Beschreibung für den Wiedergabe-Marketplace.
cid	Zeichenfolge	Die Benutzerkennung, anonymisiert mit UUID.
benefit_id	Zeichenfolge	Die Vorzüge, die mit gestreamten Inhalten verbunden sind.
catalog_id	Zeichenfolge	Fremdschlüssel (FK), der zur Verknüpfung mit der Katalogtabelle verwendet wird.
subscription_offer_id	Zeichenfolge	Die subscription offer_id nutzende Person hat zum Zeitpunkt des Streams abonniert (Active oder ApprovalPending).
subscription_event_id	Zeichenfolge	Fremdschlüssel (FK), um dem Abonnement-Ereignisprotokoll beizutreten und den genauen Status der Abonnement beziehenden Person zum Zeitpunkt der Wiedergabe abzurufen (Active)
start_segment_utc	Zeitstempel	Beginn des Wiedergabesegments in UTC.
end_segment_utc	Zeitstempel	Ende des Wiedergabesegments in UTC.
seconds_viewed	int	Sekunden, die die nutzende Person während der Wiedergabe gestreamt hat.
position_start	Doppelt	Sekunde des Streams, an der die Wiedergabesitzung begann.
position_end	Doppelt	Sekunde des Streams, an der die Wiedergabesitzung endete.
connection_type	Zeichenfolge	Verbindung, die von der nutzenden Person zum Streamen der Inhalte verwendet wird.
stream_type	Zeichenfolge	Klassifizierung zwischen Video-On-Demand-, Live- oder Just After Broadcast (JAB)-Streams.
device_class	Zeichenfolge	Art des Geräts (beispielsweise Heimkinogeräte, Mobilgeräte, Web oder Sonstiges).
device_sub_class	Zeichenfolge	Granularer Gerätetyp (z. B. Spielekonsole, Smart_TV, Roku).
geo_dma	Zeichenfolge	Die dreistellige Designated Market Area (DMA) des Gebiets, in dem der Stream generiert wurde.
playback_method	Zeichenfolge	Gibt an, ob die Wiedergabe onlineoder offline erfolgt.
quality	Zeichenfolge	Wiedergabequalität (z. B. 1080p oder 4K)
event_type	Zeichenfolge	Der definierende Ereignistyp (playback_segments)
create_time_utc	Zeitstempel	Zeitstempel, als der Datensatz zur Tabelle hinzugefügt wurde, in UTC.
last_update_time_utc	Zeitstempel	Zeitstempel der letzten Aktualisierung, als der Datensatz geändert wurde, in UTC.
is_deleted	int	Markierung, die den Partnern anzeigt, ob der Datensatz in ihrem System gelöscht werden soll.

Catalog dataset

Column	Type	Definition
id (pk)	Zeichenfolge	Die eindeutige Kennung des Titels.
marketplace_id	int	Die eindeutige Kennung für den Angebots-Marketplace.
benefit_id	Zeichenfolge	Der mit dem erweiterten Inhalt verbundene Vorteil.
title	Zeichenfolge	Der Serien-/Filmtitel.
vendor_sku	Zeichenfolge	Eine zufällige Kennung, die der Anbieter für jeden seiner Filme oder Folgen generiert.
season	Ganzzahl	Die Staffelnummer (für Serienfolgen).
episode	Ganzzahl	Die Folgennummer.
episode_name	Zeichenfolge	Der Name der Folge (optional).
runtime_minutes	Ganzzahl	Die Laufzeit des angesehenen Inhalts.
live_linear_channel_name	Zeichenfolge	Der Channel-Name für Live-Inhalte.
content_type	Zeichenfolge	Entweder TV oder Movie.
content_quality	Zeichenfolge	HD oder SD
content_group	Zeichenfolge	3P_SUBS
create_time_utc	Zeitstempel	Zeitstempel, als der Datensatz zur Tabelle hinzugefügt wurde, in UTC.
last_update_time_utc	Zeitstempel	Zeitstempel der letzten Aktualisierung, als der Datensatz geändert wurde, in UTC.
is_deleted	int	Markierung, die den Partnern anzeigt, ob der Datensatz in ihrem System gelöscht werden soll.

Beispielabfragen

Das folgende SQL-Beispiel zeigt, wie die Datensatztabellen miteinander verbunden sind. Du kannst Wiedergabedaten mit dem Abonnement-Ereignisprotokoll in der Spalte subscription_event_id verknüpfen. Dies bietet den neuesten Abonnementstatus vor diesem Stream. In diesem Beispiel wird die Spalte catalog_id im Wiedergabe-Datensatz mit dem id-Feld in catalog_event_log verknüpft, um alle Katalogmetadaten bereitzustellen.

Das folgende SQL-Beispiel gibt die 10 Titel zurück, die die Kundschaft am häufigsten angesehen haben, nachdem sie ein Abonnement abgeschlossen hatten.

Beispielorchestrierung

Falls du die Datenextraktion aus der Datensatz-API nach einem wiederkehrenden Zeitplan automatisieren möchtest, zeigt das folgende Python-Beispielskript, wie du alle 6 Stunden inkrementelle API-Aufrufe tätigst. Es protokolliert den Zeitstempel der letzten erfolgreichen Anfrage, indem es ihn lokal speichert, und verwendet diesen Wert – plus eine Sekunde – als startDateTime für den nächsten Anruf. Das Skript berechnet endDateTime als aktuelle Uhrzeit, erstellt die entsprechenden Abfrageparameter und sendet eine GET-Anfrage mit Authentifizierung. Dieser Ansatz gewährleistet einen kontinuierlichen, sich nicht überschneidenden Datenabruf über Zeitfenster hinweg und kann über Cron oder einen anderen Auftragsplaner geplant werden.