L’API Notifications vous permet de recevoir des notifications en temps réel pour divers é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 éléments et aux changements de statut des offres, ce qui vous permet de résoudre les problèmes plus rapidement et de maintenir votre catalogue à jour.
Pourquoi utiliser l’API Notifications ?
- Détection des problèmes en temps réel : recevez des notifications instantanées lors de l’échec d’une livraison d’éléments ou si le statut des offres change, 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 lors de contrôles manuels.
- Réduction des frais d’API : éliminez le besoin d’interroger en permanence l’état des API, ce qui réduit 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 alertes de flux de travail sans intervention manuelle.
- Couverture complète des événements : surveillez à la fois l’état de livraison des éléments et la disponibilité des offres de tous vos titres sur tous vos territoires à partir d’un système de notification unique.
Premiers pas
Pour commencer à utiliser les notifications, il faut suivre trois étapes :
- Enregistrer une cible : Configurez l’endroit où vous souhaitez recevoir les 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 aux cibles que vous avez enregistrées. Chaque abonnement couvre un sujet (AssetStatus ou OfferStatus), mais vous pouvez vous abonner à plusieurs types d’événements dans le cadre de ce sujet.
- Recevoir des notifications : Après la configuration, vous recevrez automatiquement des notifications en temps réel lorsque des événements se produiront.
Schémas de requête et de réponse
Cette section fournit des spécifications techniques permettant aux développeurs d’intégrer l’API de notification des partenaires dans vos systèmes. Utilisez cette référence pour comprendre le format de requête, la structure de réponse et les types de données renvoyés par l’API.
URL de base
Toutes les requêtes d’API sont adressées à l’URL de base suivante. Ajoutez le chemin d’accès au point de terminaison approprié à cette URL lorsque vous effectuez des requêtes.
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 la cible
POST /{licensor}/notifications/targets
Créer une nouvelle cible de notification dans laquelle vous recevrez des notifications d’événements.
Corps de la requête :
{
"type": "SQS|SNS|EVENTBRIDGE|WEBHOOK",
"destination": "target-destination",
"auth": { /* varies by type */ }
}
Réponse :
{
"targetId": "target-id-1",
"status": "ACTIVE"
}
Liste de 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 identifiants cibles à utiliser lors de la création ou de la mise à jour des abonnements.
GET /{licensor}/notifications/targets
Récupérer toutes les cibles enregistrées pour votre organisation.
Obtenir une cible spécifique
GET /{licensor}/notifications/targets?targetId={id}
Récupérer les détails d’une cible spécifique.
Mettre à jour la cible
PUT/{licensor}/notifications/targets/{targetId}
Mettre à jour une configuration cible existante.
Supprimer la cible
DELETE /{licensor}/notifications/targets/{targetId}
Supprimer une cible de votre configuration.
Gestion des abonnements
Un abonnement associe un ou plusieurs événements à une cible enregistrée, ce qui détermine les notifications que vous recevrez et où elles seront envoyées. Chaque abonnement est limité à un seul sujet, mais vous pouvez créer plusieurs abonnements pour couvrir tous les événements pertinents pour votre flux de travail.
Créer un abonnement
POST /{licensor}/notifications/subscriptions
Créer un abonnement pour associer les événements à vos cibles.
Corps de la requête :{
"topic": "OfferStatus",
"eventTargetMapping": {
"LiveStatusUpdated": ["target-id-1"],
"OfferStatusUpdated": ["target-id-2"]
}
}
Réponse : {
"subscriptionId": "subscription-id-1",
"status": "ACTIVE"
}
Répertorier tous les abonnements
GET /{licensor}/notifications/subscriptions
Récupérer tous les abonnements de votre organisation.
Mettre à jour un abonnement
PUT /{licensor}/notifications/subscriptions/{id}
Mettre à jour une configuration d’abonnement existante.
Supprimer un abonnement
DELETE /{licensor}/notifications/subscriptions/{id}
Supprimer un abonnement de votre configuration.
Sujets et événements disponibles
Les sujets regroupent les événements connexes. Lorsque vous créez un abonnement, vous sélectionnez un sujet et vous spécifiez les événements de ce sujet que vous souhaitez surveiller. Chaque sujet correspond à un domaine spécifique du suivi de l’état du contenu.
- LiveStatusUpdated : quand le statut de mise en ligne change
- OfferStatusUpdated : quand le statut de l’offre change (bientôt disponible)
- AssetStatusUpdated : quand le statut d’un élément change (bientôt disponible)
Types de cibles
Les types de cibles définissent comment Prime Video envoie les notifications à vos systèmes. Vous pouvez choisir parmi les services gérés par AWS pour une livraison fiable et évolutive, ou configurer un webhook HTTPS pour recevoir des notifications directement sur votre propre point de terminaison.
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 de 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 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}"
}
}
Cibles Webhook - Jeton porteur : {
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "bearer",
"bearerToken": "your-token"
}
}
Cibles Webhook - Clé API : {
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "apiKey",
"apiKey": "your-key",
"apiKeyHeader": "X-API-Key"
}
}
Cibles Webhook - HMAC (recommandé) : {
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "hmac",
"hmacSecret": "your-secret",
"hmacAlgorithm": "HmacSHA256",
"hmacHeader": "X-Signature"
}
}
Charge utile
Les webhooks reçoivent des requêtes HTTP POST avec la charge utile suivante :{
"alid": "partner-listing-id",
"territory": "US",
"marketplace": "US",
"eventType": "LiveStatusUpdated",
"callbackUrl": "https://callback-url.com",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
En-têtes d’authentification :
- HMAC : X-Signature : {signature}
- Clé API : X-API-Key : {key}
- Porteur : Authorization : Bearer {token}
Réponses d’erreurs
Lorsqu’une requête 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 comprend 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 requête non valides
- UNAUTHORIZED : échec de l’authentification
- NOT_FOUND : ressource introuvable
- CONFLICT : la ressource existe déjà
Guide de configuration de cible AWS
Si vous utilisez un service AWS (SQS, SNS ou EventBridge) comme cible de notification, vous devez configurer un rôle de livraison 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 nécessaires avant d’enregistrer votre cible.
Pré-requis
- Ressource de destination AWS (file d’attente SQS, rubrique SNS ou bus EventBridge)
- Rôle de livraison 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:role/PVPartnerApiNotificationP-EcsTaskInstanceRoleE38DB4-qWjKHaQBhouq"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "{external-id}"
}
}
}]
}
3. Politique d’autorisation (choisissez l’une des options suivantes)
SQS : {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["sqs:SendMessage", "sqs:GetQueueUrl"],
"Resource": "arn:aws:sqs:{region}:{account-id}:{queue-name}"
}]
}
SNS : {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "sns:Publish",
"Resource": "arn:aws:sns:{region}:{account-id}:{topic-name}"
}]
}
EventBridge : {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "events:PutEvents",
"Resource": "arn:aws:events:{region}:{account-id}:event-bus/{bus-name}"
}]
}
