Video Central

Présentation de l’API Datasets

L’API Datasets fait partie de notre nouveau produit de données destiné aux partenaires, Slate Analytics. Contrairement aux autres rapports Slate, les ensembles de données sont uniquement ajoutés (chaque fichier contient de nouvelles données), ne peuvent pas être téléchargés dans l’interface utilisateur de Slate (mais sont uniquement accessibles via une API) et sont conçus explicitement 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 les ensembles de données, définit les valeurs contenues dans les fichiers des ensembles de données et fournit des exemples de requêtes ainsi que des suggestions sur la manière optimale dont les partenaires peuvent utiliser ces données.

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 est uniquement disponible en ajout, afin de garantir que toutes les modifications des 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 de toujours utiliser le dernier enregistrement 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. La valeur 1 indique que l’enregistrement a été supprimé, tandis que la valeur 0 représente un enregistrement actif. Cette approche du journal des modifications vous permet de gérer efficacement les données nouvelles et changeantes, et garantit que vos tableaux de données restent exacts et à jour avec les informations les plus récentes.

Avant-premières de l’API Datasets

Avant de faire des demandes à l’API Dataset, il est important de comprendre les exigences de base en matière d’authentification et de pagination. Cette section explique comment accéder en toute sécurité à l’API et naviguer efficacement dans de grands ensembles de données.

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

L’URI de base est : https://videocentral.amazon.com/apis/v2. Tous/Toutes les demandes doivent inclure un jeton d’authentification LWA valide dans l’en-tête d’autorisation de la demande. Par exemple :

Si l’en-tête de demande n’inclut pas le jeton, ou si le jeton a expiré, l’API Datasets renvoie une exception non autorisée.

Pagination
Toutes les réponses de l’API Slate sont paginées. Les paramètres de pagination sont spécifiés via les paramètres des requêtes.

Paramètre de demande	Valeur par défaut	Description
limite	10	Le nombre de documents renvoyés sur une seule page (le format de page).
décalage	0	Le nombre de pages à ignorer (le numéro de page).

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

Champ	Description
total	Le nombre total de documents sur toutes les pages.
suivant	URL de la page suivante. Null s’il s’agit de la dernière page.

Utiliser l’API Datasets

Pour accéder aux ensembles de données par programmation, les clients doivent suivre une série d’appels d’API qui énumèrent les ressources disponibles, telles que 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 prendre en charge l’automatisation et peut être intégrée dans des pipelines de données récurrents ou des flux de travail planifiés.

Lister les 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 dans le 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

Répertorier les groupes (secteurs d’activité)
/v2/accounts/ {account_id}

Cette ressource renvoie les groupes de secteurs d’activité (tels que les canaux) 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 des entreprises (telles que des noms de chaînes spécifiques) disponibles pour ce compte, en fonction du secteur d’activité concerné.

Exemple de demande

Exemple de réponse

Liste des 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 un canal ou un studio donné. (La liste des ensembles de données disponibles et leurs attributs sont inclus dans les définitions des ensembles de données, plus loin dans cette rubrique.) Les ensembles de données actuellement disponibles au téléchargement sont les suivants :

Abonnement : événements du cycle de vie du client, tels que l’abonnement d’un client.
Lecture : événements de session de lecture 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 un ou plusieurs fichiers de jeux de données
/v2/accounts/ {account_id}/{group_id}/{business_id} /datasets/ {dataset_id} Cette ressource fournit une liste de fichiers de jeux de données.

En fonction de l’intervalle de temps demandé, la liste peut inclure un grand nombre de fichiers. Le champ Total indique le nombre de fichiers attendus. Après avoir effectué un remblayage 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.

Les nouveaux ensembles de données sont publiés toutes les 4 heures environ 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, environ toutes les 4 à 6 heures, pour vous assurer que vos données locales sont aussi complètes et à jour que possible. Si nous constatons un retard dans la publication, nous communiquerons par e-mail dès que possible.

Le tableau suivant décrit les paramètres de demande disponibles pour les fichiers de jeux de données.

Paramètre de demande	Description
Date/heure de début	Il est recommandé de le régler à partir de la dernière fois que vous l’avez extrait. (Format : YYYY-MM-DDTHH:MM:SSZ - horodatage UTC)
Date/heure de fin	Il est recommandé de régler l’heure de la traction/l’heure actuelle. (Format : YYYY-MM-DDTHH:MM:SSZ - horodatage UTC)
limite	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 de jeux de données dont l’horodatage est antérieur à 2 ans ne renverront aucun résultat.

Exemple de demande

Exemple de réponse

Remarques :

La taille maximale du fichier zip est de 300 Mo. Les fichiers qui dépassent cette limite seront divisés en plusieurs fichiers.
La durée de vie (TTL) de l’URL présignée est de 60 minutes.

Définitions des ensembles de

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

Ensemble de données d’abonnement

Colonne	Type	Définition
subscription_event_id (pk)	ficelle	L’ID unique pour chaque événement d’abonnement vendu via ce journal.
type_événement_abonnement	ficelle	Type d’événement d’abonnement qui s’est produit : Start : 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. Annuler : 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 - AR ON : le client est actif et a activé le renouvellement automatique. Actif - AR OFF : le client est actif, mais a désactivé le renouvellement automatique.
subscription_event_time_utc	horodatage	Heure à laquelle l’événement d’abonnement s’est produit, normalisée en UTC.
abonnement_event_time_zone	ficelle	Fuseau horaire du marché des abonnements.
cid	ficelle	Identifiant client anonyme (CID). Cet identifiant client sera conservé pour tous les événements sur un canal parent unique afin de permettre les mouvements entre les niveaux et le suivi du cycle de vie des clients.
identifiant de l’offre	ficelle	L’ID de l’offre d’abonnement spécifique à laquelle l’événement s’est produit.
nom_de l’offre	ficelle	Le nom lisible par l’homme de l’offre.
type_d’offre	ficelle	Le type d’offre.
offre_marketplace	ficelle	Le marché sur lequel l’offre d’abonnement était en ligne.
type d’offre_facturation	ficelle	Type de paiement requis pour l’offre : HO : offre ferme ; paiement requis. FT : essai gratuit ; aucun paiement n’est requis.
montant_de_paiement de l’offre	ficelle	Le montant de facturation de l’offer_id.
identifiant_avantage	ficelle	L’ID de l’avantage Prime Video sous lequel l’offre est configuré.
label_chaîne	ficelle	Le nom de la chaîne sous laquelle l’offre est publiée. Remarque : Si cette colonne affiche une valeur nulle et que vous avez des inquiétudes, veuillez contacter votre CAM ou votre PSm.
channel_tier_label	ficelle	Le nom de la chaîne sous laquelle l’offre est publiée. Remarque : Si cette colonne affiche une valeur nulle et que vous avez des inquiétudes, veuillez contacter votre CAM ou votre PSm.
is_promo	int	Indique si une offre fait partie d’une promotion au moment de l’événement (0 = aucune promotion, 1 = promotion oui).
créer_heure_utc	horodatage	Heure à laquelle l’enregistrement du journal des événements d’abonnement a été créé, normalisée en UTC.
heure_de_dernière_actualisation_utc	horodatage	Heure à laquelle l’enregistrement du journal des événements d’abonnement a été mis à jour pour la dernière fois, normalisée en UTC.
est supprimé	int	Indique si un enregistrement créé précédemment doit être supprimé (0 = doit être conservé, 1 = doit être supprimé).

Ensemble de données de lecture

Colonne	Type	Définition
identifiant_session (pk)	ficelle	ID unique de la session de lecture.
identifiant du marché	int	L’identifiant unique du marché de la lecture.
marketplace_desc	ficelle	Une description conviviale du marché du playback.
cid	ficelle	L’identifiant de l’utilisateur, anonymisé avec l’UUID.
identifiant_avantage	ficelle	L’avantage associé au contenu diffusé en continu.
identifiant du catalogue	ficelle	Clé étrangère (FK) utilisée pour joindre la table du catalogue.
identifiant de l’offre_d’abonnement	ficelle	L’abonnement offer_id auquel le client est abonné au moment du stream (Active ou ApprovalPending).
identifiant_événement_abonnement	ficelle	Clé étrangère (FK) à 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	Start du segment de lecture en UTC.
end_segment_utc	horodatage	Fin du segment de lecture en UTC.
secondes vues	int	Secondes pendant lesquelles l’utilisateur diffuse du contenu pendant la lecture.
position_start	double	Deuxième stream où la session de lecture a débuté.
fin de position	double	Deuxième stream où la session de lecture s’est terminée.
type_de connexion	ficelle	Connexion utilisée par le client pour diffuser le contenu.
type_flux	ficelle	Classification entre les flux de vidéo à la demande, en direct ou juste après la diffusion (JAB).
classe_appareil	ficelle	Type d’appareil (tel que salon, mobile, Web ou autres).
sous-classe_appareil	ficelle	Type d’appareil granulaire (tel qu’une console de jeu, smart_tv, roku).
geo_dma	ficelle	La zone de marché désignée (DMA) géographique à 3 chiffres de la zone où le flux a été généré.
méthode de lecture	ficelle	Indique si la lecture est en ligne ou hors ligne.
qualité	ficelle	Qualité de lecture (1080p ou 4K, par exemple)
type_événement	ficelle	Le type d’événement qui définit (playback_segments)
créer_heure_utc	horodatage	Horodatage de l’ajout de l’enregistrement à la table, en UTC.
heure_de_dernière_actualisation_utc	horodatage	Dernière mise à jour de l’horodatage lorsque l’enregistrement a été modifié, en UTC.
est supprimé	int	Signaler pour indiquer aux partenaires si l’enregistrement doit être supprimé de leur système.

Ensemble de données du catalogue

Colonne	Type	Définition
identifiant (pk)	ficelle	L’ID unique du titre.
identifiant du marché	int	L’ID unique du marché des offres.
identifiant_avantage	ficelle	L’avantage associé à l’extension du contenu.
titre	ficelle	Le titre de la série/du film.
vendor_sku	ficelle	Identifiant arbitraire généré par le fournisseur pour chacun de ses films ou épisodes.
saison	entier	Le numéro de saison (pour le contenu épisodique).
épisode	entier	Le numéro de l’épisode.
nom_épisode	ficelle	Le nom de l’épisode (facultatif).
minutes d’exécution	entier	Durée d’exécution du contenu consulté.
live_linear_channel_name	ficelle	Le nom de la chaîne pour le contenu en direct.
type_contenu	ficelle	Que ce soit pour la télévision ou pour le cinéma.
qualité_du contenu	ficelle	HD ou SD
groupe_contenu	ficelle	3P_SUBS
créer_heure_utc	horodatage	Horodatage de l’ajout de l’enregistrement à la table, en UTC.
heure_de_dernière_actualisation_utc	horodatage	Dernière mise à jour de l’horodatage lorsque l’enregistrement a été modifié, en UTC.
est supprimé	int	Signaler pour indiquer aux partenaires si l’enregistrement doit être supprimé de leur système.

Exemples de requêtes

L’exemple SQL suivant montre comment les tables du jeu 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 de l’abonnement avant ce stream. Dans cet exemple, la colonne catalog_id du jeu de données de lecture est jointe au champ id de catalog_event_log pour fournir toutes les métadonnées du catalogue.

L’exemple SQL suivant renverra les 10 titres les plus regardés en premier par les clients après avoir commencé à s’abonner.

Exemple d’orchestration

Si vous souhaitez automatiser l’extraction de données à partir de l’API Datasets de manière récurrente, l’exemple de script Python suivant montre comment effectuer des appels d’API incrémentiels toutes les 6 heures. Il suit l’horodatage de la dernière demande réussie en le conservant localement, et utilise cette valeur (plus une seconde) comme date de début pour le prochain appel. Le script calcule EndDateTime comme l’heure actuelle, crée les paramètres de requête appropriés et envoie une requête GET avec authentification. Cette approche garantit une récupération continue et sans chevauchement des données entre les fenêtres temporelles et peut être planifiée via Cron ou un autre planificateur de tâches.

API d’ensembles de données

Présentation de l’API Datasets

Avant-premières de l’API Datasets

Utiliser l’API Datasets

Définitions des ensembles de

Exemples de requêtes

Exemple d’orchestration