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 ne peut être ajouté que pour garantir 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. Si un enregistrement doit être supprimé, 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 de l’API Datasets

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.

Authentification
Pour récupérer des ensembles de données, vous devez disposer des éléments suivants :

Un identifiant avec Amazon Security Profile
Un code d’autorisation pour demander un jeton
Un jeton pour toutes les requêtes curl

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êtes	Valeur par défaut	Description
limit	10	Nombre de documents renvoyés sur une seule page (format de la page).
offset	0	Nombre de pages à ignorer (le nombre de pages).

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

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

Utilisation de l’API Datasets

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 requête

Exemple de réponse

Liste des groupes (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 requête

Exemple de réponse

Liste d’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 requête

Exemple de réponse

Liste des jeux 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 : événements dans le cycle de vie du client, tels que le moment où un client s’est abonné.
Lecture : événements de session de lecture où les clients ont interagi avec le contenu.
Catalogue : événements où les métadonnées de votre catalogue ont changé, comme lorsqu’un nouveau titre a été ajouté.

Exemple de requête

Exemple de réponse

Obtenir le ou les fichiers d’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
startDateTime	Il est recommandé de définir cette valeur à partir de la dernière extraction effectuée. (Format : AAAA-MM-JJTHH:MM:SSZ - horodatage UTC)
endDateTime	Il est recommandé de définir cette valeur à l’heure de l’extraction/l’heure actuelle. (Format : AAAA-MM-JJTHH:MM:SSZ - horodatage UTC)
limit	La limite maximale est de 1 000 liens par page.

Remarque : Notre durée maximale de conservation 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 requête

Exemple de réponse

Remarques :

La taille maximale du fichier zip est de 300 Mo. Les fichiers qui dépassent cette limite seront fractionné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)	séquence	L’identifiant unique pour chaque événement d’abonnement distribué via ce journal.
subscription_event_type	séquence	Le type d’événement d’abonnement qui s’est produit : Démarrage : 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. Résiliation : le client a résilié son abonnement. 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	séquence	Le fuseau horaire du site de vente de l’abonnement.
cid	séquence	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	séquence	L’identifiant de l’offre d’abonnement spécifique à laquelle l’événement est lié.
offer_name	séquence	Le nom de l’offre accessible aux utilisateurs.
offer_type	séquence	Le type d’offre.
offer_marketplace	séquence	Le site de vente où l’offre d’abonnement était active.
offer_billing_type	séquence	Le type de paiement requis pour l’offre : HO : offre payante ; paiement requis. FT : offre d’essai gratuit ; aucun paiement requis.
offer_payment_amount	séquence	Le montant de facturation associé à l’offer_id.
benefit_id	séquence	L’identifiant de l’avantage Prime Video sous lequel l’offre est configurée.
channel_label	séquence	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	séquence	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)	séquence	L’identifiant unique pour la session de lecture.
marketplace_id	int	L’identifiant unique pour le site de lecture.
marketplace_desc	séquence	Une description conviviale du site de lecture.
cid	séquence	L’identifiant utilisateur, anonymisé avec UUID.
benefit_id	séquence	L’avantage associé au contenu qui a été diffusé en streaming.
catalog_id	séquence	Clé étrangère (FK) utilisée pour joindre à la table de catalogue.
subscription_offer_id	séquence	L’offer_id d’abonnement auquel le client est abonné au moment du streaming (Active ou ApprovalPending).
subscription_event_id	séquence	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	séquence	Connexion utilisée par le client pour regarder le contenu.
stream_type	séquence	Classification entre les flux Vidéo à la demande, En direct ou Juste après la diffusion (JAB).
device_class	séquence	Type d’appareil (tel que Salon, Mobile, Web ou Autres).
device_sub_class	séquence	Type d’appareil spécifique (tel que console de jeu, smart_tv, roku, etc.).
geo_dma	séquence	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	séquence	Indique si la lecture est en ligne ou hors ligne.
quality	séquence	Qualité de lecture (comme 1080p ou 4K)
event_type	séquence	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)	séquence	L’identifiant unique du titre.
marketplace_id	int	L’identifiant unique du site de vente de l’offre.
benefit_id	séquence	L’avantage associé au contenu étendu.
title	séquence	Le titre de la série/du film.
vendor_sku	séquence	Un identifiant arbitraire généré par le fournisseur pour chacun de ses films ou épisodes.
season	nombre entier	Le numéro de saison (pour les contenus épisodiques).
episode	nombre entier	Le numéro d’épisode.
episode_name	séquence	Le nom de l’épisode (facultatif).
runtime_minutes	nombre entier	La durée d’exécution du contenu consulté.
live_linear_channel_name	séquence	Le nom de la chaîne pour le contenu en direct.
content_type	séquence	Série ou Film.
content_quality	séquence	HD ou SD
content_group	séquence	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 sur la colonne subscription_event_id. Cela fournit le dernier statut d’abonnement avant cette diffusion. Dans cet exemple, la colonne catalog_id dans l’ensemble de données de lecture est jointe au champ id dans 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 à travers les fenêtres temporelles et peut être programmée via cron ou un autre planificateur de tâches.