Mit der Benachrichtigungs-API können Sie Echtzeitbenachrichtigungen für verschiedene Inhaltsereignisse auf Prime Video erhalten, sodass Sie die Status-APIs nicht wiederholt abfragen müssen. Richten Sie automatisierte Workflows ein, die sofort auf Aktualisierungen der Warenzustellung und Live-Statusänderungen reagieren, sodass Sie Probleme schneller lösen und Ihren Katalog auf dem neuesten Stand halten können.
Problemerkennung in Echtzeit — Erhalten Sie sofortige Benachrichtigungen, wenn Anlagenlieferungen fehlschlagen oder sich der Live-Status ändert, sodass Sie Probleme sofort beheben können, anstatt sie Stunden oder Tage später durch manuelle Prüfungen zu entdecken.
Geringerer API-Overhead — Eliminieren Sie die Notwendigkeit, ständig Status-APIs abzufragen, und reduzieren Sie so Ihre Infrastrukturkosten und das API-Aufrufvolumen, während Sie gleichzeitig aktuelle Informationen beibehalten.
Automatisierte Workflow-Integration — Verbinden Sie Benachrichtigungen direkt mit Ihren vorhandenen Systemen (AWS-Services oder Webhooks), um automatisierte Antworten, Ticketerstellung oder Alert-Workflows ohne manuelles Eingreifen auszulösen.
Umfassende Berichterstattung über Veranstaltungen — Überwachen Sie sowohl den Status der Auslieferung von Inhalten als auch den Live-Status in all Ihren Titeln und Gebieten von einem einzigen Benachrichtigungssystem aus.
Erste Schritte Um mit Benachrichtigungen zu beginnen, sind drei Schritte erforderlich:
- Ein Ziel registrieren: Lege fest, wo du Benachrichtigungen erhalten möchtest. 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.
Verfügbare Themen und Veranstaltungen
Themen gruppieren verwandte Ereignisse. Wenn Sie ein Abonnement erstellen, wählen Sie ein Thema aus und geben an, welche Ereignisse innerhalb dieses Themas Sie überwachen möchten.
LiveStatusAktualisiertes Thema
:OfferStatus
Benachrichtigt Sie, wenn sich der Live-Status eines Titels in der Prime Video-Storefront ändert, d. h. wenn ein Titel live geht oder nicht.
Was löst diese Benachrichtigung aus? In der Storefront ändert sich der Live-Status eines Titels bzw. der Status „Nicht live“. Verwenden Sie die CallbackURL in der Payload, um die vollständigen Angebotsstatusdetails über die Angebotsstatus-API abzurufen.
Nutzlast: {
"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"
}
Thema „AssetStatus
“ aktualisiert:AssetStatus
Benachrichtigt Sie, sobald ein Asset das endgültige Lieferziel erreicht hat. Eine Benachrichtigung wird gesendet, wenn der Status einer Anlage wie folgt lautet:
- Erfüllt — das Asset wurde erfolgreich geliefert, oder
- Fehlgeschlagen — Die Anlage konnte nicht geliefert werden oder muss bearbeitet werden.
Was löst diese Benachrichtigung aus? Eine Änderung des Lieferstatus eines Assets (z. B. Video, Audio, Untertitel, Grafik). Verwenden Sie die CallbackURL, um den vollständigen Lieferstatus des Assets abzurufen, einschließlich detaillierter Fehlerinformationen, sofern zutreffend.
Anwendungsfälle:
- Erkennen Sie Lieferfehler in Echtzeit und lösen Sie automatisierte Workflows für die erneute Lieferung aus
- Bestätigen Sie die erfolgreiche Asset-Verarbeitung, ohne die Asset-Status-API abzufragen
- Integrieren Sie es in interne Ticketsysteme, um Probleme sofort zu lösen
Nutzlast: {
"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 Entwickler zur Integration der Partner Notification API in Ihre Systeme. Verwenden Sie diese Referenz, um das Anforderungsformat, die Antwortstruktur und die von der API zurückgegebenen Datentypen zu verstehen.
Basis-URL
Alle API-Anfragen werden an die folgende Basis-URL gestellt. Hängen Sie bei Anfragen den entsprechenden Endpunktpfad an diese URL an.
https://partnerapi.primevideo.com/v1
Zielverwaltung
Ein Ziel ist das Ziel, an dem Sie Benachrichtigungen erhalten möchten. Dabei kann es sich um einen AWS-Service (SQS, SNS oder EventBridge) oder einen HTTPS-Webhook-Endpunkt handeln. Sie müssen mindestens ein Ziel registrieren, bevor Sie Abonnements erstellen können.
Target registrieren
POST /{licensor}/notifications/targets
Erstellen Sie ein neues Benachrichtigungsziel, über das Sie Ereignisbenachrichtigungen erhalten.
Hauptteil der Anfrage:
{
"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 Benachrichtigungsziele abzurufen. Dies ist nützlich, um Ihre aktuelle Konfiguration zu überprüfen oder Ziel-IDs zu identifizieren, die bei der Erstellung oder Aktualisierung von Abonnements verwendet werden sollen.
GET /{licensor}/notifications/targets
Rufen Sie alle registrierten Ziele für Ihre Organisation ab.
Spezifisches Ziel abrufen
GET /{licensor}/notifications/targets?targetId={id}
Rufen Sie Details für ein bestimmtes Ziel ab.
Ziel aktualisieren
PUT /{licensor}/notifications/targets/{targetId}
Aktualisieren Sie eine bestehende Zielkonfiguration.
Ziel löschen
DELETE /{licensor}/notifications/targets/{targetId}
Entfernen Sie ein Ziel aus Ihrer Konfiguration.
Abonnementverwaltung
Ein Abonnement ordnet ein oder mehrere Ereignisse einem registrierten Ziel zu und bestimmt, welche Benachrichtigungen Sie erhalten und wo sie zugestellt werden. Jedes Abonnement ist auf ein einzelnes Thema beschränkt. Sie können jedoch mehrere Abonnements erstellen, um alle Ereignisse abzudecken, die für Ihren Workflow relevant sind.
Abonnement erstellen
POST /{licensor}/notifications/subscriptions
Erstellen Sie ein Abonnement, um Ereignisse Ihren Zielen zuzuordnen.
Hauptteil der Anfrage:
{
"topic": "OfferStatus",
"eventTargetMapping": {
"LiveStatusUpdated": ["target-id-1"]
}
}
Antwort:
{
"subscriptionId": "subscription-id-1",
"status": "ACTIVE"
}
Alle Abonnements auflisten
GET /{licensor}/notifications/subscriptions
Rufen Sie alle Abonnements für Ihre Organisation ab.
Abonnement aktualisieren
PUT /{licensor}/notifications/subscriptions/{id}
Aktualisieren Sie eine bestehende Abonnementkonfiguration.
Abonnement löschen
DELETE /{licensor}/notifications/subscriptions/{id}
Entfernen Sie ein Abonnement aus Ihrer Konfiguration.
Zieltypen
Zieltypen definieren, wie Prime Video Benachrichtigungen an Ihre Systeme übermittelt. Sie können zwischen AWS-verwalteten Diensten für eine zuverlässige, skalierbare Bereitstellung wählen oder einen HTTPS-Webhook konfigurieren, um Benachrichtigungen direkt an Ihrem eigenen Endpunkt zu erhalten.
AWS-Ziele (SQS, SNS, EventBridge)
Erforderliche Felder:
- Ziel — 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}"
}
}
Inhaber-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"
}
}
Nutzlast
Payload-Struktur
Alle Payloads für Benachrichtigungen folgen einer konsistenten Struktur:
Feld |
Description |
|---|---|
gültig |
Partnereintrags-ID (Titel-ID) |
Gebiet |
Gebietscode (z. B. US, GB) |
Marktplatz |
Code für den Marktplatz |
Partner-Alias |
Partner-ID |
Ereignistyp |
Das spezifische Ereignis, das eingetreten ist |
Callback-URL |
URL zum Abrufen der vollständigen Statusdetails |
Zeitstempel des Ereignisses |
ISO 8601-Zeitstempel des Ereignisses |
Webhooks empfangen HTTP-POST-Anfragen mit der folgenden Nutzlast: {
"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: {Signatur} X-Signatur: {Signatur}
- API-Schlüssel: X-API-Schlüssel: {Schlüssel} X-API-Schlüssel: {Schlüssel}
- Inhaber: Inhaber {Token} Autorisierung: Inhaber {Token}
Antworten auf Fehler
Wenn eine Anfrage nicht abgeschlossen werden kann, gibt die API eine strukturierte Fehlerantwort zurück, um Ihnen zu helfen, das Problem zu identifizieren und zu lösen. Die Antwort umfasst einen Fehlercode und eine menschenlesbare Meldung, in der das Problem beschrieben wird.
{
"error": {
"code": "ERROR_CODE",
"message": "Human readable error message"
}
}
Häufige Fehlercodes:
- BAD_REQUEST — Ungültige Anforderungsparameter
- UNAUTORISIERT — Die Authentifizierung ist fehlgeschlagen
- NOT_FOUND — Ressource nicht gefunden
- KONFLIKT — Die Ressource ist bereits vorhanden
Leitfaden zur Einrichtung von AWS Target
Wenn Sie einen AWS-Service (SQS, SNS oder EventBridge) als Ihr Benachrichtigungsziel verwenden, müssen Sie eine IAM-Zustellungsrolle konfigurieren, um Prime Video die Erlaubnis zu erteilen, Benachrichtigungen an Ihre AWS-Ressourcen zu senden. Gehen Sie wie folgt vor, um die erforderlichen IAM-Rollen- und Berechtigungsrichtlinien einzurichten, bevor Sie Ihr Ziel registrieren.
Voraussetzungen
- AWS-Zielressource (SQS-Warteschlange, SNS-Thema oder EventBridge Bus)
- IAM-Bereitstellungsrolle mit Vertrauens- und Berechtigungsrichtlinien
Einrichtung der IAM-Rolle 1.
Rolle erstellen: AWS-Konsole → IAM → Rollen → Rolle erstellen → Benutzerdefinierte Vertrauensrichtlinie 2. Vertrauensrichtlinie {
"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. Berechtigungsrichtlinie (wählen Sie eine):
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}"
}]
}
