L’API Avils si basa sul Partner API Framework, che offre un’interfaccia unificata per API accessibili dall’esterno. Questo framework consente a studi, case di post-produzione e altri partner di distribuzione di gestire in modo programmatico il proprio catalogo video su Prime Video.
Inizia
Per accedere all’API Avils, avrai bisogno di un certificato MTLS e di una chiave API. Questa sezione fornisce i passaggi per generare una richiesta di firma del certificato (CSR), richiedere un certificato MTLS ed effettuare richieste API all’API Informazioni sulla disponibilità.
Passaggio 1: il client crea la propria chiave privata e la richiesta di firma del certificato (CSR) utilizzando openssl.
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr
Fase 2: Il cliente invia un’e-mail a pv-partner-apis-support@amazon.com con allegato client.csr. (Il team risponderà con un certificato entro 1 giorno lavorativo.) Il seguente frammento di codice è un esempio consigliato. EMAIL TEMPLATE
Partner Details
PartnerName :
Partner Alias :
Partner Resource Access : [Avails-Read,Avails-Write]
Request Limit :
Attachment
Partner Certificate signing request (client.csr).
Fase 3: Il cliente riceve il certificato pubblico, il cacert e la chiave API dal team Partner API. Il seguente frammento di codice fornisce un esempio dei messaggi che potresti ricevere. Prod EMAIL TEMPLATE
Hi <Name/s>
Attached you’ll find your MTLS cert for PartnerApi Production environment. It will be usable only with the client.key you used to create client.csr that you sent us
Your ApiKey is: XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX. Include it in your requests as http header ‘x-api-key’
Requests with a body must have Content-Type=application/json header
The base url is https://partnerapi.primevideo.com
MTLS certs and ApiKeys provided for Sandbox environment will not work for Prod environment. You will need to request a separate MTLS cert and ApiKey to make requests against our Prod environment when you are ready
We have given you a rate limit of 10 TPS and 5 burst TPS (meaning you can have up to 5 open concurrent connections/requests at a time).
As a place to start, I would suggest doing a request to make sure you’re able to get an authenticated response. Try a GET request to https://partnerapi.primevideo.com/v1/avails/<licensor>/full-extract/some-test-alid?territory=US&businessLine=PRIME_SUBSCRIPTION. You should get a 404 status code with a response body indicating ‘Title not found for ALID some-test-alid and Licensor <licensor>’
Please let us know if you have any questions/problems!
PV PartnerApi Team
Attachment
Partner public Certificate (clientCert.pem)
CertificateAuthority public certificate (cacert.pem)
SANDBOX EMAIL TEMPLATE
Hi <Name/s>
Attached you’ll find your MTLS cert for PartnerApi Sandbox environment. It will be usable only with the client.key you used to create client.csr that you sent us.
We have created a new sandbox only vendorAlias of api_sandbox_<licensor> that you will use as vendorAlias/licensor for all your sandbox API requests.
Your ApiKey is: XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX. Include it in your requests as http header ‘x-api-key’.
Requests with a body must have Content-Type=application/json header.
Sandbox offers the exact same endpoints offered by our Prod api but with a different base url. The base url for Sandbox is https://sandbox.partnerapi.primevideo.com
The MTLS cert and ApiKey provided here will only work in the Sandbox environment. You will need to request a separate MTLS cert and ApiKey to make requests against our Prod environment when you are ready.
When creating Avails in the sandbox environment, you may use whatever ALID/SKU you want. These will not be connected nor linked to any prod titles and need not be coordinated with any real title ALID/SKU you have created in your account. Additionally, in the Sandbox you may safely use the same ALID/SKU as real titles in your prod account if you wish.
We have given you a rate limit of 4 TPS and 2 burst TPS (burst meaning you can have up to 2 open concurrent connections/requests at a time).
Note that this sandbox is not intended for long-term storage. Lifetime of a sandbox Avail is intended to be less-than 30 days.
As a place to start, I would suggest doing a request to make sure you’re able to get an authenticated response. Try a GET request to https://sandbox.partnerapi.primevideo.com/v1/avails/api_sandbox_<licensor>/full-extract/some-test-alid?territory=US&businessLine=PRIME_SUBSCRIPTION. You should get a 404 status code with a response body indicating ‘Title not found for ALID some-test-alid and Licensor api_sandbox_<licensor>’
Please let us know if you have any questions/problems!
PV PartnerApi Team
Attachment
Partner public Certificate (clientCert.pem)
CertificateAuthority public certificate (cacert.pem)
Passaggio 4: il client utilizza PublicKey, il certificato pubblico Partner e la chiave API per chiamare l’API.
Ecco alcuni esempi di integrazioni che utilizzano diverse tecnologie.
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 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'})
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) => {
// ...
});
Revoca l’accesso al certificato MTLS
Occasionalmente, potrebbe essere necessario revocare un certificato MTLS. Se hai bisogno che uno dei loro certificati venga revocato, invia le informazioni mostrate nell’esempio seguente via e-mail a pv-partner-apis-support@amazon.com. EMAIL TEMPLATE
Partner Details
PartnerName :
Partner Alias :
Owner Email Id :
Certificate Serial Number :
ApiKey :
Mappatura dello schema da MDDF a EMA Avail
Stiamo usando lo schema MDDF Avail in JSON. Un diagramma dello schema è disponibile su MovieLabs al seguente link: https://www.movielabs.com/md/avails/v2.6/avails-v2.6.1/avails-v2.6.1.html#Link2. La tabella seguente mostra la mappatura effettuata da EMA per le proprietà e gli attributi MDDF Avail supportati.
Prime Video MDF JSON |
Foglio di calcolo Prime Video EMA |
Versione avail.compatibility.SPEC |
1.7.3 |
Avail.alid |
VALIDO |
avail.disposition.entryType |
Tipo di ingresso |
avail.licensor.displayName |
Nome del display |
Avail.Asset. _ContentID |
VALIDO |
avail.asset.WorkType |
Tipo di lavoro |
Alias interni avail.asset.metadata.titleInternal |
Titolo: Alias interno |
Avail.asset.episodemetadata.titleInternalAliias |
Alias interno del titolo dell’episodio |
avail.asset.episodemetadata.episodenumber.Number |
Numero di episodio |
Alias interno avail.asset.episodemetadata.seasonMetadata.SeasonTitleAlias |
Alias interno del titolo stagionale |
avail.asset.episodeMetadata.SeasonMetadata.SeasonContentID |
ID stagionale |
avail.asset.episodeMetadata.SeasonMetadata.SeasonNumber.Number |
Numero della stagione |
avail.asset.episodemetadata.SeasonMetadata.Numero di episodi |
Conteggio episodi |
avail.asset.episodemetadata.seriesMetadata.SeriesContentID |
Serie ALDID |
Alias interno avail.asset.episodemetadata.seriesMetadata.serieTitleAlias |
Alias interno del titolo della serie |
avail.asset.episodemetadata.seriesmetadata.Number of Seasons |
Conteggio delle stagioni |
Aliias interno di Avail.asset.SeasonMetadata.SeasonTitleAliias |
Alias interno del titolo stagionale |
avail.asset.seasonMetadata.SeasonContentID |
ID stagionale |
avail.asset.seasonmetadata.SeasonNumber.Number |
Numero della stagione |
Metadati avail.asset.season. numero di episodi |
Conteggio episodi |
avail.asset.seasonMetadata.seriesMetadata.SeriesContentID |
Serie ALDID |
Alias interno Avail.asset.SeasonMetadata.SeriesMetadata.SerieTitleInternal |
Alias interno del titolo della serie |
avail.asset.seasonmetadata.seriesMetadata.NumberofSeasons |
Conteggio delle stagioni |
Avail.Transaction.License Type |
Tipo di licenza |
Disponibile.Transazione.Territorio.Paese |
Territorio |
Avail.Transaction.Start |
Inizia |
Avail.Transaction.End |
Fine |
Avail.Transaction.AllowedLanguage |
Lingue consentite |
Avail.Transaction.Holdback Language |
Lingua di trattenimento |
avail.transaction.assetLanguage.Value |
Asset Language |
avail.transaction.assetLanguage. _risorsa |
Tipo di localizzazione |
Avail.Transaction.LicenseRights Descrizione |
Descrizione dei diritti di licenza |
Profilo avail.transaction.format |
Formatta il profilo |
avail.transaction.contractId |
ID del contratto |
Avail.Transaction.Altre istruzioni |
Altre istruzioni |
Transazione disponibile. _TransactionID |
ID disponibile |
Avail.Transaction.Term. _TermName.Identità del canale |
Identità del gruppo |
Disponibilità della transazione. Termine. _TermName.AnnuncieDate |
Annunciare la data |
Avail.Transaction.Term. _TermName.SuppressionLiftDate |
SuppressionLiftDate |
Durata della transazione disponibile. _TermName.RentalDuration |
Durata del noleggio |
Transazione disponibile. Durata. _termname.watchDuration |
Durata dell’orologio |
Avail.Transaction.Term. _TermName.Scarica |
Scarica |
Avail.Transaction.Term. _TermName.Tier |
Tipo di prezzo |
Avail.Transaction.Termine. _TermName.Category |
Tipo di prezzo |
Avail.Transaction.Termine. _Termine nome.wsp |
Tipo di prezzo |
Avail.Transaction.Termine. _Termname.srp |
SRP |
avail.transaction.term.money.value |
Prezzo |
Disponibilità, transazione, termine, denaro. _valuta |
Prezzo e valuta |
Esclusività Avail.Transaction.Term.Exclusivity |
Esclusività |
Attributi avail.transaction.term.ExclusiveAttributes |
Attributi esclusivi |
avail.sharedEntitlement.EcosystemID |
ID_DMA |
Avail.SharedEntitlement.Ecosystem |
DMA_ID |
Metodi
Le sezioni seguenti descrivono i diversi metodi di richiesta API che è possibile utilizzare con l’API Informazioni sulla disponibilità, inclusi gli endpoint specifici, e l’aspetto che dovrebbe avere il corpo di ogni richiesta e risposta.
Categoria: Estratto
completo GET:- Punto di destinazione:
/avails/ {licensor} /full-extract/ {ALID}? territorio= {territorio} &BusinessLine= {BusinessLine} - Corpo della richiesta: -
- ResponseBody: utilizza le transazioni per un ambito
METTI:
- Punto finale:
/avails/ {licensor} /full-extract/ {ALID}
Corpo della richiesta: {... Utilizza i dati}- ResponseBody: risposta di successo/fallimento
ELIMINA:
- Punto finale:
/avails/ {licensor} /full-extract/ {ALID}? territorio= {territorio} &businessLine = {businessLine} &contractID= {CPH | FIXED_FEE} &channelIdentity= {channelIdentity} - Corpo della richiesta: -
- ResponseBody: risposta di successo/fallimento
POSTA:
- Punto di destinazione:
/avails/ {licensor} /full-extract/ {ALID} /validate
Corpo della richiesta: {... Utilizza i dati}- ResponseBody: risposta di successo/fallimento
Categoria: Batch
Sottocategoria: Estratto completo POST:
- Punto finale: /avails/full-extract/batch/get
- Corpo della richiesta:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}' }... ] } - Organo di risposta:
[ { 'requestItemId':'<requestId>', 'success':'<true | false>', 'avail':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
POSTA:
- Punto finale:
/avails/fullextract/batch/put - Organo della richiesta:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}' 'body': { avails: [<Avail data>] } }... ] } - Organo di risposta:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
POSTA:
- Punto finale:
/avails/full-extract/batch/delete - Corpo della richiesta:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}&contractId={CPH | FIXED_FEE}&channelIdentity={channelIdentity}' }... ] } - Organo di risposta:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
POSTA:
- Punto finale:
/avails/full-extract/batch/validate - Corpo della richiesta:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}/validate' 'body': { avails: [<Avail data>] } }... ] } - Organo di risposta:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
Linee di business
Per Full Extract, tutte le Informazioni sulla disponibilità per una linea di business + territorio devono essere consegnate insieme. Sono supportate le seguenti linee di business:
- PRIME_SUBSCRIPTION
- TVOD
- VOD
- CANALI
I valori BusinessLine possono essere determinati dalla combinazione di LicenseType e BenefitID, come illustrato nella tabella seguente.
Tipo di licenza |
ID del vantaggio |
BusinessLine |
EST |
- |
TVOD |
VOD |
- |
TVOD |
POEST |
- |
TVOD |
SVOD |
PRIMO |
ABBONAMENTO PRIME_ |
SVOD |
A4 K |
ABBONAMENTO PRIME_ |
SVOD |
QUALSIASI (non PRIME o A4K) |
CANALI |
VOD |
QUALSIASI |
VOD |
