Mit der Notifications API kannst du Echtzeitbenachrichtigungen zu verschiedenen Inhaltsereignissen auf Prime Video erhalten – so musst du Status-APIs nicht mehr wiederholt abfragen. Richte automatisierte Workflows ein, die sofort auf Aktualisierungen bei der Bereitstellung von Assets und Live-Statusänderungen reagieren, sodass du Probleme schneller beheben und deinen Katalog auf dem neuesten Stand halten kannst.
Problemerkennung in Echtzeit – Erhalte sofortige Benachrichtigungen, wenn die Bereitstellung von Bestands-Assets fehlschlägt oder sich der Live-Status ändert, sodass du Probleme umgehend beheben kannst, anstatt sie erst Stunden oder Tage später bei manuellen Überprüfungen zu entdecken.
Reduzierter API-Overhead – Mach ständige Abfragen von Status-APIs überflüssig, senke so deine Infrastrukturkosten und das Volumen der API-Aufrufe und sorge dennoch für stets aktuelle Informationen.
Automatisierte Workflow-Integration – Verbinde Benachrichtigungen direkt mit deinen bestehenden Systemen (AWS-Services oder Webhooks), um automatisierte Antworten, die Erstellung von Tickets oder Alarm-Workflows ohne manuellen Eingriff auszulösen.
Umfassende Event-Berichterstattung – Überwache den Status der Asset-Bereitstellung sowie die Live-Status für alle deine Titel und Regionen über ein einziges Benachrichtigungssystem.
Erste Schritte
Um mit Benachrichtigungen zu beginnen, sind drei Schritte erforderlich:
- Ein Ziel registrieren: Richte ein, wo du Benachrichtigungen erhalten möchtest. Du kannst zwischen AWS-Services (SQS, SNS, EventBridge) oder HTTPS-Webhooks wählen.
- Abonnements erstellen: Ordne die Ereignisse, die du überwachen möchtest, deinen registrierten Zielen zu. Jedes Abonnement deckt ein Thema ab (AssetStatus oder OfferStatus), aber du kannst innerhalb dieses Themas mehrere Ereignistypen abonnieren.
- Benachrichtigungen erhalten: Nach der Konfiguration erhältst du automatisch Benachrichtigungen in Echtzeit, wenn Ereignisse eintreten.
Verfügbare Themen und Veranstaltungen
Themen gruppieren verwandte Ereignisse zusammen. Wenn du ein Abonnement erstellst, wähle ein Thema aus und gib an, welche Ereignisse innerhalb dieses Themas du überwachen möchtest.
LiveStatusUpdated
Thema: OfferStatus
Informiert dich, wenn sich der Live-Status eines Titels auf der Prime-Video-Storefront ändert – d. h. wenn ein Titel live geht oder sich zu nicht live ändert.
Was löst diese Benachrichtigung aus? Der Live-/Nicht-Live-Status eines Titels ändert sich auf der Storefront. Verwende die callbackUrl in den Nutzdaten, um vollständige Angebotsstatusdetails über die Angebotsstatus-API abzurufen.
Nutzdaten:{
"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
Thema: AssetStatus
Benachrichtigt dich, sobald ein Asset ein endgültiges Bereitstellungsergebnis erreicht hat. Eine Benachrichtigung wird gesendet, wenn der Status eines Assets wie folgt lautet:
- Versendet – das Asset wurde erfolgreich bereitgestellt, oder
- Fehlgeschlagen – das Asset konnte nicht bereitgestellt werden oder muss bearbeitet werden.
Was löst diese Benachrichtigung aus? Eine Änderung des Bereitstellungsstatus eines Assets (z. B. Video, Audio, Untertitel, Bildmaterial). Verwende die callbackUrl, um den vollständigen Status der Asset-Bereitstellung abzurufen, einschließlich detaillierter Fehlerinformationen, sofern zutreffend.
Anwendungsfälle:
- Erkenne Fehler bei der Bereitstellung in Echtzeit und löse automatisierte Workflows für die erneute Lieferung aus
- Bestätige die erfolgreiche Asset-Verarbeitung, ohne die Asset-Status-API abzufragen
- Integriere es in interne Ticketsysteme, um Probleme sofort zu lösen
Nutzdaten:{
"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"
}
Anfrage- und Antwortschemas
Dieser Abschnitt enthält technische Spezifikationen für Entwickelnde zur Integration der Partner Notification API in deine Systeme. Verwende diese Referenz, um das Anfrageformat, die Antwortstruktur und die von der API zurückgegebenen Datentypen zu verstehen.
Basis-URL
Alle API-Anfragen werden an die folgende Basis-URL gestellt. Füge bei der Übermittlung von Anfragen den entsprechenden Endpunktpfad an diese URL an.
https://partnerapi.primevideo.com/v1
Zielmanagement
Ein Ziel ist der Ort, an dem du Benachrichtigungen erhalten möchtest – dies kann ein AWS-Service (SQS, SNS oder EventBridge) oder ein HTTPS-Webhook-Endpunkt sein. Du musst mindestens ein Ziel registrieren, bevor du Abonnements erstellen kannst.
Ziel registrieren
POST /{licensor}/notifications/targets
Erstelle ein neues Benachrichtigungsziel, an das Ereignisbenachrichtigungen gesendet werden sollen.
Anfragetext:
{
"type": "SQS|SNS|EVENTBRIDGE|WEBHOOK",
"destination": "target-destination",
"auth": { /* varies by type */ }
}
Antwort:
{
"targetId": "target-id-1",
"status": "ACTIVE"
}
Alle Ziele auflisten
Verwende diesen Endpunkt, um eine vollständige Liste der für deine Organisation registrierten Benachrichtigungsempfänger abzurufen. Dies ist nützlich, um deine aktuelle Konfiguration zu überprüfen oder Ziel-IDs zu ermitteln, die beim Erstellen oder Aktualisieren von Abonnements verwendet werden sollen.
GET /{licensor}/notifications/targets
Es werden alle registrierten Ziele für deine Organisation abgerufen.
Spezifisches Ziel abrufen
GET /{licensor}/notifications/targets?targetId={id}
Es werden Details für ein bestimmtes Ziel abgerufen.
Ziel aktualisieren
PUT /{licensor}/notifications/targets/{targetId}
Es wird eine bestehende Zielkonfiguration aktualisiert.
Ziel löschen
DELETE /{licensor}/notifications/targets/{targetId}
Es wird ein Ziel aus deiner Konfiguration gelöscht.
Abonnementverwaltung
Ein Abonnement ordnet einem registrierten Ziel ein oder mehrere Ereignisse zu und legt fest, welche Benachrichtigungen du erhältst und wohin diese gesendet werden. Jedes Abonnement bezieht sich auf ein einzelnes Thema, du kannst jedoch mehrere Abonnements erstellen, um alle für deinen Workflow relevanten Ereignisse abzudecken.
Abonnement erstellen
POST /{licensor}/notifications/subscriptions
Es wird ein Abonnement erstellt, um Ereignisse deinen Zielen zuzuordnen.
Anfragetext:
{
"topic": "OfferStatus",
"eventTargetMapping": {
"LiveStatusUpdated": ["target-id-1"]
}
}
{
"topic": "AssetStatus",
"eventTargetMapping": {
"AssetStatusUpdated": ["target-id-1"]
}
}
Antwort:
{
"subscriptionId": "subscription-id-1",
"status": "ACTIVE"
}
Alle Abonnements auflisten
GET /{licensor}/notifications/subscriptions
Es werden alle Abonnements für deine Organisation abgerufen.
Abonnement aktualisieren
PUT /{licensor}/notifications/subscriptions/{id}
Es wird eine bestehende Abonnement-Konfiguration aktualisiert.
Abonnement löschen
DELETE /{licensor}/notifications/subscriptions/{id}
Es wird ein Abonnement aus deiner Konfiguration gelöscht.
Zieltypen
Zieltypen definieren, wie Prime Video Benachrichtigungen an deine Systeme sendet. Du kannst zwischen von AWS verwalteten Services für eine zuverlässige und skalierbare Bereitstellung wählen oder einen HTTPS-Webhook konfigurieren, um Benachrichtigungen direkt an deinem eigenen Endpunkt zu empfangen.
AWS-Ziele (SQS, SNS, EventBridge)
Erforderliche Felder:
- destination – ARN der AWS-Ressource
- assumeRoleArn – IAM-Rolle für die Bereitstellung
- externalId – Sicherheits-ID (optional, aber empfohlen)
SQS-Beispiel:{
"type": "SQS",
"destination": "arn:aws:sqs:{region}:{account-id}:{queue-name}",
"auth": {
"assumeRoleArn": "arn:aws:iam::{account-id}:role/{role-name}",
"externalId": "{external-id}"
}
}
SNS-Beispiel:{
"type": "SNS",
"destination": "arn:aws:sns:{region}:{account-id}:{topic-name}",
"auth": {
"assumeRoleArn": "arn:aws:iam::{account-id}:role/{role-name}",
"externalId": "{external-id}"
}
}
EventBridge-Beispiel:{
"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}"
}
}
Bearer-Token:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "bearer",
"bearerToken": "your-token"
}
}
API-Schlüssel:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "apiKey",
"apiKey": "your-key",
"apiKeyHeader": "X-API-Key"
}
}
HMAC (empfohlen):{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "hmac",
"hmacSecret": "your-secret",
"hmacAlgorithm": "HmacSHA256",
"hmacHeader": "X-Signature"
}
}
Nutzdaten
Struktur der Nutzdaten
Alle Benachrichtigungsnutzdaten folgen einer konsistenten Struktur:
Feld |
Beschreibung |
|---|---|
alid |
Partnerangebots-ID (Titelkennzeichnung) |
Gebiet |
Gebietscode (z. B. USA, GB) |
Marketplace |
Marketplace code |
partnerAlias |
Partner-ID |
eventType |
Das spezifische Ereignis, das eingetreten ist |
callbackUrl |
URL zum Abrufen der vollständigen Statusdetails |
eventTimestamp |
ISO-8601-Zeitstempel des Ereignisses |
Webhooks empfangen HTTP-POST-Anfragen mit folgenden Nutzdaten:{
"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"
}
Authentifizierungs-Header:
- HMAC: X-Signatur: {signature}X-Signatur: {signature}
- API-Schlüssel: X-API-Schlüssel: {key}X-API-Schlüssel: {key}
- Bearer: Bearer-{token}Autorisierung: Bearer {token}
Antworten auf Fehler
Wenn eine Anfrage nicht abgeschlossen werden kann, gibt die API eine strukturierte Fehlerantwort zurück, die dir dabei hilft, das Problem zu identifizieren und zu beheben. Die Antwort enthält einen Fehlercode und eine menschenlesbare Meldung, die das Problem beschreibt.
{
"error": {
"code": "ERROR_CODE",
"message": "Human readable error message"
}
}
Häufige Fehlercodes:
- BAD_REQUEST – Ungültige Anfrageparameter
- UNAUTHORIZED – Authentifizierung fehlgeschlagen
- NOT_FOUND – Ressource wurde nicht gefunden
- CONFLICT – Ressource ist bereits vorhanden
Anleitung zur Einrichtung von AWS-Ziel
Wenn du einen AWS-Service (SQS, SNS oder EventBridge) als Benachrichtigungsziel verwendest, musst du eine IAM-Bereitstellungsrolle konfigurieren, um Prime Video die Berechtigung zu erteilen, Benachrichtigungen an deine AWS-Ressourcen zu senden. Befolge die folgenden Schritte, um die erforderlichen IAM-Rollen- und Berechtigungsrichtlinien einzurichten, bevor du dein Ziel registrierst.
Voraussetzungen
- AWS-Zielressource (SQS Queue, SNS Topic oder EventBridge Bus)
- IAM-Bereitstellungsrolle mit Vertrauens- und Berechtigungsrichtlinien
Einrichtung der IAM-Rolle
1. Rolle erstellen: AWS-Konsole → IAM → Rollen → Rolle erstellen → Benutzerdefinierte Vertrauensrichtlinien
2. Vertrauensrichtlinien{
"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. Berechtigungsrichtlinien (eine auswählen):
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}"
}]
}
