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 completo di onboarding sia per la suite API contenuti che per la suite API analisi, inclusi i requisiti di autenticazione, la configurazione tecnica e le principali differenze tra le due.
Passaggio 1: richiedi l’accesso e genera le credenziali
Contatta il tuo referente Prime Video o invia una richiesta di accesso tramite Contattaci per richiedere l’accesso alla Suite API Contenuti.
Passaggio 2: genera le credenziali e invia
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 tuo referente Prime Video designato.
Genera il tuo CSR
Puoi usare qualsiasi strumento di certificazione per generare i tuoi CSR. Se vuoi usare 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 referente 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 referente 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 che tu tenga al sicuro i file delle chiavi private e non li condivida mai con nessuno, incluso Prime Video. Non chiederemo mai questo file. Lo userai in seguito quando effettuerai le tue chiamate API verso di noi.
Passaggio 3: ricevi le tue credenziali
Una volta approvata la tua richiesta, riceverai un’e-mail dal team di Prime Video con le seguenti informazioni:
- Il certificato pubblico che userai 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.
Passaggio 4: configura la tua integrazione
Congratulazioni! Ora puoi usare la chiave privata, il certificato pubblico e la chiave API per chiamare l’API. Ecco alcuni esempi di integrazioni che usano diverse tecnologie:
Bashbash
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
PythonPython 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) => {
// ...
});
Passaggio 5: prova la tua integrazione
Per l’API Informazioni sulla disponibilità, offriamo supporto per i test per garantire che tu possa inviare, aggiornare e far scadere correttamente le informazioni sulla disponibilità tramite API. Poiché queste operazioni hanno un impatto diretto sulle risorse (non solo sul recupero dei dati), consigliamo vivamente a tutti i partner di testare accuratamente la propria integrazione. Per le API Stato offerte e Stato risorse, poiché sono di sola lettura, puoi eseguire il test usando l’account di produzione.
Passaggio 6: inizia a usare l’API
Congratulazioni! Il test è completo e convalidato. Ora puoi iniziare a usare 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 nel tuo catalogo.
Passaggio 1: crea il tuo profilo di sicurezza
Come parte di questo passaggio, imposterai le credenziali dell’applicazione e configurerai le impostazioni di autenticazione tramite la Console per gli sviluppatori di Amazon.
Registra la tua applicazione
- Vai alla Console per gli sviluppatori di Amazon 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
- Profilo di sicurezza: Scegli un nome descrittivo che identifichi chiaramente la tua integrazione (per esempio, “Integrazione dati prestazioni” o “Accesso API Analisi”)
- Descrizione: Fornisci una spiegazione chiara dello scopo dell’applicazione e di come userà le API Analisi
- URL Informativa sulla privacy: Includi un URL che spieghi agli utenti come la tua applicazione gestirà e proteggerà i loro dati
- Fai clic su Salva per creare il tuo profilo di sicurezza
- Dovresti ricevere un messaggio di successo una volta impostato correttamente
Imposta il tuo URL di reindirizzamento
- Vai al tuo profilo e seleziona le schede Profilo di sicurezza da Gestione sul tuo profilo di sicurezza appena creato:
- Quindi seleziona Impostazioni web per configurare il comportamento di reindirizzamento dell’applicazione
- Aggiungi il tuo URL di reindirizzamento: questo è l’endpoint sicuro a cui verranno inviati gli utenti dopo aver autorizzato l’applicazione (è necessario usare https://o https://localhost per lo sviluppo locale)
Importante: salva questo URL in modo sicuro: dovrai usare questo URL esatto nel passaggio successivo durante la generazione del codice di autorizzazione.
Ricevi le tue credenziali
- Vai alla scheda Impostazioni web per accedere alle credenziali dell’applicazione
- Copia il tuo ID cliente (che funge da identificatore univoco dell’applicazione) e Client Secret (funge da password dell’applicazione)
- Conserva entrambe le credenziali in modo sicuro nel sistema di gestione dei segreti della tua organizzazione: verranno usate per autenticare tutte le tue richieste API
Passaggio 2: autorizza la tua applicazione
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 delle prestazioni e le analisi tramite le API.
Aggiungi la tua applicazione a Slate
- Accedi al tuo account Prime Video Slate usando le credenziali della tua organizzazione
- Vai su Impostazioni dell’account nell’angolo in alto a destra, quindi seleziona Applicazioni dal menu a tendina
- 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 Reportistica per concedere all’applicazione l’accesso ai dati delle prestazioni e ai report
- 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 dal Passaggio 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 dalla tua applicazione, quindi fai clic su Consenti per concedere l’accesso
- Dopo l’autorizzazione, avverrà il reindirizzamento al tuo specifico URL di reindirizzamento: copia il codice di autorizzazione dalla stringa di query dell’URL (verrà visualizzato come
?code=YOUR_CODE
Buona pratica: ti consigliamo di creare un account Slate dedicato (per esempio, api_access@yourcompany.com) con le autorizzazioni minime richieste specificamente per l’accesso alle 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 per l’utilizzo dei report dell’utente che autorizza, le autorizzazioni all’uso dei report saranno revocate anche all’applicazione.
Passaggio 3: richiedi i tuoi token di accesso
Come parte di questo passaggio, userai 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 usati per recuperare un access_token, restituiscono un refresh_token che può essere usato per recuperare il successivo access_token. La sezione seguente avvia il processo di recupero del tuo primo refresh_token.
Richiesta del token iniziale (solo la prima volta):
Per richiedere un token:
- inserisci client_id, client_secret, authorization_code e grant_type come dati form codificati URL.
- Effettua una richiesta HTTP.
Il comando curl per generare i 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=refresh_token' \
--data 'client_id=amzn1.application-oa2-client.20534a91be57487e9c3547dada8a7394' \
--data 'client_secret=c007c411c9657dde807a11a96a3cfd8a2972f9599ac28de241675832f63cac05' \
--data 'refresh_token=Atzr|IwEBIPw8sQi6vSq67a0QeWDjRp4DJusAHG9kg-707e9PVbCbFTD3mU3H9ztkXppkSfeIgGsq
d4zDnwr5y5hbFZvqyEQPsPRPNspT4cyWNhS6teaQsgyQa6CDTEejwYksDC4rQCi77p67zAkVzh6vHAuVJwkmaXH8IFFouRvR5gp
qrffASpNv1eZwLTyqJzMNyU2CNJrIgurqJmByJN3u-smxLkshqMej0anoykw8qyNTmNxrzYRZJR2KdZLH6Kcw9mO41zHJKVWKi_
My4_bevVGd8viCGUeXeaRgOONI-GtGoQOZV7NwERLFkjT8Imw_yu4AeZ9lXEomFTy61RhieWvpxJmHNDb6MRuJcywFhx-h2fw1I
jxP-W3J6HuVME69UMdapNkgk3bfgpWCsfkxDP3Qq1MddDkYvoTuJPAtqq12X4hvmlM1OZWsy8uG0Pckb9S3D1rh4g06pWcx-VaW
GXQr2hbP58DWWQYIbLW-kZHD0eakoqNdrOtj56IMZZTz7RAPdmHiiHScDkgu6PyiBFBDBV7V'
Aggiornamento del token di accesso:
Per tutte le sessioni successive alla richiesta iniziale del token, usa il token di aggiornamento per ottenere i 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]'
Passaggio 4: configura la tua applicazione
Congratulazioni! Ora hai tutte le credenziali necessarie per chiamare le API Prestazioni. Come parte di questo passaggio, configurerai la tua applicazione per includere il tuo 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 per i 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 tue richieste: sostituisci [YOUR_ACCESS_TOKEN]
Passaggio 5: prova l’integrazione
Consigliamo vivamente a tutti i partner di testare accuratamente l’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 l’uso
Una volta completati i test e verificato che l’integrazione funziona in modo affidabile, puoi iniziare a usare l’ambiente di produzione per recuperare dati sulle prestazioni e analisi in tempo reale per i tuoi contenuti su Prime Video. Le tue pipeline di dati possono ora usare i file del set di dati di sola aggiunta per eseguire l’analisi granulare di cui la tua organizzazione ha bisogno.
Scopri di più sui framework di dati delle API di Analytics disponibili qui:
