Mit der Notifications API können Sie Echtzeitbenachrichtigungen zu verschiedenen Inhaltsereignissen auf Prime Video erhalten – so müssen Sie Status-APIs nicht mehr wiederholt abfragen. Richten Sie automatisierte Workflows ein, die sofort auf Aktualisierungen bei der Bereitstellung von Assets und Statusänderungen reagieren, sodass Sie Probleme schneller beheben und Ihren Katalog auf dem neuesten Stand halten können.
Warum die Notifications API verwenden?
- Problemerkennung in Echtzeit – Erhalten Sie sofortige Benachrichtigungen, wenn die Bereitstellung von Bestands-Assets fehlschlägt oder sich der Status eines Angebots ändert, sodass Sie Probleme umgehend beheben können, anstatt sie erst Stunden oder Tage später bei manuellen Überprüfungen zu entdecken.
- Reduzierter API-Overhead – Machen Sie die ständige Abfrage von Status-APIs überflüssig, senken Sie so Ihre Infrastrukturkosten und das Volumen der API-Aufrufe und sorgen Sie dennoch für stets aktuelle Informationen.
- Automatisierte Workflow-Integration – Verbinden Sie Benachrichtigungen direkt mit Ihren bestehenden Systemen (AWS-Services oder Webhooks), um automatisierte Antworten, die Erstellung von Tickets oder Alarm-Workflows ohne manuellen Eingriff auszulösen.
- Umfassende Event-Berichterstattung – Überwachen Sie den Status der Asset-Bereitstellung sowie die Verfügbarkeit von Angeboten für alle Ihre Titel und Regionen über ein einziges Benachrichtigungssystem.
Erste Schritte
Um mit Benachrichtigungen zu beginnen, sind drei Schritte erforderlich:
- Ein Ziel registrieren: Richten Sie ein, wo Sie Benachrichtigungen erhalten möchten. Sie können zwischen AWS-Services (SQS, SNS, EventBridge) oder HTTPS-Webhooks wählen.
- Abonnements erstellen: Ordnen Sie die Ereignisse, die Sie überwachen möchten, Ihren registrierten Zielen zu. Jedes Abonnement deckt ein Thema ab (AssetStatus oder OfferStatus), aber Sie können innerhalb dieses Themas mehrere Ereignistypen abonnieren.
- Benachrichtigungen erhalten: Nach der Konfiguration erhalten Sie automatisch Benachrichtigungen, wenn Ereignisse in Echtzeit eintreten.
Anfrage- und Antwortschemas
Dieser Abschnitt enthält technische Spezifikationen für Entwickler zur Integration der Partner Notification API in Ihre Systeme. Verwenden Sie 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ügen Sie 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 Sie Benachrichtigungen erhalten möchten – dies kann ein AWS-Service (SQS, SNS oder EventBridge) oder ein HTTPS-Webhook-Endpunkt sein. Sie müssen mindestens ein Ziel registrieren, bevor Sie Abonnements erstellen können.
Target registrieren
POST /{licensor}/notifications/targets
Erstellen Sie 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
Verwenden Sie diesen Endpunkt, um eine vollständige Liste der für Ihre Organisation registrierten Benachrichtigungsempfänger abzurufen. Dies ist nützlich, um Ihre 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 Ihre 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 Ihrer Konfiguration gelöscht.
Abonnementverwaltung
Ein Abonnement ordnet einem registrierten Empfänger ein oder mehrere Ereignisse zu und legt fest, welche Benachrichtigungen Sie erhalten und wohin diese gesendet werden. Jedes Abonnement bezieht sich auf ein einzelnes Thema, Sie können jedoch mehrere Abonnements erstellen, um alle für Ihren Workflow relevanten Ereignisse abzudecken.
Abonnement erstellen
POST /{licensor}/notifications/subscriptions
Es wird ein Abonnement erstellt, um Ereignisse Ihren Zielen zuzuordnen.
Anfragetext:{
"topic": "OfferStatus",
"eventTargetMapping": {
"LiveStatusUpdated": ["target-id-1"],
"OfferStatusUpdated": ["target-id-2"]
}
}
Antwort:{
"subscriptionId": "subscription-id-1",
"status": "ACTIVE"
}
Alle Abonnements auflisten
GET /{licensor}/notifications/subscriptions
Es werden alle Abonnements für Ihre 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 Ihrer Konfiguration gelöscht.
Verfügbare Themen und Veranstaltungen
Themen gruppieren verwandte Ereignisse zusammen. Wenn Sie ein Abonnement erstellen, wählen Sie ein Thema aus und geben an, welche Ereignisse innerhalb dieses Themas Sie überwachen möchten. Jedes Thema ist einem bestimmten Bereich der Statusverfolgung von Inhalten zugeordnet.
- LiveStatusUpdated – Wenn sich der Live-Status ändert
- OfferStatusUpdated – Wenn sich der Angebotsstatus ändert (In Kürze verfügbar)
- AssetStatusUpdated – Wenn sich der Asset-Status ändert (In Kürze verfügbar)
Zieltypen
Zieltypen definieren, wie Prime Video Benachrichtigungen an Ihre Systeme sendet. Sie können zwischen von AWS verwalteten Services für eine zuverlässige und skalierbare Bereitstellung wählen oder einen HTTPS-Webhook konfigurieren, um Benachrichtigungen direkt an Ihrem 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}"
}
}
Webhook-Ziele – Bearer Token{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "bearer",
"bearerToken": "your-token"
}
}
Webhook-Ziele – API-Schlüssel:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "apiKey",
"apiKey": "your-key",
"apiKeyHeader": "X-API-Key"
}
}
Webhook-Ziele – HMAC (empfohlen):{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "hmac",
"hmacSecret": "your-secret",
"hmacAlgorithm": "HmacSHA256",
"hmacHeader": "X-Signature"
}
}
Nutzdaten
Webhooks empfangen HTTP-POST-Anfragen mit folgenden Nutzdaten:{
"alid": "partner-listing-id",
"territory": "US",
"marketplace": "US",
"eventType": "LiveStatusUpdated",
"callbackUrl": "https://callback-url.com",
"eventTimestamp": "2024-01-01T00:00:00.000Z"
}
Authentifizierungs-Header:
- HMAC: X-Signatur: {signature}
- API-Schlüssel: X-API-Schlüssel: {key}
- Bearer: Autorisierung: Bearer {token}
Antworten auf Fehler
Wenn eine Anfrage nicht abgeschlossen werden kann, gibt die API eine strukturierte Fehlerantwort zurück, die Ihnen 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 Target
Wenn Sie einen AWS-Service (SQS, SNS oder EventBridge) als Benachrichtigungsziel verwenden, müssen Sie eine IAM-Bereitstellungsrolle konfigurieren, um Prime Video die Berechtigung zu erteilen, Benachrichtigungen an Ihre AWS-Ressourcen zu senden. Befolgen Sie die folgenden Schritte, um die erforderlichen IAM-Rollen- und Berechtigungsrichtlinien einzurichten, bevor Sie Ihr Ziel registrieren.
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:role/PVPartnerApiNotificationP-EcsTaskInstanceRoleE38DB4-qWjKHaQBhouq"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "{external-id}"
}
}
}]
}
3. Berechtigungsrichtlinien (eine der folgenden Optionen 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}"
}]
}
