Video Central

Overzicht van de API voor datasets

De Datasets API maakt deel uit van ons nieuwe partnergegevensproduct, Slate Analytics. In tegenstelling tot andere Slate-rapporten kunnen datasets alleen worden toegevoegd (elk bestand bevat nieuwe gegevens), kunnen ze niet worden gedownload in de gebruikersinterface van Slate (maar zijn ze alleen toegankelijk via de API) en zijn ze expliciet gemaakt voor partnergegevenstechnici om gedetailleerde gegevens te gebruiken en analyses uit te voeren. Dit onderwerp helpt data-ingenieurs bij het opzetten van hun pijplijnen om datasets op te halen, definieert de waarden in de datasetbestanden en biedt voorbeeldvragen en suggesties voor de optimale manieren waarop partners deze gegevens kunnen gebruiken.

Praktisch gebruik van datasets

We bieden datasets aan consumenten in de vorm van een changelog. Elk evenement wordt maar één keer gepubliceerd. Als er echter kolomwaarden voor een eerder aangeleverde rij moeten worden bijgewerkt, publiceren we een nieuwe versie van de record waarin de wijzigingen in het volgende beschikbare bestand worden weergegeven. De changelog kan alleen worden toegevoegd om ervoor te zorgen dat alle gegevenswijzigingen worden vastgelegd. Data-engineers kunnen deze changelog gebruiken om hun gegevenstabellen rechtstreeks bij te werken.

Bij het verwerken van de changelog is het essentieel om altijd de laatste record voor een gegeven event_id te gebruiken, gebaseerd op de last_update_time_utc-kolom. Dit zorgt ervoor dat je altijd de meest recente versie van elk record hebt. Als een record moet worden verwijderd, wordt deze actie weergegeven in de kolom is_deleted. De waarde 1 geeft aan dat de record is verwijderd, terwijl de waarde 0 staat voor een actief record. Met deze changelog-aanpak kunt u nieuwe en veranderende gegevens effectief beheren en ervoor zorgen dat uw gegevenstabellen nauwkeurig en up-to-date blijven met de meest recente informatie.

API-voorrondes voor datasets

Voordat u een aanvraag indient bij de Dataset API, is het belangrijk om de basisvereisten voor authenticatie en paginering te begrijpen. In dit gedeelte wordt beschreven hoe u veilig toegang kunt krijgen tot de API en hoe u efficiënt door grote datasets kunt navigeren.

Onboarding to Datasets API
Om datasets op te halen, moet u eerst onboarden in de Datasets API-suite. Meer informatie vind je hier.

De basis-URI is: https://videocentral.amazon.com/apis/v2. Alle aanvragen moeten een geldig LWA-authenticatietoken bevatten in de kop van de autorisatie van de aanvraag. Bijvoorbeeld:

Als de aanvraagheader het token niet bevat, of als het token is verlopen, retourneert de Datasets API een ongeautoriseerde uitzondering.

Paginering
Alle Slate API-reacties zijn gepagineerd. Pagineringsparameters worden gespecificeerd via verzoekparameters.

Parameter aanvragen	Standaardwaarde	Omschrijving
begrenzing	10	Het aantal documenten dat op één pagina wordt geretourneerd (het paginaformaat).
offset	0	Het aantal pagina’s dat moet worden overgeslagen (het paginanummer).

Alle gepagineerde reacties bevatten de volgende velden.

Veld	Omschrijving
totaal	Het totale aantal documenten op alle pagina’s.
volgende	De URL naar de volgende pagina. Null van de laatste pagina.

De Datasets API gebruiken

Om programmatisch toegang te krijgen tot datasets, moeten klanten een reeks API-aanroepen volgen waarin de beschikbare bronnen, zoals accounts, groepen, bedrijven en datasets, worden opgesomd voordat ze downloadbare URL’s voor de gegevensbestanden ophalen. Deze reeks is ontworpen om automatisering te ondersteunen en kan worden geïntegreerd in terugkerende datapijplijnen of geplande workflows.

Accounts weergeven
/v2/accounts

Deze bron retourneert de lijst met Slate-accounts waartoe de gebruiker toegang heeft. De set accounts is toegankelijk in Slate via de lijst met accounts in de rechterbovenhoek van de portal. Je kunt deze links ook gebruiken om je account_id of je kanaal/studio_id te vinden.

Voorbeeldaanvraag

Voorbeeldreactie

Groepen (bedrijfsonderdelen)
/v2/accounts/ {account_id} weergeven

Deze bron retourneert de groepen bedrijfsonderdelen (zoals kanalen) waartoe de gebruiker toegang heeft.

Voorbeeldaanvraag

Voorbeeldreactie

Bedrijven weergeven
/v2/accounts/ {account_id}/{group_id}

Deze bron retourneert een lijst met bedrijven (zoals specifieke kanaalnamen) die beschikbaar zijn voor dit account, afhankelijk van het gegeven bedrijfsonderdeel.

Voorbeeldaanvraag

Voorbeeldreactie

Beschikbare datasets
/v2/accounts/ {acccount_id}/{group_id}/{business_id} /datasets weergeven
Deze bron retourneert de lijst met datasets die beschikbaar zijn voor een bepaald kanaal of studio. (De lijst met beschikbare datasets en hun kenmerken zijn opgenomen in de definities van datasets, verderop in dit onderwerp.) De datasets die momenteel beschikbaar zijn om te downloaden zijn:

Abonnement: Gebeurtenissen in de levenscyclus van de klant, zoals wanneer een klant zich heeft geabonneerd.
Afspelen: gebeurtenissen in afspeelsessies waarbij klanten zich met inhoud hebben bezig gehouden.
Catalogus: Gebeurtenissen waarbij de metagegevens van uw catalogus zijn gewijzigd, zoals wanneer een nieuwe titel werd toegevoegd.

Voorbeeldaanvraag

Voorbeeldreactie

Datasetbestand (en)
/v2/accounts/ {account_id}/{group_id}/{business_id} /datasets/ {dataset_id} verkrijgen Deze bron bevat een lijst met datasetbestanden.

Afhankelijk van het gevraagde tijdbereik kan de lijst een groot aantal bestanden bevatten. Het totaalveld geeft aan hoeveel bestanden je kunt verwachten. Nadat u een volledige aanvulling hebt voltooid, kunt u op de hoogte blijven door bestanden aan te vragen met een StartDateTime die gelijk is aan de laatst opgehaalde tijdstempel en een EndDateTime die is ingesteld op de huidige tijd.

Nieuwe datasets worden ongeveer elke 4 uur gepubliceerd en kunnen gebeurtenissen bevatten die zich in de afgelopen 12 uur hebben voorgedaan. We raden aan om onze API meerdere keren per dag te bellen, ongeveer elke 4-6 uur, om ervoor te zorgen dat je lokale gegevens zo volledig en actueel mogelijk zijn. Als we vertraging ondervinden bij het publiceren, zullen we zo snel mogelijk via e-mail communiceren.

De volgende tabel beschrijft de beschikbare aanvraagparameters voor datasetbestanden.

Parameter aanvragen	Omschrijving
Startdatum en tijd	Aanbeveling is om in te stellen vanaf de laatste keer dat de gebruiker is getrokken. (Formaat: YYYY-MM-DDTHH:MM:SSZ - tijdstempel UTC)
Einddatum/tijd	Aanbeveling is om in te stellen op het moment van trekken/huidige tijd. (Formaat: YYYY-MM-DDTHH:MM:SSZ - tijdstempel UTC)
limiet	De maximale limiet is 1000 links per pagina.

Opmerking: onze maximale gegevensbewaring is 2 jaar. Aanvragen voor datasets met een tijdstempel eerder dan 2 jaar eerder leveren geen resultaten op.

Voorbeeldaanvraag

Voorbeeldreactie

Notities:

De maximale zipgrootte van een bestand is 300 MB. Bestanden die deze limiet overschrijden, worden opgesplitst in meerdere bestanden.
De vooraf ondertekende URL time-to-live (TTL) is 60 minuten.

Definities van datasets

De tabellen in deze sectie bevatten de kolommen, gegevenstypen en definities voor elk van de 3 beschikbare datasets.

Dataset voor abonnementen

Kolom	Typ	Definitie
subscription_event_id (pk)	touwtje	De unieke ID voor elk abonnementsevenement dat via dit logboek wordt verkocht.
abonnement_event_type	touwtje	Het type abonnementsgebeurtenis dat plaatsvond: Start: de klant heeft zich geabonneerd op een kanaal waarop hij eerder niet was geabonneerd. Verlenging: de klant was geabonneerd op een kanaal en was al actief voor dat kanaal voorafgaand aan het abonnementsevenement. Annuleren: de klant heeft zijn abonnement opgezegd. Opschorten: het abonnement van de klant is tijdelijk onderbroken vanwege betalingsproblemen (onvoldoende saldo of ongeldige factuurgegevens). Het abonnement wordt automatisch hervat en er wordt een verlengingsgebeurtenis gegenereerd zodra de klant zijn factuurgegevens heeft bijgewerkt en de betaling succesvol is verwerkt. Actief - AR AAN: De klant is actief en heeft automatische verlenging ingeschakeld. Actief - AR UIT: De klant is actief, maar heeft automatische verlenging uitgeschakeld.
subscription_event_time_utc	tijdstempel	Het tijdstip waarop het abonnement plaatsvond, gestandaardiseerd naar UTC.
subscription_event_time_zone	touwtje	De tijdzone van de marktplaats voor abonnementen.
zuur	touwtje	Geanonimiseerde klant-ID (CID). Deze klantidentificatie blijft voor alle gebeurtenissen via één ouderkanaal bestaan om bewegingen tussen verschillende niveaus mogelijk te maken en de levenscyclus van klanten te volgen.
offer_id	touwtje	De ID van de specifieke abonnementsaanbieding waarop de gebeurtenis plaatsvond.
naam van het aanbod	touwtje	De voor mensen leesbare naam van de aanbieding.
offer_type	touwtje	Het soort aanbod.
offer_marketplace	touwtje	De marktplaats waar het abonnementsaanbod live was.
offer_billing_type	touwtje	Het type betaling dat vereist is voor de aanbieding: HO: Moeilijk aanbod; betaling vereist. FT: Gratis proefversie; geen betaling vereist.
offer_betaling_bedrag	touwtje	Het factuurbedrag van de offer_id.
benefit_id	touwtje	De ID van het Prime Video-voordeel dat de aanbieding biedt, is geconfigureerd onder.
kanaal_label	touwtje	De naam van het kanaal waaronder het aanbod staat. Opmerking: Als deze kolom een nulwaarde bevat en u zich zorgen maakt, neem dan contact op met uw CAM of PsM.
channel_tier_label	touwtje	De naam van het kanaal waaronder het aanbod staat. Opmerking: Als deze kolom een nulwaarde bevat en u zich zorgen maakt, neem dan contact op met uw CAM of PsM.
is_promo	int	Geeft aan of een aanbieding betrekking heeft op een promotie op het moment van het evenement (0 = geen promotie, 1 = ja promo).
create_time_utc	tijdstempel	Het tijdstip waarop het logboekrecord van de abonnementsgebeurtenis werd aangemaakt, gestandaardiseerd naar UTC.
last_update_time_utc	tijdstempel	Het tijdstip waarop het logboekrecord van de abonnementsgebeurtenis voor het laatst is bijgewerkt, gestandaardiseerd naar UTC.
is_verwijderd	int	Geeft aan of een record dat eerder is gemaakt, moet worden verwijderd (0 = moet blijven bestaan, 1 = moet worden verwijderd).

Dataset afspelen

Kolom	Typ	Definitie
session_id (pk)	touwtje	De unieke ID voor de afspeelsessie.
marketplace_id	int	De unieke ID voor de playbackmarktplaats.
marketplace_desc	touwtje	Een vriendelijke beschrijving voor de playbackmarkt.
zuur	touwtje	De gebruikersidentificatie, geanonimiseerd met UUID.
benefit_id	touwtje	Het voordeel van content die is gestreamd.
catalog_id	touwtje	Foreign key (FK) gebruikt om deel te nemen aan de catalogustabel.
subscription_offer_id	touwtje	Het abonnement waarop de klant offer_id is geabonneerd op het moment van de stream (actief of in afwachting van goedkeuring).
subscription_event_id	touwtje	Externe sleutel (FK) om deel te nemen aan het evenementenlogboek van het abonnement om de exacte status van de abonnee te krijgen op het moment van afspelen (actief)
start_segment_utc	tijdstempel	Begin van het afspeelsegment in UTC.
end_segment_utc	tijdstempel	Einde van het afspeelsegment in UTC.
seconden bekeken	int	Seconds streamde de gebruiker inhoud tijdens het afspelen.
position_start	dubbel	Tweede van de stream waar de afspeelsessie begon.
position_end	dubbel	Tweede van de stream waar de afspeelsessie is beëindigd.
verbinding_type	touwtje	Verbinding die door de klant wordt gebruikt om de inhoud te streamen.
stream_type	touwtje	Classificatie tussen video-on-demand-streams, livestreams of Just After Broadcast (JAB).
apparaat_klasse	touwtje	Soort apparaat (zoals woonkamer, mobiel, internet of andere).
device_sub_class	touwtje	Gedetailleerd type apparaat (zoals gameconsole, smart_tv, roku).
geo_dma	touwtje	Het 3-cijferige geografische Designated Market Area (DMA) van het gebied waar de stream werd gegenereerd.
playback_methode	touwtje	Hiermee wordt bepaald of het afspelen online of offline is.
kwaliteit	touwtje	Afspeelkwaliteit (zoals 1080p of 4K)
event_type	touwtje	Het bepalende type gebeurtenis (playback_segments)
create_time_utc	tijdstempel	Tijdstempel wanneer record werd toegevoegd aan de tabel, in UTC.
last_update_time_utc	tijdstempel	Laatst bijgewerkte tijdstempel toen de record werd gewijzigd, in UTC.
is_verwijderd	int	Markeer om partners aan te geven of het record in hun systeem moet worden verwijderd.

Catalogusdataset

Kolom	Typ	Definitie
deksel (per stuk)	touwtje	De unieke ID voor de titel.
marketplace_id	int	De unieke ID voor de marktplaats van het aanbod.
benefit_id	touwtje	Het voordeel van de inhoud is uitgebreid.
titel	touwtje	De titel van de serie/film.
vendor_sku	touwtje	Een willekeurige identificatiecode die de leverancier genereert voor elk van zijn films of afleveringen.
seizoen	geheel getal	Het seizoensnummer (voor episodische inhoud).
aflevering	geheel getal	Het nummer van de aflevering.
naam van de aflevering	touwtje	De naam van de aflevering (optioneel).
runtime_minutes	geheel getal	De looptijd van de bekeken inhoud.
live_linear_channel_name	touwtje	De kanaalnaam voor live content.
inhoud_type	touwtje	Of het nu tv of film is.
inhoud_kwaliteit	touwtje	HD of SD
inhoud_groep	touwtje	3P_SUBS
create_time_utc	tijdstempel	Tijdstempel wanneer record werd toegevoegd aan de tabel, in UTC.
last_update_time_utc	tijdstempel	Laatst bijgewerkte tijdstempel toen de record werd gewijzigd, in UTC.
is_verwijderd	int	Markeer om partners aan te geven of het record in hun systeem moet worden verwijderd.

Voorbeeldvragen

Het volgende SQL-voorbeeld laat zien hoe de datasettabellen met elkaar verbonden zijn. Je kunt afspeelgegevens toevoegen aan het logboek van de abonnementsgebeurtenis in de kolom subscription_event_id. Dit geeft de laatste abonnementsstatus vóór die stream weer. In dit voorbeeld wordt de kolom catalog_id in de afspeelgegevensset gekoppeld aan het id-veld in catalog_event_log om alle metagegevens van de catalogus op te geven.

In het volgende SQL-voorbeeld worden de tien meest bekeken titels weergegeven voor klanten die een abonnement hebben gestart.

Voorbeeldorkestratie

Als u de gegevensextractie uit de Datasets API volgens een terugkerend schema wilt automatiseren, laat het volgende Python-voorbeeldscript zien hoe u elke 6 uur incrementele API-aanroepen kunt uitvoeren. Het traceert de tijdstempel van de laatste succesvolle aanvraag door deze lokaal te bewaren, en gebruikt die waarde (plus één seconde) als de StartDateTime voor de volgende aanroep. Het script berekent EndDateTime als de huidige tijd, stelt de juiste queryparameters samen en verstuurt een GET-aanvraag met authenticatie. Deze aanpak zorgt voor een continue, niet-overlappende gegevensopname in verschillende tijdvensters en kan worden gepland via cron of een andere taakplanner.

API voor gegevenssets

Overzicht van de API voor datasets

API-voorrondes voor datasets

De Datasets API gebruiken

Definities van datasets

Voorbeeldvragen

Voorbeeldorkestratie