API Notifiche

• Rilevamento dei problemi in tempo reale: ricevi notifiche istantanee quando le consegne delle risorse non vanno a buon fine o lo stato delle offerte 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 le informazioni aggiornate.
• 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 la disponibilità delle offerte in tutti i tuoi titoli e territori da un unico sistema di notifica.

Per iniziare a utilizzare le notifiche sono necessari tre passaggi:

1. Registra un target: configura dove vuoi ricevere le notifiche; puoi scegliere tra servizi AWS (SQS, SNS, EventBridge) o webhook HTTPS.
2. 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.
3. Ricevi notifiche: una volta configurate, riceverai automaticamente notifiche man mano che gli eventi si verificheranno in tempo reale.

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.

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

Crea un nuovo target delle notifiche in cui riceverai le notifiche relative agli eventi.

Corpo della richiesta:

Risposta:

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

Recupera tutti i target registrati per la tua organizzazione.

Ottieni target specifico

GET

Recupera i dettagli per un target specifico.

Aggiorna target

PUT

Aggiorna una configurazione di un target esistente.

Elimina target

DELETE

Rimuovi un target dalla tua configurazione.

Un’iscrizione associa uno o più eventi a un target registrato, consentendo di stabilire quali notifiche ricevere 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

Crea un’iscrizione per associare gli eventi in base ai tuoi target.

Corpo della richiesta:

Risposta:

Elenca tutti le iscrizioni

GET

Recupera tutte le iscrizioni per la tua organizzazione.

Aggiorna iscrizione

PUT

Aggiorna una configurazione di iscrizione esistente.

Elimina iscrizione

DELETE

Rimuovi un’iscrizione dalla tua configurazione.

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 desiderano monitorare. Ogni argomento è associato a un’area specifica di monitoraggio dello stato dei contenuti.

• LiveStatusUpdated: quando cambia lo stato in tempo reale
• OfferStatusUpdated: quando cambia lo stato dell’offerta (disponibile a breve)
• AssetStatusUpdated: quando cambia lo stato della risorsa (disponibile a breve)

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.

Target 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:

Esempio SNS:

Esempio EventBridge:

Target webhook - Token di connessione:

Target webhook - Chiave API:

Target webhook - HMAC (consigliato):

I webhook ricevono richieste HTTP POST con il seguente payload:

Intestazioni di autenticazione:

• HMAC: Firma X: {signature}
• Chiave API: Chiave X-API: {key}
• Bearer. Autorizzazione: Bearer {token}

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.

Codici di errore comuni:

• Bad_Request: parametri di richiesta non validi
• Unauthorized: autorizzazione non riuscita
• Not_Found: risorsa non trovata
• Conflict: risorsa già esistente

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à

3. Policy di autorizzazione (selezionare una delle seguenti opzioni)

SQS:

SNS:

EventBridge:

Le seguenti sezioni forniscono risposte alle domande più comuni sull’utilizzo dell’API Notifiche.