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 à leur changements de statut de diffusion, 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 lors de l’échec d’une livraison d’éléments ou de changement de leur statut de diffusion, 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 le statut de diffusion 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.
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.
LiveStatusUpdated
Sujet : OfferStatus
Vous avertit lorsque le statut de diffusion d’un titre change sur la page d’accueil de Prime Video, c’est-à-dire lorsqu’un titre est en ligne ou hors ligne.
Qu’est-ce qui déclenche cette notification ? Le statut en ligne ou hors ligne d’un titre change sur la page d’accueil. Utilisez l’URL de rappel (callbackUrl) dans la charge utile pour récupérer toutes les informations de statut de l’offre via l’API Offer Status.
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"
}
AssetStatusUpdated
Sujet : AssetStatus
Vous informe dès qu’un élément atteint le résultat final d’une livraison. Une notification est envoyée lorsque le statut d’un élément devient :
- Livré : l’élément a bien été livré ou
- Échec : l’élément n’a pas pu être livré ou nécessite une attention particulière.
Qu’est-ce qui déclenche cette notification ? Une modification de l’état de diffusion d’un élément (par exemple, vidéo, audio, sous-titre, illustration). Utilisez le callbackURL pour récupérer l’état complet de livraison des éléments, y compris des informations détaillées sur les erreurs, le cas échéant.
Cas d’utilisation :
- Détecter les échecs de livraison en temps réel et déclenchez des flux de relivraison automatisés
- Confirmer le succès du traitement des éléments sans interroger l’API Asset Status
- S’intégrer aux systèmes de gestion des tickets 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 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"]
}
}
{
"topic": "AssetStatus",
"eventTargetMapping": {
"AssetStatusUpdated": ["target-id-1"]
}
}
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.
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}"
}
}
Jeton du porteur :{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "bearer",
"bearerToken": "your-token"
}
}
Clé 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 la charge utile
Toutes les charges utiles de notification suivent une structure similaire :
Champ |
Description |
|---|---|
alid |
Identifiant de mise en vente des partenaires (identifiant du titre) |
territoire |
Code de territoire (par exemple, US, GB) |
site de vente |
Code du site de vente |
partnerAlias |
Identifiant du partenaire |
eventType |
L’événement spécifique qui s’est produit |
callbackUrl |
URL pour récupérer les informations complètes sur l’état |
eventTimestamp |
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 : X-Signature : {signature}X-Signature : {signature}
- Clé API : X-API-Key : {key}X-API-Key :{key}
- Porteur : Autorisation {token}du porteur : Porteur {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: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}"
}]
}
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}"
}]
}
