Video Central

Aperçu de l’API Datasets

L’API Datasets fait partie de notre nouveau produit de données pour partenaires, Slate Analytics. Contrairement aux autres rapports Slate, les ensembles de données fonctionnent par ajout uniquement (chaque fichier contient de nouvelles données). Ils ne sont pas disponibles au téléchargement dans l’interface Slate, mais sont accessibles uniquement via l’API. Ils sont conçus spécifiquement pour que les ingénieurs de données partenaires puissent utiliser des données granulaires et effectuer des analyses. Cette rubrique aide les ingénieurs de données à configurer leurs pipelines pour récupérer des ensembles de données, définit les valeurs dans les fichiers de données et fournit des exemples de requêtes et des suggestions pour optimiser l’utilisation des données par les partenaires.

Utilisation pratique des ensembles de données

Nous fournissons des ensembles de données aux consommateurs sous la forme d’un journal des modifications. Chaque événement n’est publié qu’une seule fois. Toutefois, si les valeurs de colonne d’une ligne précédemment fournie doivent être mises à jour, nous publierons une nouvelle version de l’enregistrement afin de refléter les modifications dans votre prochain fichier disponible. Le journal des modifications fonctionne par ajout uniquement, afin de s’assurer que toutes les modifications de données sont capturées. Les ingénieurs de données peuvent utiliser ce journal des modifications pour mettre à jour leurs tables de données directement.

Lorsque vous traitez le journal des modifications, il est essentiel d’utiliser toujours l’enregistrement le plus récent pour un event_id donné, en fonction de la colonne last_update_time_utc. Cela garantit que vous disposez toujours de la version la plus récente de chaque enregistrement. S’il faut supprimer un enregistrement, cette action est reflétée dans la colonne is_deleted. Une valeur de 1 indique que l’enregistrement a été supprimé, tandis qu’une valeur de 0 représente un enregistrement actif. Cette approche de journal des modifications vous permet de gérer efficacement les nouvelles données et les données changeantes, et garantit que vos tables de données restent précises et à jour avec les dernières informations.

Les bases des ensembles de données API

Avant d’adresser des requêtes à l’API Datasets, il est important de comprendre les exigences de base pour l’authentification et la pagination. Cette section explique comment accéder à l’API en toute sécurité et parcourir efficacement de grands ensembles de données.

Intégration à l’API Analytics
Pour récupérer des ensembles de données, vous devez d’abord intégrer la suite API Analytics. Vous trouverez plus de détails ici.

L’URL de base est : https://videocentral.amazon.com/apis/v2. L’en-tête d’autorisation des requêtes doit inclure un jeton d’authentification LWA valide pour toutes les requêtes. Par exemple :

Si l’en-tête de requête n’inclut pas le jeton, ou si le jeton est arrivé à expiration, une exception non autorisée sera générée par l’API Datasets.

Pagination
Toutes les réponses de l’API Slate sont paginées. Les paramètres de pagination sont définis à l’aide des paramètres de requête.

Paramètre de requête	Valeur par défaut	Description
limite	10	Le nombre de documents renvoyés sur une seule page (taille de page).
offset	0	Le nombre de pages à ignorer (le nombre de pages).

Toutes les réponses paginées contiennent les champs suivants.

Champ	Description
total	Nombre total de documents dans toutes les pages.
suivant	L’URL de la page suivante. Null se rapporte à la dernière page.

Utilisation des ensembles de données de l’API

Pour accéder aux ensembles de données par programmation, les clients doivent suivre une série d’appels API qui énumèrent les ressources disponibles, comme les comptes, les groupes, les entreprises et les ensembles de données, avant de récupérer les URL téléchargeables pour les fichiers de données. Cette séquence est conçue pour soutenir l’automatisation et peut être intégrée dans des pipelines de données récurrents ou des flux de travail programmés.

Liste des comptes
/v2/accounts

Cette ressource renvoie la liste des comptes Slate auxquels l’utilisateur peut accéder. L’ensemble des comptes est accessible dans Slate via la liste déroulante des comptes située près du coin supérieur droit du portail. Vous pouvez également utiliser ces liens pour trouver votre account_id ou votre channel/studio_id.

Exemple de demande

Exemple de réponse

Groupes de listes (secteurs d’activité)
/v2/accounts/{account_id}

Cette ressource renvoie les groupes de secteurs d’activité (tels que les chaînes) auxquels l’utilisateur peut accéder.

Exemple de demande

Exemple de réponse

Liste des entreprises
/v2/accounts/{account_id}/{group_id}

Cette ressource renvoie une liste d’entreprises (telles que des noms de chaînes spécifiques) disponibles pour ce compte, en fonction du secteur d’activité indiqué.

Exemple de demande

Exemple de réponse

Répertorier les ensembles de données disponibles
/v2/accounts/{acccount_id}/{group_id}/{business_id}/datasets

Cette ressource renvoie la liste des ensembles de données disponibles pour une chaîne ou un studio donné. (La liste des ensembles de données disponibles et leurs attributs sont inclus dans Définitions des ensembles de données, plus loin dans ce sujet.) Les ensembles de données actuellement disponibles au téléchargement sont les suivants :

Abonnement : Les événements du cycle de vie du client, tels que le moment où un client s’est inscrit.
Lecture : Visionnez les événements de session au cours desquels les clients ont interagi avec le contenu.
Catalogue : Événements au cours desquels les métadonnées de votre catalogue ont changé, par exemple lorsqu’un nouveau titre a été ajouté.

Exemple de demande

Exemple de réponse

Obtenir le ou les fichiers de l’ensemble de données
/v2/accounts/{account_id}/{group_id}/{business_id}/datasets/{dataset_id}

Cette ressource fournit une liste de fichiers d’ensemble de données. Selon la plage temporelle demandée, la liste peut contenir un grand nombre de fichiers. Le total indique combien de fichiers sont à prévoir. Après avoir effectué un remplissage complet, vous pouvez rester à jour en continuant à demander des fichiers en utilisant un startDateTime égal au dernier horodatage récupéré et un endDateTime défini sur l’heure actuelle.

De nouveaux ensembles de données sont publiés approximativement toutes les 4 heures et peuvent contenir des événements survenus au cours des 12 heures précédentes. Nous vous recommandons d’appeler notre API plusieurs fois par jour, approximativement toutes les 4 à 6 heures, pour garantir que vos données locales soient aussi complètes et à jour que possible. Si nous rencontrons un retard dans la publication, nous vous en informerons par e-mail dès que possible.

Le tableau suivant décrit les paramètres de requête disponibles pour les fichiers d’ensembles de données.

Paramètre de requête	Description
Date et heure de début	La recommandation est à définir à partir de la dernière extraction. (Format : AAAA-MM-JJTHH:MM:SSZ - horodatage UTC)
Date et heure de fin	La recommandation est de régler à l’heure de l’extraction/à l’heure actuelle. (Format : AAAA-MM-JJTHH:MM:SSZ - horodatage UTC)
limite	La limite maximale est de 1000 liens par page.

Remarque : Notre durée de conservation maximale des données est de 2 ans. Les demandes d’ensembles de données avec un horodatage antérieur à 2 ans ne renverront aucun résultat.

Exemple de demande

Exemple de réponse

Remarques :

La taille maximale des fichiers zip est de 300 Mo. Les fichiers dépassant cette limite seront divisés en plusieurs fichiers.
La durée de vie (TTL) des URL pré-signées est de 60 minutes.

Définitions des ensembles de données

Les tableaux de cette section répertorient les colonnes, les types de données et les définitions pour chacun des 3 ensembles de données disponibles.

Ensemble de données d’abonnement

Colonne	Type	Définition
subscription_event_id (pk)	chaîne de caractères	L’identifiant unique pour chaque événement d’abonnement distribué via ce journal.
subscription_event_type	chaîne de caractères	Le type d’événement d’abonnement qui s’est produit : Début : Le client s’est abonné à une chaîne à laquelle il n’était pas abonné auparavant. Renouvellement : Le client s’est abonné à une chaîne et était déjà actif pour cette chaîne avant l’événement d’abonnement. Annulation : Le client a annulé son abonnement. Suspension : L’abonnement du client est temporairement suspendu en raison de problèmes de paiement (fonds insuffisants ou informations de facturation non valides). L’abonnement reprendra automatiquement et générera un événement de renouvellement une fois que le client aura mis à jour ses informations de facturation et que le paiement aura été traité avec succès. Actif - RA activé : Le client est actif et a activé le renouvellement automatique. Actif - RA désactivé : Le client est actif, mais a désactivé le renouvellement automatique.
subscription_event_time_utc	horodatage	L’heure à laquelle l’événement d’abonnement s’est produit, normalisée en UTC.
subscription_event_time_zone	chaîne de caractères	Le fuseau horaire du site de vente de l’abonnement.
cid	chaîne de caractères	Identifiant client anonymisé (CID). Cet identifiant client persistera pour tous les événements au sein d’un même canal parent afin de permettre le suivi des mouvements entre les différents niveaux et le suivi du cycle de vie du client.
offer_id	chaîne de caractères	L’identifiant de l’offre d’abonnement spécifique à laquelle l’événement est lié.
offer_name	chaîne de caractères	Le nom de l’offre accessible aux utilisateurs.
offer_type	chaîne de caractères	Le type d’offre.
offer_marketplace	chaîne de caractères	Le site de vente où l’offre d’abonnement était active.
offer_billing_type	chaîne de caractères	Le type de paiement requis pour l’offre : HO : Offre ferme ; paiement requis. FT : Essai gratuit ; aucun paiement requis.
offer_payment_amount	chaîne de caractères	Le montant de facturation de l’offer_id.
benefit_id	chaîne de caractères	L’identifiant de l’avantage Prime Video sous lequel l’offre est configurée.
channel_label	chaîne de caractères	Le nom de la chaîne qui propose l’offre. Remarque : Si cette colonne affiche une valeur nulle et que cela vous préoccupe, contactez votre CAM ou PsM.
channel_tier_label	chaîne de caractères	Le nom de la chaîne qui propose l’offre. Remarque : Si cette colonne affiche une valeur nulle et que cela vous préoccupe, contactez votre CAM ou PsM.
is_promo	int	Indique si une offre fait l’objet d’une promotion au moment de l’événement (0 = pas de promotion, 1 = promotion en cours).
create_time_utc	horodatage	L’heure à laquelle l’enregistrement du journal d’événements d’abonnement a été créé, normalisée en UTC.
last_update_time_utc	horodatage	L’heure à laquelle l’enregistrement du journal d’événements d’abonnement a été mis à jour pour la dernière fois, normalisée en UTC.
is_deleted	int	Indique si un enregistrement précédemment créé doit être supprimé (0 = à conserver, 1 = à supprimer).

Ensemble de données de lecture

Colonne	Type	Définition
session_id (pk)	chaîne de caractères	L’identifiant unique pour la session de lecture.
marketplace_id	int	L’identifiant unique pour le site de lecture.
marketplace_desc	chaîne de caractères	Une description amicale du site de lecture.
cid	chaîne de caractères	L’identifiant utilisateur, anonymisé avec UUID.
benefit_id	chaîne de caractères	L’avantage associé au contenu qui a été diffusé en streaming.
catalog_id	chaîne de caractères	Clé étrangère (FK) utilisée pour joindre à la table de catalogue.
subscription_offer_id	chaîne de caractères	L’offer_id d’abonnement auquel le client est abonné au moment du streaming (Active (actif) ou ApprovalPending(en attente d’approbation)).
subscription_event_id	chaîne de caractères	Clé étrangère (FK) pour joindre au journal des événements d’abonnement afin d’obtenir le statut exact de l’abonné au moment de la lecture (Active)
start_segment_utc	horodatage	Début du segment de lecture en UTC.
end_segment_utc	horodatage	Fin du segment de lecture en UTC.
seconds_viewed	int	Secondes pendant lesquelles l’utilisateur a regardé du contenu en cours de lecture.
position_start	double	Seconde à laquelle la session de lecture en streaming a débuté.
position_end	double	Seconde à laquelle la session de lecture en streaming s’est terminée.
connection_type	chaîne de caractères	Connexion utilisée par le client pour regarder le contenu.
stream_type	chaîne de caractères	Classification entre les flux Vidéo à la demande, En direct ou Juste après la diffusion (JAB).
device_class	chaîne de caractères	Type d’appareil (tel que Salon, Mobile, Web ou Autres).
device_sub_class	chaîne de caractères	Type d’appareil spécifique (tel que console de jeu, smart_tv, roku, etc.).
geo_dma	chaîne de caractères	La zone de marché désignée (DMA) géographique à 3 chiffres de la zone où le visionnage a été généré.
playback_method	chaîne de caractères	Indique si la lecture est en ligne ou hors ligne.
quality	chaîne de caractères	Qualité de lecture (1080p ou 4K, par exemple)
event_type	chaîne de caractères	Le type d’événement défini (playback_segments)
create_time_utc	horodatage	Horodatage indiquant quand l’enregistrement a été ajouté à la table, en UTC.
last_update_time_utc	horodatage	Horodatage de la dernière mise à jour lorsque l’enregistrement a été modifié, en UTC.
is_deleted	int	Indicateur permettant de signaler aux partenaires si l’enregistrement doit être supprimé dans leur système.

Ensemble de données du catalogue

Colonne	Type	Définition
id (pk)	chaîne de caractères	L’identifiant unique du titre.
marketplace_id	int	L’identifiant unique du site de vente de l’offre.
benefit_id	chaîne de caractères	L’avantage associé au contenu étendu.
title	chaîne de caractères	Le titre de la série/du film.
vendor_sku	chaîne de caractères	Un identifiant arbitraire généré par le fournisseur pour chacun de ses films ou épisodes.
saison	nombre entier	Le numéro de saison (pour les contenus épisodiques).
épisode	nombre entier	Le numéro d’épisode.
episode_name	chaîne de caractères	Le nom de l’épisode (facultatif).
runtime_minutes	nombre entier	La durée d’exécution du contenu consulté.
live_linear_channel_name	chaîne de caractères	Le nom de la chaîne pour le contenu en direct.
content_type	chaîne de caractères	Série ou Film.
content_quality	chaîne de caractères	HD ou SD
content_group	chaîne de caractères	3P_SUBS
create_time_utc	horodatage	Horodatage indiquant quand l’enregistrement a été ajouté à la table, en UTC.
last_update_time_utc	horodatage	Horodatage de la dernière mise à jour lorsque l’enregistrement a été modifié, en UTC.
is_deleted	int	Indicateur permettant de signaler aux partenaires si l’enregistrement doit être supprimé dans leur système.

Exemples de requêtes

L’exemple SQL suivant montre comment les tables de l’ensemble de données sont connectées. Vous pouvez joindre les données de lecture au journal des événements d’abonnement dans la colonne subscription_event_id. Cela fournit le dernier statut d’abonnement avant cette diffusion. Dans cet exemple, la colonne catalog_id du jeu de données de lecture est jointe au champ id du catalog_event_log pour fournir toutes les métadonnées du catalogue.

L’exemple SQL suivant renvoie les 10 premiers titres regardés par les clients après avoir commencé un abonnement.

Exemple d’orchestration

Si vous souhaitez automatiser l’extraction de données depuis l’API Datasets selon un calendrier récurrent, le script Python d’exemple suivant montre comment effectuer des appels API incrémentaux toutes les 6 heures. Il suit l’horodatage de la dernière requête réussie en le conservant localement, et utilise cette valeur, plus une seconde, comme startDateTime pour l’appel suivant. Le script calcule endDateTime comme l’heure actuelle, construit les paramètres de requête appropriés et envoie une requête GET avec authentification. Cette approche garantit une récupération de données continue et sans chevauchement sur toutes les fenêtres temporelles et peut être planifiée via cron ou un autre planificateur de tâches.

Ensembles de données API

Aperçu de l’API Datasets

Les bases des ensembles de données API

Utilisation des ensembles de données de l’API

Définitions des ensembles de données

Exemples de requêtes

Exemple d’orchestration