Prime Video offre ai partner due suite API complete progettate per semplificare la gestione dei contenuti e fornire preziose informazioni aziendali. Questa guida descrive il processo di onboarding completo per Content API Suite e Analytics API Suite, inclusi i requisiti di autenticazione, la configurazione tecnica e le principali differenze tra le due.
Fase 1: Richiedere l’accesso e generare credenziali
Contatta il tuo contatto Prime Video o invia una richiesta di accesso tramite Contattaci per richiedere l’accesso alla Content API Suite.
Fase 2: Generazione delle credenziali e invio
Una volta approvata la richiesta di accesso, genera una chiave privata e una richiesta di firma del certificato (CSR) per ogni ambiente e condividile con il contatto Prime Video designato.
Genera la tua CSR
Puoi utilizzare qualsiasi strumento di certificazione per generare i tuoi CSR. Se desideri utilizzare OpenSSL puoi eseguire i due comandi seguenti: openssl genrsa -out client.key 2048
openssl req -new -key client.key -out prod_client.csr
Invia la tua CSR al tuo contatto Prime Video
La CSR contiene tutte le informazioni di cui abbiamo bisogno per generare il tuo certificato API. Questo è il file che invierai al tuo contatto come parte della tua richiesta di onboarding. Una volta che Prime Video avrà ricevuto la tua CSR, non avrai più bisogno di questo file.
Nota: è molto importante proteggere i file con la chiave privata e non condividerli mai con nessuno, incluso Prime Video. Non chiederemo mai questo file. Lo utilizzerai in seguito per effettuare le tue chiamate API verso di noi.
Fase 3: Ricevere le credenziali
Una volta approvata la richiesta, riceverai un’email dal team di Prime Video con le seguenti informazioni:
- Il certificato pubblico che utilizzerai per effettuare chiamate verso di noi.
- La tua chiave API per le intestazioni delle richieste
- Gli endpoint URL per le chiamate API.
- Informazioni sul TPS per cui sei configurato con il tuo certificato.
Fase 4: Configurazione dell’integrazione
Ecco alcuni esempi di integrazioni che utilizzano diverse tecnologie:
Bash
bash
curl --location --request PUT 'https://partnerapi.primevideo.com/v1/avails/{partnerAlias}/full-extract/{ALID}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: <api key>' \
--data-raw '{ "avail": <Avail json> }' \
--key ./private_key.txt --cert ./certificate.pem
Python
Python https://requests.readthedocs.io/en/master/user/advanced/#client-side-certificates
requests.put(f'https://partnerapi.primevideo.com/v1/avails/{partnerAlias}/full-extract/{ALID}',
data={'{ "avail": <Avail json> }'},
cert=('/path/client.cert', '/path/client.key'),
headers={'x-api-key':'<api key>','Content-Type':'application/json'})
Node.js
Nodejs https://nodejs.org/api/https.html#https_https_request_options_callback
const options = {
hostname: `https://partnerapi.primevideo.com/v1/avails/{partnerAlias}/full-extract/{ALID}`,
port: 443,
path: `/v1/avails/{partnerAlias}/full-extract/{ALID}`,
method: 'PUT',
headers: {
'Content-Type':'application/json',
'x-api-key':'<api key>'
},
key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
agent: false
};
const req = https.request(options, (res) => {
// ...
});
Fase 5: Verifica la tua integrazione
Per quanto riguarda l’API Avails, offriamo supporto ai test per assicurarci che tu possa inviare, aggiornare e far scadere correttamente gli avail tramite API. Poiché queste operazioni hanno un impatto diretto sugli asset (non solo sul recupero dei dati), consigliamo vivamente a tutti i partner di testare a fondo la loro integrazione. Per le API Offer Status e Asset Status, poiché sono di sola lettura, puoi eseguire il test utilizzando l’account Production.
Passaggio 6: Inizia a utilizzare l’API
Congratulazioni! Il test è completo e convalidato. Ora puoi iniziare a utilizzare l’ambiente di produzione con le tue credenziali di produzione per gestire i tuoi contenuti su Prime Video. La tua integrazione è pronta per semplificare le operazioni relative ai contenuti e fornire visibilità in tempo reale sul tuo catalogo.
Fase 1: Crea il tuo profilo di sicurezza
Come parte di questo passaggio, configurerai le credenziali dell’applicazione e configurerai le impostazioni di autenticazione tramite la Developer Console di Amazon.
Registra la tua applicazione
- Accedi alla Amazon Developer Console per iniziare il processo di registrazione
- Accedi con il tuo account sviluppatore Amazon esistente o crea un nuovo account se non ne hai uno
- Fai clic su Crea un nuovo profilo di sicurezza per iniziare a configurare le impostazioni di autenticazione dell’applicazione
Configura il tuo profilo
- Nome del profilo di sicurezza: scegli un nome descrittivo che identifichi chiaramente la tua integrazione (ad esempio, «Performance Data Integration» o «Analytics API Access»)
- Descrizione: fornisci una spiegazione chiara dello scopo dell’applicazione e di come utilizzerà le API di Analytics
- URL dell’informativa sulla privacy: includi un URL che spieghi agli utenti come l’applicazione gestirà e proteggerà i loro dati
- Fai clic su Salva per creare il tuo profilo di sicurezza
- Dovresti ricevere un messaggio corretto una volta impostato correttamente
Imposta l’URL di reindirizzamento
- Vai al tuo profilo e seleziona le schede del profilo di sicurezza da Gestire sul tuo profilo di sicurezza appena creato:
- Quindi seleziona Impostazioni Web per configurare il comportamento di reindirizzamento dell’applicazione
- Aggiungi l’URL di reindirizzamento: questo è l’endpoint sicuro a cui verranno inviati gli utenti dopo aver autorizzato l’applicazione (è necessario utilizzare https://o https://localhost per lo sviluppo locale)
Importante: Salva questo URL in modo sicuro: dovrai utilizzare questo URL esatto nel passaggio successivo per generare il codice di autorizzazione.
Ricevi le tue credenziali
- Vai alla scheda Impostazioni Web per accedere alle credenziali dell’applicazione
- Copia il tuo Client ID (che funge da identificatore univoco dell’applicazione) e Client Secret (funge da password dell’applicazione)
- Archivia entrambe le credenziali in modo sicuro nel sistema di gestione dei segreti della tua organizzazione: verranno utilizzate per autenticare tutte le tue richieste API
Fase 2: Autorizza la tua candidatura
Come parte di questo passaggio, autorizzerai la tua applicazione ad accedere a Prime Video Slate per conto della tua organizzazione, stabilendo le autorizzazioni necessarie per recuperare i dati e le analisi delle prestazioni tramite le API.
Aggiungi la tua applicazione a Slate
- Accedi al tuo account Prime Video Slate utilizzando le credenziali della tua organizzazione
- Vai alle Impostazioni dell’account nell’angolo in alto a destra, quindi seleziona Applicazioni dal menu a discesa
- Fai clic su Aggiungi applicazione per iniziare il processo di autorizzazione
- Inserisci il tuo ID cliente (dal passaggio 1) nel campo fornito
- Seleziona la casella di controllo Reporting per concedere all’applicazione l’accesso ai dati e ai report sulle prestazioni
- Fai clic su Aggiungi applicazione per completare la registrazione in Slate
Genera il tuo codice di autorizzazione
- Costruisci il tuo URL di autorizzazione sostituendo i segnaposto tra parentesi con le tue credenziali effettive della Fase 1:
https://www.amazon.com/ap/oa?client_id=[YOUR_CLIENT_ID]&redirect_uri=[YOUR_REDIRECT_URI]&scope=videocentral::reports:read&response_type=code
- Apri questo URL nel tuo browser web per avviare il flusso di autorizzazione
- Accedi con le credenziali del tuo account Slate quando richiesto
- Controlla le autorizzazioni richieste dall’applicazione, quindi fai clic su Consenti per concedere l’accesso
- Dopo l’autorizzazione, verrai reindirizzato all’URL di reindirizzamento specificato: copia il codice di autorizzazione dalla stringa di query dell’URL (apparirà come
?code=YOUR_CODE
Best practice: consigliamo di creare un account Slate dedicato (ad esempio, api_access@yourcompany.com) con autorizzazioni minime richieste specificamente per l’accesso all’API. Questo approccio migliora la sicurezza e semplifica la gestione e il controllo dell’utilizzo delle API in tutta l’organizzazione.
Nota: se rimuovi le autorizzazioni dell’utente che autorizza l’utilizzo dei report, anche l’applicazione vedrà revocata l’autorizzazione all’utilizzo dei report.
Fase 3: Richiedere i token di accesso
Come parte di questo passaggio, utilizzerai il tuo codice di autorizzazione per ottenere i token necessari per effettuare chiamate API autenticate. Il token di accesso consente all’applicazione di recuperare i dati sulle prestazioni, mentre il token di aggiornamento consente di generare nuovi token di accesso senza ripetere il processo di autorizzazione.
I codici di autorizzazione sono token monouso. Quando vengono utilizzati per recuperare un access_token, restituiscono un refresh_token che può essere utilizzato per recuperare il successivo access_token. La sezione seguente illustra come recuperare il primo refresh_token.
Richiesta token iniziale (solo per la prima volta):
per richiedere un token:
- Inserisci client_id, client_secret, authorization_code e grant_type come dati del modulo con codifica URL.
- Effettua una richiesta HTTP.
Il comando curl per generare token da authorization_code è mostrato nell’esempio seguente.
curl --request POST \
--url https://api.amazon.com/auth/o2/token \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code' \
--data 'code=[AUTH_CODE]' \
--data 'client_id=[ID]' \
--data 'client_secret=[SECRET] \
--data 'redirect_uri=[URI]'
Aggiornamento del token di accesso:
per tutte le sessioni successive alla richiesta iniziale del token, utilizza il token di aggiornamento per ottenere nuovi token di accesso: bash
curl --location --request POST 'https://api.amazon.com/auth/o2/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=refresh_token' \
--data 'client_id=[YOUR_CLIENT_ID]' \
--data 'client_secret=[YOUR_CLIENT_SECRET]' \
--data 'refresh_token=[YOUR_REFRESH_TOKEN]'
Fase 4: Configurazione dell’applicazione
Congratulazioni! Ora disponi di tutte le credenziali necessarie per chiamare le API Performance. Come parte di questo passaggio, configurerai l’applicazione per includere il token di accesso nell’intestazione di autorizzazione di ogni richiesta API, consentendoti di recuperare i dati dell’abbonamento, le metriche delle prestazioni e le analisi dei tuoi contenuti.
Esempio di richiesta API:
curl --request GET \
--url https://videocentral.amazon.com/apis/v1/accounts \
--header 'authorization: bearer Atza|IwEBIPSxTCdGGC-xL-ywFib_lJfg-D7d435Jw739GWa3xy6dHJ
Questo esempio dimostra come autenticare le richieste: replace[YOUR_ACCESS_TOKEN]
Fase 5: Test di integrazione
Consigliamo vivamente a tutti i partner di testare a fondo la propria integrazione per garantire un accesso affidabile ai dati sulle prestazioni. Come parte di questo passaggio, verificherai che il flusso di autenticazione funzioni correttamente, che le chiamate API restituiscano i dati previsti e che la gestione degli errori sia configurata correttamente.
Passaggio 6: Inizia a utilizzare
Una volta completati i test e verificato che l’integrazione funzioni in modo affidabile, puoi iniziare a utilizzare l’ambiente di produzione per recuperare dati e analisi sulle prestazioni in tempo reale per i tuoi contenuti su Prime Video. Le tue pipeline di dati possono ora utilizzare i file del set di dati di sola aggiunta per eseguire le analisi granulari di cui la tua organizzazione ha bisogno.
Scopri di più sui framework di dati dell’API Analytics disponibili qui:
