Video Central

Übersicht über die Datensatz-API

Die Datasets API ist Teil unseres neuen Partnerdatenprodukts Slate Analytics. Im Gegensatz zu anderen Slate-Berichten können Datensätze nur angehängt werden (jede Datei enthält neue Daten), stehen in der Slate-Benutzeroberfläche nicht zum Herunterladen zur Verfügung (sondern sind nur über die API zugänglich) und wurden explizit für Datentechniker von Partnern erstellt, um detaillierte Daten zu verarbeiten und Analysen durchzuführen. Dieses Thema hilft Dateningenieuren 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 Partner.

Praktische Verwendung von Datensätzen

Wir stellen Verbrauchern Datensätze in Form eines Changelogs zur Verfügung. Jede Veranstaltung wird nur einmal veröffentlicht. Wenn jedoch Spaltenwerte für eine zuvor bereitgestellte Zeile aktualisiert werden müssen, veröffentlichen wir eine neue Version des Datensatzes, um die Änderungen in Ihrer nächsten verfügbaren Datei widerzuspiegeln. Das Changelog dient nur zum Anhängen, um sicherzustellen, dass alle Datenänderungen erfasst werden. Dateningenieure können dieses Changelog verwenden, um ihre Datentabellen direkt zu aktualisieren.

Wenn Sie das Changelog verarbeiten, ist es wichtig, immer den neuesten Datensatz für eine bestimmte event_id zu verwenden, der auf der last_update_time_utc-Spalte basiert. Dadurch wird sichergestellt, dass Sie immer über die aktuellste Version jedes Datensatzes verfügen. Wenn ein Datensatz gelöscht werden muss, spiegelt sich diese Aktion in der Spalte is_deleted wider. Ein Wert von 1 gibt an, dass der Datensatz gelöscht wurde, während ein Wert von 0 für einen aktiven Datensatz steht. Dieser Changelog-Ansatz ermöglicht es Ihnen, neue und sich ändernde Daten effektiv zu verwalten und stellt sicher, dass Ihre Datentabellen korrekt und auf dem neuesten Stand bleiben.

Vorläufige Informationen zur Datensatz-API

Bevor Sie Anfragen an die Dataset-API stellen, ist es wichtig, die grundlegenden Anforderungen für Authentifizierung und Paginierung zu verstehen. In diesem Abschnitt erfahren Sie, wie Sie sicher auf die API zugreifen und große Datensätze effizient verwalten können.

Onboarding in die Datasets API
Um Datensätze abzurufen, müssen Sie zuerst die Datasets API-Suite nutzen. Weitere Einzelheiten finden Sie hier.

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

Wenn der Anforderungsheader das Token nicht enthält oder wenn das Token abgelaufen ist, gibt die Datasets-API eine nicht autorisierte Ausnahme zurück.

Paginierung
Alle Slate-API-Antworten sind paginiert. Paginierungsparameter werden durch Anforderungsparameter angegeben.

Anforderungsparameter	Standardwert	Description
Limit	10	Die Anzahl der auf einer einzelnen Seite zurückgegebenen Dokumente (die Seitengröße).
Offset	0	Die Anzahl der zu überspringenden Seiten (die Seitennummer).

Alle paginierten Antworten enthalten die folgenden Felder.

Feld	Description
insgesamt	Die Gesamtzahl der Dokumente auf allen Seiten.
als nächstes	Die URL zur nächsten Seite. Null, wenn die letzte Seite ist.

Verwenden Sie die Datasets API

Um programmgesteuert auf Datensätze zuzugreifen, sollten Kunden einer Reihe von API-Aufrufen folgen, die verfügbare Ressourcen — wie Konten, Gruppen, Unternehmen und Datensätze — auflisten, bevor sie herunterladbare URLs für die Datendateien abrufen. Diese sequence wurde zur Unterstützung der Automatisierung entwickelt und kann in wiederkehrende Datenpipelines oder geplante Workflows integriert werden.

Konten auflisten
/v2/accounts

Diese Ressource gibt die Liste der Slate-Konten zurück, auf die der Benutzer zugreifen kann. Auf die Kontogruppe kann in Slate über die Dropdownliste der Konten in der oberen rechten Ecke des Portals zugegriffen werden. Sie können diese Links auch verwenden, um Ihre Account-ID oder Ihre Channel/Studio-ID zu finden.

Beispiel für eine Anfrage

Beispiel für eine Antwort

Gruppen (Geschäftsbereiche) auflisten
/v2/accounts/ {account_id}

Diese Ressource gibt die Gruppen von Geschäftsbereichen (z. B. Kanäle) zurück, auf die der Benutzer zugreifen kann.

Beispiel für eine Anfrage

Beispiel für eine Antwort

Unternehmen auflisten
/v2/accounts/ {account_id}/{group_id}

Diese Ressource gibt je nach Geschäftsbereich eine Liste von Unternehmen (z. B. bestimmte Kanalnamen) zurück, die für dieses Konto verfügbar sind.

Beispiel für eine Anfrage

Beispiel für eine Antwort

Verfügbare Datensätze auflisten
/v2/accounts/ {acccount_id}/{group_id}/{business_id} /datasets Diese Ressource gibt die Liste der für einen bestimmten Kanal oder ein bestimmtes Studio verfügbaren Datensätze zurück

. (Die Liste der verfügbaren Datensätze und ihrer Attribute finden Sie in den Datensatzdefinitionen weiter unten in diesem Thema.) Derzeit stehen folgende Datensätze zum Herunterladen zur Verfügung:

Abonnement: Ereignisse im Kundenlebenszyklus, z. B. wenn ein Kunde ein Abonnement abgeschlossen hat.
Wiedergabe: Wiedergeben von Sitzungsereignissen, bei denen Kunden mit Inhalten interagiert haben.
Katalog: Ereignisse, bei denen sich Ihre Katalog-Metadaten geändert haben, z. B. wenn ein neuer Titel hinzugefügt wurde.

Beispiel für eine Anfrage

Beispiel für eine Antwort

Datensatzdatei (en) abrufen
/v2/accounts/ {account_id}/{group_id}/{business_id} /datasets/ {dataset_id} Diese Ressource stellt eine Liste von Datensatzdateien bereit.

Je nach angefordertem Zeitraum kann die Liste eine große Anzahl von Dateien enthalten. Das Gesamtfeld gibt an, wie viele Dateien zu erwarten sind. Nachdem Sie einen vollständigen Backfill abgeschlossen haben, können Sie auf dem Laufenden bleiben, indem Sie weiterhin Dateien mit einem StartDateTime-Wert anfordern, der dem zuletzt abgerufenen Zeitstempel entspricht, und einem EndDateTime-Wert, der auf die aktuelle Uhrzeit gesetzt ist.

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

In der folgenden Tabelle werden die verfügbaren Anforderungsparameter für Datensatzdateien beschrieben.

Parameter anfordern	Description
StartDateTime	Es wird empfohlen, den Wert vom letzten Abruf festzulegen. (Format: YYYY-MM-DDTHH:MM:SSZ - Zeitstempel UTC)
Enddatum/Uhrzeit	Es wird empfohlen, die Einstellung zum Zeitpunkt des Abrufens/zum aktuellen Zeitpunkt festzulegen. (Format: YYYY-MM-DDTHH:MM:SSZ - Zeitstempel UTC)
Grenze	Die maximale Grenze liegt bei 1000 Links pro Seite.

Hinweis: Unsere maximale Datenspeicherung beträgt 2 Jahre. Anfragen nach Datensätzen, deren Zeitstempel vor 2 Jahren liegt, führen zu keinen Ergebnissen.

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) der vordefinierten URL beträgt 60 Minuten.

Datensatzdefinitionen

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

Abonnement-Datensatz

Spalte	Type	Definition
Abonnement-Event-ID (pk)	Zeichenfolge	Die eindeutige ID für jedes Abonnementereignis, das über dieses Protokoll verkauft wird.
Veranstaltungstyp des Abonnements	Zeichenfolge	Die type des aufgetretenen Abonnementereignisses: Start: Der Kunde hat einen Kanal abonniert, den er zuvor nicht abonniert hatte. Verlängerung: Der Kunde hat einen Kanal abonniert und war vor dem Abonnement-Event bereits für diesen Kanal aktiv. Kündigen: Der Kunde hat sein Abonnement gekündigt. Sperren: Das Abonnement des Kunden wurde aufgrund von Zahlungsproblemen (unzureichendes Guthaben oder ungültige Rechnungsinformationen) vorübergehend pausiert. Das Abonnement wird automatisch fortgesetzt und es wird ein Verlängerungsereignis generiert, sobald der Kunde seine Rechnungsinformationen aktualisiert hat und die Zahlung erfolgreich verarbeitet wurde. Aktiv — AR ON: Der Kunde ist aktiv und hat die automatische Verlängerung aktiviert. Aktiv — AR AUS: Der Kunde ist aktiv, hat aber die automatische Verlängerung deaktiviert.
Abonnement_Event_Time_UTC	Zeitstempel	Die Uhrzeit, zu der das Abonnementereignis eingetreten ist, standardisiert auf UTC.
Abonnement_Event_Timezone	Zeichenfolge	Die Zeitzone des Abonnement-Marktplatzes.
cid	Schnur	Anonymisierte Kunden-ID (CID). Diese Kunden-ID wird für alle Ereignisse in einem einzigen übergeordneten Kanal gespeichert, um Bewegungen zwischen den Stufen und die Nachverfolgung des Kundenlebenszyklus zu ermöglichen.
angebots_id	Zeichenfolge	Die ID des spezifischen Abonnementangebots, in Bezug auf das das Ereignis eingetreten ist.
Name des Angebots	Zeichenfolge	Der für Menschen lesbare Name des Angebots.
angebotsart	Zeichenfolge	Die type des Angebots.
angebot_marktplatz	Zeichenfolge	Der Marketplace, auf dem das Abonnementangebot live war.
Abrechnungstyp des Angebots	Zeichenfolge	Die für das Angebot erforderliche Zahlungsart: HO: Festes Angebot; Zahlung erforderlich. FT: Kostenlose Testversion; keine Zahlung erforderlich.
Betrag der Angebotszahlung	Zeichenfolge	Der Rechnungsbetrag der Offer_ID.
Vorteils-ID	Zeichenfolge	Die ID des Prime Video-Vorteils, unter dem das Angebot konfiguriert ist.
kanal_label	Zeichenfolge	Der Name des Kanals, unter dem das Angebot läuft. Hinweis: Wenn in dieser Spalte ein Nullwert angezeigt wird und Sie Bedenken haben, wenden Sie sich bitte an Ihren CAM oder PSm.
channel_tier_label	Zeichenfolge	Der Name des Kanals, unter dem das Angebot läuft. Hinweis: Wenn in dieser Spalte ein Nullwert angezeigt wird und Sie Bedenken haben, wenden Sie sich bitte an Ihren CAM oder PSm.
ist_promo	int	Gibt an, ob es sich bei einem Angebot zum Zeitpunkt der Veranstaltung um eine Werbeaktion handelt (0 = keine Werbeaktion, 1 = ja).
create_time_utc	Zeitstempel	Die Uhrzeit, zu der der Datensatz im Abonnement-Ereignisprotokoll erstellt wurde, standardisiert auf UTC.
Uhrzeit der letzten Aktualisierung (UTC)	Zeitstempel	Die Uhrzeit der letzten Aktualisierung des Abonnement-Ereignisprotokolls, standardisiert auf UTC.
ist_gelöscht	int	Gibt an, ob ein Datensatz, der zuvor erstellt wurde, gelöscht werden soll (0 = sollte bestehen bleiben, 1 = sollte gelöscht werden).

Datensatz wiedergeben

Spalte	Type	Definition
Sitzungs-ID (pk)	Zeichenfolge	Die eindeutige ID für die Wiedergabesitzung.
Marktplatz-ID	int	Die eindeutige ID für den Playback-Marktplatz.
marketplace_desc	Zeichenfolge	Eine freundliche Beschreibung für den Playback-Marktplatz.
cid	Schnur	Die Benutzerkennung, anonymisiert mit UUID.
Vorteils-ID	Zeichenfolge	Der Vorteil, der mit Inhalten verbunden ist, die gestreamt wurden.
katalog_id	Zeichenfolge	Fremdschlüssel (FK), der für die Verknüpfung mit der Katalogtabelle verwendet wird.
Abonnement-Angebots-ID	Zeichenfolge	Das Abonnement offer_id, das der Kunde zum Zeitpunkt des Streams abonniert hat (Active oder ApprovalPending).
Abonnement-Event-ID	Zeichenfolge	Fremdschlüssel (FK) für den Beitritt zum Abonnement-Ereignisprotokoll, um den genauen Status des Abonnenten zum Zeitpunkt der Wiedergabe abzurufen (Aktiv)
start_segment_utc	Zeitstempel	Start des Playback-Segments in UTC.
Endsegment_UTC	Zeitstempel	End des Playback-Segments in UTC.
gesehene Sekunden	int	Sekunden, in denen der Benutzer Inhalte während der Wiedergabe gestreamt hat.
position_start	doppelt	Sekunde des Streams, in dem die Wiedergabe-Sitzung gestartet wurde.
position_end	doppelt	Sekunde des Streams, in dem die Wiedergabe-Sitzung beendet wurde.
Verbindungstyp	Zeichenfolge	Verbindung, die vom Kunden verwendet wird, um den Inhalt zu streamen.
Stream-Typ	Zeichenfolge	Klassifizierung zwischen Video-On-Demand-, Live- oder Just After Broadcast (JAB) -Streams.
Geräteklasse	Zeichenfolge	Type des Geräts (z. B. Wohnzimmer, Handy, Internet oder Andere).
Gerätesubklasse	Zeichenfolge	Granularer Gerätetyp (z. B. Spielekonsole, Smart_TV, Roku).
geo_dma	Zeichenfolge	Das dreistellige geografische Designated Market Area (DMA) des Gebiets, in dem der Stream erzeugt wurde.
Wiedergabemethode	Zeichenfolge	Gibt an, ob die Wiedergabe online oder offline ist.
Qualität	Schnur	Wiedergabequalität (z. B. 1080p oder 4K)
Ereignistyp	Zeichenfolge	Der definierende Ereignistyp (playback_segments)
create_time_utc	Zeitstempel	Zeitstempel, zu dem der Datensatz zur Tabelle hinzugefügt wurde, in UTC.
Uhrzeit der letzten Aktualisierung (UTC)	Zeitstempel	Zeitstempel der letzten Aktualisierung, als der Datensatz geändert wurde, in UTC.
ist_gelöscht	int	Markierung, um Partnern mitzuteilen, ob der Datensatz in ihrem System gelöscht werden soll.

Katalog-Datensatz

Spalte	Type	Definition
id (pk)	Zeichenfolge	Die eindeutige ID für den Titel.
Marktplatz-ID	int	Die eindeutige ID für den Angebots-Marketplace.
Vorteils-ID	Zeichenfolge	Der mit dem Inhalt verbundene Vorteil wurde erweitert.
Titel	Zeichenfolge	Der Titel der Serie/des Films.
vendor_sku	Zeichenfolge	Eine willkürliche Kennung, die der Anbieter für jeden seiner Filme oder Folgen generiert.
Jahreszeit	Ganzzahl	Die Staffelnummer (für episodischen Inhalt).
Folge	Ganzzahl	Die Nummer der Folge.
Name der Folge	Zeichenfolge	Der Name der Episode (optional).
laufzeit_minuten	Ganzzahl	Die Laufzeit des aufgerufenen Inhalts.
live_linear_kanalname	Zeichenfolge	Der Kanalname für Live-Inhalte.
Inhaltstyp	Zeichenfolge	Entweder TV oder Film.
Inhaltsqualität	Zeichenfolge	HD oder SD
Inhaltsgruppe	Zeichenfolge	3P_SUBS
create_time_utc	Zeitstempel	Zeitstempel, zu dem der Datensatz zur Tabelle hinzugefügt wurde, in UTC.
Uhrzeit der letzten Aktualisierung (UTC)	Zeitstempel	Zeitstempel der letzten Aktualisierung, als der Datensatz geändert wurde, in UTC.
ist_gelöscht	int	Markierung, um Partnern mitzuteilen, ob der Datensatz in ihrem System gelöscht werden soll.

Beispielabfragen

Das folgende SQL-Beispiel zeigt, wie die Datensatztabellen miteinander verbunden sind. Sie können Wiedergabedaten mit dem Abonnement-Ereignisprotokoll in der Spalte subscription_event_id verknüpfen. Dadurch wird der aktuelle Abonnementstatus vor dem Stream angezeigt. In diesem Beispiel wird die Spalte catalog_id im Playback-Dataset mit dem ID-Feld in catalog_event_log verknüpft, um alle Katalogmetadaten bereitzustellen.

Das folgende SQL-Beispiel gibt die zehn Titel zurück, die sich Kunden zuerst angesehen haben, nachdem sie ein Abonnement abgeschlossen haben.

Orchestrierung von Beispielen

Wenn Sie die Datenextraktion aus der Datasets-API nach einem wiederkehrenden Zeitplan automatisieren möchten, zeigt das folgende Python-Beispielskript, wie Sie alle 6 Stunden inkrementelle API-Aufrufe durchführen. Es verfolgt 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 Aufruf. Das Skript berechnet EndDateTime als aktuelle Uhrzeit, erstellt die entsprechenden Abfrageparameter und sendet eine GET-Anforderung mit Authentifizierung. Dieser Ansatz gewährleistet einen kontinuierlichen, nicht überlappenden Datenabruf über Zeitfenster hinweg und kann über Cron oder einen anderen Job-Scheduler geplant werden.