L’API de notifications vous permet de recevoir des notifications en temps réel pour différents événements liés au contenu sur Prime Video, ce qui vous évite d’avoir à interroger à plusieurs reprises les API de statut. Configurez des flux de travail automatisés qui répondent instantanément aux mises à jour de livraison des actifs et aux changements de statut en temps réel, ce qui vous permet de résoudre les problèmes plus rapidement et de maintenir votre catalogue à jour.
Détection des problèmes en temps réel : recevez des notifications instantanées en cas d’échec des livraisons d’actifs ou de modification du statut réel, ce qui vous permet de résoudre les problèmes immédiatement au lieu de les découvrir des heures ou des jours plus tard par le biais de vérifications manuelles.
Réduction de la charge d’API : éliminez le besoin de demander en permanence les API d’état, réduisant ainsi les coûts de votre infrastructure et le volume d’appels d’API tout en maintenant les informations à jour.
Intégration automatisée des flux de travail : connectez les notifications directement à vos systèmes existants (services AWS ou webhooks) pour déclencher des réponses automatisées, la création de tickets ou des flux de travail d’alerte sans intervention manuelle.
Couverture complète des événements : surveillez à la fois l’état de livraison des actifs et le statut en temps réel de tous vos titres et territoires à partir d’un seul système de notification.
Pour
commencer à utiliser les notifications, trois étapes sont nécessaires :
- Enregistrer une cible : configurez l’endroit où vous souhaitez recevoir des notifications. Vous pouvez choisir entre les services AWS (SQS, SNS, EventBridge) ou les webhooks HTTPS.
- Créer des abonnements : associez les événements que vous souhaitez surveiller à vos cibles enregistrées. Chaque abonnement couvre un sujet (AssetStatus ou OfferStatus), mais vous pouvez vous abonner à plusieurs types d’événements dans ce sujet.
- Recevoir des notifications : une fois configuré, vous recevrez automatiquement des notifications lorsque des événements se produiront en temps réel.
Sujets et événements disponibles
Les sujets regroupent les événements connexes. Lorsque vous créez un abonnement, vous sélectionnez un sujet et spécifiez les événements de ce sujet que vous souhaitez surveiller.
Sujet mis à jour sur LiveStatus
:OfferStatus
Vous avertit lorsque le statut en ligne d’un titre change sur la vitrine Prime Video, c’est-à-dire lorsqu’un titre est mis en ligne ou non.
Qu’est-ce qui déclenche cette notification ? Le statut en ligne ou non disponible d’un titre change sur la vitrine. Utilisez le callbackURL dans la charge utile pour récupérer les détails complets du statut de l’offre via l’API de statut de l’offre.
Charge utile : {
"alid": "partner-listing-id",
"territory": "US",
"marketplace": "US",
"partnerAlias": "partner-alias",
"eventType": "LiveStatusUpdated",
"callbackUrl": "https://partnerapi.primevideo.com/v1/avails/{partnerAlias}/status/{alid}?marketplace={marketplace}&territory={territory}",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
Rubrique actualisée du statut des actifs
:AssetStatus
Vous avertit lorsqu’un actif atteint le résultat final de livraison. Une notification est envoyée lorsque le statut d’un actif devient :
- Expédié : l’actif a été livré avec succès, ou
- Échec : l’actif n’a pas pu être livré ou nécessite une attention particulière.
Qu’est-ce qui déclenche cette notification ? Modification du statut de livraison d’un actif (vidéo, audio, sous-titre, illustration, etc.). Utilisez le callbackURL pour récupérer l’état complet de livraison des actifs, y compris les informations détaillées sur les erreurs, le cas échéant.
Cas d’utilisation :
- Détectez les défaillances de livraison en temps réel et déclenchez des flux de livraison automatisés
- Confirmez la réussite du traitement des actifs sans interroger l’API Statut des actifs
- Intégrez les systèmes de billetterie internes pour une résolution immédiate des problèmes
Charge utile : {
"alid": "partner-listing-id",
"marketplace": "US",
"partnerAlias": "partner-alias",
"eventType": "AssetStatusUpdated",
"callbackUrl": "https://partnerapi.primevideo.com/v1/assets/{partnerAlias}/status/{alid}?marketplace={marketplace}",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
Schémas de demande et de réponse
Cette section fournit des spécifications techniques permettant aux développeurs d’intégrer l’API de notification aux partenaires dans vos systèmes. Utilisez cette référence pour comprendre le format de demande, la structure de réponse et les types de données renvoyés par l’API.
URL de base
Toutes les demandes d’API sont envoyées à l’URL de base suivante. Ajoutez le chemin du point de terminaison approprié à cette URL lorsque vous effectuez des demandes.
https://partnerapi.primevideo.com/v1
Gestion des cibles
Une cible est la destination vers laquelle vous souhaitez recevoir des notifications. Il peut s’agir d’un service AWS (SQS, SNS ou EventBridge) ou d’un point de terminaison de webhook HTTPS. Vous devez enregistrer au moins une cible avant de créer des abonnements.
Enregistrer Target
POST /{licensor}/notifications/targets
Créer une nouvelle cible de notification dans laquelle vous recevrez des notifications d’événements.
Organisme de la demande :
{
"type": "SQS|SNS|EVENTBRIDGE|WEBHOOK",
"destination": "target-destination",
"auth": { /* varies by type */ }
}
Réponse :
{
"targetId": "target-id-1",
"status": "ACTIVE"
}
Lister toutes les
cibles Utilisez ce point de terminaison pour récupérer la liste complète des cibles de notification enregistrées pour votre organisation. Cela est utile pour auditer votre configuration actuelle ou identifier les ID cibles à utiliser lors de la création ou de la mise à jour d’abonnements.
GET /{licensor}/notifications/targets
Récupérez toutes les cibles enregistrées pour votre organisation.
Obtenir une cible spécifique
GET /{licensor}/notifications/targets?targetId={id}
Récupérez les détails d’une cible spécifique.
Mettre à jour la cible
PUT /{licensor}/notifications/targets/{targetId}
Mettez à jour une configuration cible existante.
Supprimer la cible
DELETE /{licensor}/notifications/targets/{targetId}
Supprimez une cible de votre configuration.
Gestion des abonnements
Un abonnement associe un ou plusieurs événements à une cible enregistrée, déterminant ainsi les notifications que vous recevez et leur destination. Chaque abonnement est limité à un seul sujet, mais vous pouvez créer plusieurs abonnements pour couvrir tous les événements liés à votre flux de travail.
Créer un abonnement
POST /{licensor}/notifications/subscriptions
Créer un abonnement pour associer les événements à vos cibles.
Organisme de la demande :
{
"topic": "OfferStatus",
"eventTargetMapping": {
"LiveStatusUpdated": ["target-id-1"]
}
}
Réponse :
{
"subscriptionId": "subscription-id-1",
"status": "ACTIVE"
}
Lister tous les abonnements
GET /{licensor}/notifications/subscriptions
Récupérez tous les abonnements de votre organisation.
Mettre à jour l’abonnement
PUT /{licensor}/notifications/subscriptions/{id}
Mettez à jour une configuration d’abonnement existante.
Supprimer l’abonnement
DELETE /{licensor}/notifications/subscriptions/{id}
Supprimez un abonnement de votre configuration.
Types de cibles
Les types de cibles définissent la manière dont Prime Video envoie les notifications à vos systèmes. Vous pouvez choisir parmi les services gérés par AWS pour une diffusion fiable et évolutive, ou configurer un webhook HTTPS pour recevoir des notifications directement sur votre propre terminal.
Cibles AWS (SQS, SNS, EventBridge)
Champs obligatoires :
- destination — ARN de la ressource AWS
- AssumeRoLearn — Rôle IAM pour la livraison
- ExternalID — Identifiant de sécurité (facultatif mais recommandé)
Exemple SQS : {
"type": "SQS",
"destination": "arn:aws:sqs:{region}:{account-id}:{queue-name}",
"auth": {
"assumeRoleArn": "arn:aws:iam::{account-id}:role/{role-name}",
"externalId": "{external-id}"
}
}
Exemple de SNS : {
"type": "SNS",
"destination": "arn:aws:sns:{region}:{account-id}:{topic-name}",
"auth": {
"assumeRoleArn": "arn:aws:iam::{account-id}:role/{role-name}",
"externalId": "{external-id}"
}
}
Exemple d’EventBridge : {
"type": "EVENTBRIDGE",
"destination": "arn:aws:events:{region}:{account-id}:event-bus/{bus-name}",
"auth": {
"assumeRoleArn": "arn:aws:iam::{account-id}:role/{role-name}",
"externalId": "{external-id}"
}
}
Jeton au porteur : {
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "bearer",
"bearerToken": "your-token"
}
}
Clé d’API : {
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "apiKey",
"apiKey": "your-key",
"apiKeyHeader": "X-API-Key"
}
}
HMAC (recommandé) : {
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "hmac",
"hmacSecret": "your-secret",
"hmacAlgorithm": "HmacSHA256",
"hmacHeader": "X-Signature"
}
}
Charge utile
Structure de charge utile
Toutes les charges utiles de notification suivent une structure cohérente :
Champ |
Description |
|---|---|
valide |
ID de la liste des partenaires (identifiant du titre) |
territoire |
Code de territoire (par exemple, États-Unis, Royaume-Uni) |
marché |
Code du marché |
Alias du partenaire |
Identifiant du partenaire |
Type d’événement |
L’événement spécifique qui s’est produit |
URL de rappel |
URL permettant de récupérer les informations complètes sur le statut |
Horodatage de l’événement |
Horodatage ISO 8601 de l’événement |
Les webhooks reçoivent des requêtes HTTP POST avec la charge utile suivante : {
"alid": "partner-listing-id",
"territory": "US",
"marketplace": "US",
"partnerAlias": "partner-alias",
"eventType": "LiveStatusUpdated",
"callbackUrl": "https://callback-url.com",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
En-têtes d’authentification :
- HMAC : Signature X : {signature} Signature X : {signature}
- Clé d’API : clé d’API X : {clé} clé d’API X : {clé}
- Porteur : porteur {jeton} Autorisation : porteur {jeton}
Réponses aux erreurs
Lorsqu’une demande ne peut pas être traitée, l’API renvoie une réponse d’erreur structurée pour vous aider à identifier et à résoudre le problème. La réponse inclut un code d’erreur et un message lisible par l’homme décrivant le problème.
{
"error": {
"code": "ERROR_CODE",
"message": "Human readable error message"
}
}
Codes d’erreur courants :
- BAD_REQUEST — Paramètres de demande non valides
- NON AUTORISÉ — Échec de l’authentification
- NOT_FOUND — Ressource introuvable
- CONFLIT — La ressource existe déjà
Guide de configuration d’AWS Target
Si vous utilisez un service AWS (SQS, SNS ou EventBridge) comme cible de notification, vous devez configurer un rôle de diffusion IAM pour autoriser Prime Video à envoyer des notifications à vos ressources AWS. Suivez les étapes ci-dessous pour configurer le rôle IAM et les politiques d’autorisation requis avant d’enregistrer votre cible.
Prérequis
- Ressource de destination AWS (file d’attente SQS, rubrique SNS ou bus EventBridge)
- Rôle de prestation IAM avec politiques de confiance et d’autorisation
Configuration du rôle IAM
1. Créer un rôle : console AWS → IAM → Rôles → Créer un rôle → Politique de confiance personnalisée 2. Politique de confiance {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::687801838843:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "{external-id}"
},
"ArnLike": {
"aws:PrincipalArn": "arn:aws:iam::687801838843:role/PVPartnerApiNPS-ExecutionRole-*"
}
}
}
]
}
3. Politique d’autorisation (choisissez-en une) :
SQS :
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["sqs:SendMessage", "sqs:GetQueueUrl"],
"Resource": "arn:aws:sqs:{region}:{account-id}:{queue-name}"
}]
}
Réseau social : {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "sns:Publish",
"Resource": "arn:aws:sns:{region}:{account-id}:{topic-name}"
}]
}
Event Bridge : {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "events:PutEvents",
"Resource": "arn:aws:events:{region}:{account-id}:event-bus/{bus-name}"
}]
}
