API di notifica

Rilevamento dei problemi in tempo reale: ricevi notifiche istantanee quando le consegne degli asset falliscono o lo stato in tempo reale cambia, consentendoti di risolvere immediatamente i problemi invece di scoprirli ore o giorni dopo tramite controlli manuali.

Riduzione del sovraccarico delle API: elimina la necessità di eseguire il polling continuo delle API di stato, riducendo i costi dell’infrastruttura e il volume delle chiamate API mantenendo al contempo informazioni aggiornate.

Integrazione automatizzata del flusso di lavoro: collega le notifiche direttamente ai sistemi esistenti (servizi AWS o webhook) per attivare risposte automatiche, creazione di ticket o flussi di lavoro di avviso senza intervento manuale.

Copertura completa degli eventi: monitora lo stato di consegna degli asset e lo stato in tempo reale in tutti i tuoi titoli e territori da un unico sistema di notifica.

Guida
introduttiva Per iniziare a utilizzare le notifiche sono necessari tre passaggi:

1. Registra un bersaglio: imposta dove desideri ricevere le notifiche. Puoi scegliere tra i servizi AWS (SQS, SNS, EventBridge) o i webhook HTTPS.
2. Crea abbonamenti: mappa gli eventi che desideri monitorare ai tuoi obiettivi registrati. Ogni abbonamento copre un argomento (AssetStatus o OfferStatus), ma puoi iscriverti a più tipi di eventi all’interno di quell’argomento.
3. Ricevi notifiche: una volta configurata, riceverai automaticamente le notifiche man mano che gli eventi si verificano in tempo reale.

Gli argomenti raggruppano gli eventi correlati. Quando si crea un abbonamento, si seleziona un argomento e si specificano gli eventi all’interno di quell’argomento che si desidera monitorare.

Argomento aggiornato su LiveStatus:

Ti avvisa quando lo stato live di un titolo cambia nella vetrina Prime Video, ad esempio quando un titolo viene pubblicato o non è più disponibile.
Cosa attiva questa notifica? Lo stato «live/non-live» 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.

Carico utile:

Argomento aggiornato sullo stato degli asset:

Ti avvisa quando una risorsa raggiunge il risultato di consegna finale. Viene inviata una notifica quando lo stato di una risorsa diventa:

• Soddisfatto: la risorsa è stata consegnata correttamente, oppure
• Non riuscito: la risorsa non può essere consegnata o richiede attenzione.

Cosa fa scattare questa notifica? Una modifica dello stato di consegna di una risorsa (ad esempio video, audio, sottotitoli, grafica). Utilizzate il callbackURL per recuperare lo stato completo di consegna delle risorse, comprese le informazioni dettagliate sugli errori, ove applicabile.

Casi d’uso:

• Rileva gli errori di consegna in tempo reale e attiva flussi di lavoro di riconsegna automatizzati
• Conferma la corretta elaborazione degli asset senza eseguire il polling dell’API Asset Status
• Integrazione con i sistemi di ticketing interni per una risoluzione immediata dei problemi

Carico utile:

Questa sezione fornisce le specifiche tecniche per gli sviluppatori per integrare l’API Partner Notification nei tuoi sistemi. Utilizza questo riferimento per comprendere il formato della richiesta, la struttura della risposta e i tipi di dati restituiti dall’API.

URL di base
Tutti le richieste API vengono effettuate al seguente URL di base. Aggiungi il percorso dell’endpoint pertinente a questo URL quando effettui le richieste.

Gestione degli obiettivi
Un target è la destinazione in cui desideri ricevere le notifiche, può essere un servizio AWS (SQS, SNS o EventBridge) o un endpoint webhook HTTPS. È necessario registrare almeno un target prima di creare sottoscrizioni.

Registra Target

Crea un nuovo obiettivo di notifica in cui ricevere le notifiche degli eventi.

Corpo della richiesta:

Risposta:

Elenca tutti gli obiettivi
Utilizza questo endpoint per recuperare un elenco completo degli obiettivi di notifica registrati per la tua organizzazione. Ciò è utile per controllare la configurazione corrente o identificare gli ID di destinazione da utilizzare per la creazione o l’aggiornamento delle sottoscrizioni.

Recupera tutti gli obiettivi registrati per la tua organizzazione.

Ottieni un obiettivo specifico

Recupera i dettagli di un obiettivo specifico.

Aggiorna Target

Aggiorna una configurazione di destinazione esistente.

Elimina Target

Rimuovi un obiettivo dalla tua configurazione.

Gestione delle sottoscrizioni
Un abbonamento associa uno o più eventi a un obiettivo registrato, determinando quali notifiche ricevere e dove vengono recapitate. Ogni abbonamento riguarda un singolo argomento, ma puoi creare più abbonamenti per coprire tutti gli eventi pertinenti al tuo flusso di lavoro.

Crea abbonamento

Crea un abbonamento per mappare gli eventi ai tuoi obiettivi.

Corpo della richiesta:

Risposta:

Elenca tutti gli abbonamenti

Recupera tutti gli abbonamenti per la tua organizzazione.

Aggiorna abbonamento

Aggiorna una configurazione di abbonamento esistente.

Elimina abbonamento

Rimuovi un abbonamento dalla tua configurazione.

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 distribuzione affidabile e scalabile o configurare un webhook HTTPS per ricevere notifiche direttamente sul tuo endpoint.

Obiettivi AWS (SQS, SNS, EventBridge)

Campi obbligatori:

• destinazione: ARN della risorsa AWS
• AssumeroLearn: ruolo IAM per la distribuzione
• ExternalID: identificatore di sicurezza (opzionale ma consigliato)

Esempio SQS:

Esempio SNS:

Esempio di EventBridge:

Token al portatore:

Chiave API:

HMAC (consigliato):

Struttura del payload
Tutti i payload di notifica seguono una struttura coerente:

I webhook ricevono richieste HTTP POST con il seguente payload:

Intestazioni di autenticazione:

• HMAC: X-Signature: {signature} X-Signature: {signature}
• Chiave API: Chiave X-API: {key} Chiave X-API: {key}
• Portatore: Bearer {token} Autorizzazione: Bearer {token}

Quando una richiesta non può essere completata, l’API restituisce una risposta di errore strutturata per aiutarti a identificare e risolvere il problema. La risposta include un codice di errore e un messaggio leggibile dall’uomo che descrive il problema.

Codici di errore comuni:

• BAD_REQUEST — Parametri di richiesta non validi
• UNAUTHORIZED: autenticazione non riuscita
• NOT_FOUND — Risorsa non trovata
• CONFLICT — La risorsa esiste già

Se utilizzi un servizio AWS (SQS, SNS o EventBridge) come obiettivo di notifica, devi configurare un IAM Delivery Role per concedere a Prime Video l’autorizzazione a inviare notifiche alle tue risorse AWS. Segui i passaggi seguenti per configurare il ruolo IAM e le politiche di autorizzazione richieste prima di registrare il tuo obiettivo.

Prerequisiti

• Risorsa di destinazione AWS (SQS Queue, SNS Topic o EventBridge Bus)
• IAM Delivery Role con politiche di fiducia e autorizzazione

2. Politica di fiducia

3. Politica di autorizzazione (scegline una):

SQS:

SNS:

EventBridge: