L’API Notifiche ti consente di ricevere notifiche in tempo reale per vari eventi di contenuto su Prime Video, in modo da non dover più svolgere ripetutamente il polling delle API di stato. Configura flussi di lavoro automatizzati che rispondono istantaneamente agli aggiornamenti sulla consegna delle risorse e alle modifiche allo stato live, consentendoti di risolvere i problemi più rapidamente e mantenere il tuo catalogo sempre aggiornato.
Rilevamento dei problemi in tempo reale: ricevi notifiche istantanee quando le consegne delle risorse non vanno a buon fine o lo stato in diretta cambia, in modo da risolvere immediatamente i problemi invece di scoprirli ore o giorni dopo tramite controlli manuali.
Sovraccarico delle API ridotto: non è più necessario effettuare un polling continuo delle API di stato; ciò consente non solo di ridurre i costi dell’infrastruttura e il volume delle chiamate API, ma anche di mantenere aggiornate le informazioni.
Integrazione automatizzata del flusso di lavoro: connetti le notifiche direttamente ai tuoi sistemi esistenti (servizi AWS o webhook) per attivare risposte automatiche, la creazione di ticket o flussi di lavoro per gli avvisi senza intervento manuale.
Copertura completa degli eventi: monitora lo stato di consegna delle risorse e lo stato live di tutti i tuoi titoli e territori da un unico sistema di notifica.
Introduzione
Per iniziare a utilizzare le notifiche sono necessari tre passaggi:
- Registra un target: configura dove vuoi ricevere le notifiche; puoi scegliere tra servizi AWS (SQS, SNS, EventBridge) o webhook HTTPS.
- Crea iscrizioni: associa gli eventi che desideri monitorare ai tuoi target registrati. Ogni iscrizione copre un argomento (AssetStatus o OfferStatus), ma puoi iscrivere più tipi di eventi all’interno dello stesso argomento.
- Ricevi notifiche: una volta configurate, riceverai automaticamente notifiche man mano che gli eventi si verificheranno in tempo reale.
Argomenti ed eventi disponibili
Gli argomenti raggruppano eventi correlati. Quando si crea un’iscrizione, si seleziona un argomento e si specifica quali eventi all’interno di tale argomento si desidera monitorare.
Stato in tempo reale aggiornato
ArgomentoOfferStatus
Ti avvisa quando lo stato in diretta di un titolo cambia sulla vetrina Prime Video, ad esempio quando un titolo viene pubblicato o meno.
Cosa attiva questa notifica? Lo stato in diretta/non in diretta di un titolo cambia nella vetrina. Utilizza il callbackURL nel payload per recuperare i dettagli completi sullo stato dell’offerta tramite l’API Offer Status.
Payload:{
"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
Argomento:AssetStatus
Ti avvisa quando una risorsa raggiunge il risultato finale di consegna. Viene inviata una notifica quando lo stato di una risorsa diventa:
- Completato: la risorsa è stata consegnata con successo, oppure
- Operazione non riuscita:: la risorsa non può essere consegnata o richiede attenzione.
Cosa attiva questa notifica? Una modifica dello stato di consegna di una risorsa (ad esempio, video, audio, sottotitoli, grafica). Utilizza il callbackURL per recuperare lo stato completo di consegna delle risorse, incluse informazioni dettagliate sugli errori, ove applicabile.
Casi d’uso:
- Rilevamento degli errori di consegna in tempo reale e attiva flussi di lavoro di riconsegna automatizzati
- Conferma della corretta elaborazione delle risorse senza eseguire il polling dell’API Asset Status
- Integrazione con i sistemi di biglietteria interni per una risoluzione immediata dei problemi
Payload:{
"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"
}
Schemi di richiesta e risposta
Questa sezione fornisce le specifiche tecniche che consentono agli sviluppatori di integrare l’API Notifiche dei partner nei tuoi sistemi. Usa questo riferimento per comprendere il formato della richiesta, la struttura della risposta e i tipi di dati restituiti dall’API.
URL di base
Tutte le richieste API vengono effettuate al seguente URL di base. Aggiungi il percorso dell’endpoint pertinente a questo URL quando effettui delle richieste.
https://partnerapi.primevideo.com/v1
Gestione dei target
Per target si intende la destinazione in cui desideri ricevere le notifiche: può trattarsi di un servizio AWS (SQS, SNS o EventBridge) o di un endpoint webhook HTTPS. È necessario registrare almeno un target prima di creare le iscrizioni.
Registra target
POST /{licensor}/notifications/targets
Crea un nuovo target delle notifiche in cui riceverai le notifiche relative agli eventi.
Corpo della richiesta:
{
"type": "SQS|SNS|EVENTBRIDGE|WEBHOOK",
"destination": "target-destination",
"auth": { /* varies by type */ }
}
Risposta:
{
"targetId": "target-id-1",
"status": "ACTIVE"
}
Elenca tutti i target
Usa questo endpoint per recuperare un elenco completo dei target delle notifiche registrati per la tua organizzazione. Questa operazione è utile per verificare la configurazione corrente o identificare gli ID di destinazione da utilizzare durante la creazione o l’aggiornamento delle iscrizioni.
GET /{licensor}/notifications/targets
Recupera tutti i target registrati per la tua organizzazione.
Ottieni target specifico
GET /{licensor}/notifications/targets?targetId={id}
Recupera i dettagli per un target specifico.
Aggiorna target
PUT /{licensor}/notifications/targets/{targetId}
Aggiorna una configurazione di un target esistente.
Elimina target
DELETE /{licensor}/notifications/targets/{targetId}
Rimuovi un target dalla tua configurazione.
Gestione delle iscrizioni
Un’iscrizione associa uno o più eventi a un target registrato, consentendo di stabilire quali notifiche riceverai e dove vengono consegnate. Ogni iscrizione è riservata a un singolo argomento, ma è possibile creare più iscrizioni per coprire tutti gli eventi rilevanti per il tuo flusso di lavoro.
Crea iscrizione
POST /{licensor}/notifications/subscriptions
Crea un’iscrizione per associare gli eventi in base ai tuoi target.
Corpo della richiesta:
{
"topic": "OfferStatus",
"eventTargetMapping": {
"LiveStatusUpdated": ["target-id-1"]
}
}
{
"topic": "AssetStatus",
"eventTargetMapping": {
"AssetStatusUpdated": ["target-id-1"]
}
}
Risposta:
{
"subscriptionId": "subscription-id-1",
"status": "ACTIVE"
}
Elenca tutti le iscrizioni
GET /{licensor}/notifications/subscriptions
Recupera tutte le iscrizioni per la tua organizzazione.
Aggiorna iscrizione
PUT /{licensor}/notifications/subscriptions/{id}
Aggiorna una configurazione di iscrizione esistente.
Elimina iscrizione
DELETE /{licensor}/notifications/subscriptions/{id}
Rimuovi un’iscrizione dalla tua configurazione.
Tipi di target
I tipi di target definiscono il modo in cui Prime Video invia le notifiche ai tuoi sistemi. Puoi scegliere tra i servizi gestiti da AWS per una consegna affidabile e scalabile o configurare un webhook HTTPS per ricevere notifiche direttamente sul tuo endpoint.
Obiettivi AWS (SQS, SNS, EventBridge)
Campi obbligatori:
- destination: ARN della risorsa AWS
- assumeRoleArn: ruolo IAM per la consegna
- externalID: identificatore di sicurezza (opzionale ma consigliato)
Esempio 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}"
}
}
Esempio 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}"
}
}
Esempio 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}"
}
}
Token al portatore: {
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "bearer",
"bearerToken": "your-token"
}
}
Chiave API:{
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "apiKey",
"apiKey": "your-key",
"apiKeyHeader": "X-API-Key"
}
}
HMAC (consigliato): {
"type": "WEBHOOK",
"destination": "https://your-api.example.com/webhooks",
"auth": {
"type": "hmac",
"hmacSecret": "your-secret",
"hmacAlgorithm": "HmacSHA256",
"hmacHeader": "X-Signature"
}
}
Payload
Struttura del Payload
Tutti i payload delle notifiche seguono una struttura coerente:
Campo |
Descrizione |
|---|---|
alid |
ID dell’inserzione del partner (identificatore del titolo) |
territory |
Codice territoriale (ad esempio, Stati Uniti, GB) |
marketplace |
Codice Marketplace |
partnerAlias |
Identificativo del partner |
eventType |
L’evento specifico che si è verificato |
callbackUrl |
URL per recuperare i dettagli completi sullo stato |
eventTimestamp |
Timestamp ISO 8601 dell’evento |
I webhook ricevono richieste HTTP POST con il seguente payload:{
"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"
}
Intestazioni di autenticazione:
- HMAC: Firma X: {signature}Firma X: {signature}
- Chiave API: Chiave X-API: {key}Chiave X-API:{key}
- Bearer. {token}Autorizzazione al portatore: Bearer {token}
Risposte agli errori
Quando non è possibile completare una richiesta, l’API rinvia una risposta di errore strutturata per aiutarti a identificare il problema e a risolverlo. La risposta include un codice di errore e un messaggio leggibile dall’uomo contenente la descrizione del problema.
{
"error": {
"code": "ERROR_CODE",
"message": "Human readable error message"
}
}
Codici di errore comuni:
- BAD_REQUEST: parametri di richiesta non validi
- UNAUTHORIZED: autorizzazione non riuscita
- NOT_FOUND: risorsa non trovata
- CONFLICT: risorsa già esistente
Guida alla configurazione di target AWS
Se utilizzi un servizio AWS (SQS, SNS o EventBridge) come destinazione delle notifiche, è necessario configurare un ruolo di consegna IAM per concedere a Prime Video l’autorizzazione a inviare notifiche alle tue risorse AWS. Segui i seguenti passaggi per impostare il ruolo IAM e le policy di autorizzazione richieste prima di registrare il tuo target.
Prerequisiti
- Risorsa di destinazione AWS (coda SQS, argomento SNS o bus EventBridge)
- Ruolo di consegna IAM con policy di attendibilità e autorizzazione
Configurazione del ruolo IAM
1. Creare il ruolo: Console AWS → IAM → Ruoli → Crea ruolo → Policy di attendibilità personalizzata
2. Policy di attendibilità{
"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. Politica di autorizzazione (scegline una):
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}"
}]
}
