La API Avils se basa en el Partner API Framework, que ofrece una interfaz unificada para las API accesibles externamente. Este marco permite a los estudios, las empresas de posproducción y otros socios logísticos gestionar mediante programación su catálogo de vídeos en Prime Video.
Empezar
Para acceder a la API de Avails, necesitará un certificado MTLS y una clave de API. En esta sección se proporcionan los pasos para generar una solicitud de firma de certificado (CSR), solicitar un certificado MTLS y realizar solicitudes de API a la API de Avails.
Paso 1: El cliente crea su clave privada y la solicitud de firma de certificado (CSR) mediante openssl.
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr
Paso 2: El cliente envía un correo electrónico a pv-partner-apis-support@amazon.com con el archivo client.csr adjunto. (El equipo responderá con un certificado en un plazo de 1 día laborable). El siguiente fragmento de código es un ejemplo sugerido. EMAIL TEMPLATE
Partner Details
PartnerName :
Partner Alias :
Partner Resource Access : [Avails-Read,Avails-Write]
Request Limit :
Attachment
Partner Certificate signing request (client.csr).
Paso 3: El cliente recibe el certificado público, el cacert y la clave de API del equipo de API del partner. El siguiente fragmento de código proporciona un ejemplo de los mensajes que puede recibir. 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)
Paso 4: El cliente usa PublicKey, el certificado público del socio y la clave de API para llamar a la API.
Estos son algunos ejemplos de integraciones que utilizan diferentes tecnologías.
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) => {
// ...
});
Revocar el acceso al certificado MTLS
Ocasionalmente, es posible que sea necesario revocar un certificado MTLS. Si necesita que se revoque uno de sus certificados, envíe la información que se muestra en el siguiente ejemplo por correo electrónico a pv-partner-apis-support@amazon.com. EMAIL TEMPLATE
Partner Details
PartnerName :
Partner Alias :
Owner Email Id :
Certificate Serial Number :
ApiKey :
Mapeo de esquemas de MDDF a EMA Avail
Estamos usando el esquema MDDF Avail en JSON. Hay un diagrama del esquema disponible en MovieLabs en el siguiente enlace: https://www.movielabs.com/md/avails/v2.6/avails-v2.6.1/avails-v2.6.1.html#Link2. La siguiente tabla muestra el mapeo realizado por EMA para las propiedades y atributos de MDDF Avail compatibles.
Prime Video MDDF JSON |
Hoja de cálculo EMA de Prime Video |
Disponible. Compatibilidad. Versión específica |
1.7.3 |
Disponible. ID |
VÁLIDO |
Disponibilidad. Disposición. Tipo de entrada |
Tipo de entrada |
Avail.licensor.displayName |
Nombre de visualización |
Avail.Asset. _ContentID |
UNA ID VÁLIDA |
Avail.asset.workType |
Tipo de trabajo |
Alias internas de Avail.asset.metadata.title |
Alias interno del título |
Avail.asset.episodeMetadata.TitleInternalAlias |
Título del episodio Alias internas |
Avail.Asset.EpisodeMetadata.EpisodeNumber.Número |
Número de episodio |
Disponible. Activo. Metadatos del episodio. Metadatos de la temporada. Alias interno del título de la temporada |
Alias interno del título de la temporada |
Avail.Asset.Metadatatatos del episodio. Metadatos de la temporada.Season Content ID |
ID de temporada |
Disponible. Activo. Metadatos de episodio. Metadatos de temporada. Número de temporada |
Número de temporada |
Disponible. Activo. Metadatos del episodio. Metadatos de la temporada. Número de episodios |
Recuento de episodios |
Disponible. Asset.Metadatatos del episodio. Metadatos de la serie. ID del contenido de la serie |
Serie ALDID |
Avail.Asset.EpisodeMetadata.Metadatatata.SerieTitle Internal Alias |
Alias interno del título de la serie |
Disponible. Asset.Metadatos del episodio. Metadatos de la serie. Número de temporadas |
Recuento de temporadas |
Metadatos disponibles. Asset.Season. Alias internas del título de la temporada |
Alias interno del título de la temporada |
Avail.Asset.SeasonMetadata.SeasonContent ID |
ID de temporada |
Metadatos de temporada disponibles. Número de temporada. Número |
Número de temporada |
Metadatos disponibles. Activos y temporadas. Número de episodios |
Recuento de episodios |
Avail.asset.seasonmetadata.seriesMetadata.seriesContentID |
Serie ALDID |
Avail.asset.seasonmetadata.seriesMetadata.serieTitle Internal Alias |
Alias interno del título de la serie |
Metadatos disponibles. Asset.Season. Metadatos de series. Número de temporadas |
Recuento de temporadas |
Disponible. Transacción. Tipo de licencia |
Tipo de licencia |
Disponible. Transacción, Territorio, País |
Territorio |
Disponibilidad. Transacción. Inicio |
Empezar |
Avail.Transaction.End |
Fin |
Disponible. Transacción. Idioma permitido |
Idiomas permitidos |
Idioma Avail.Transaction.Holdback |
Lenguaje de retención |
Avail.Transaction.AssetLanguage.Value |
Lenguaje de activos |
Avail.Transaction.AssetLanguage. _activo |
Tipo de localización |
Descripción de Avail.Transaction.License |
Descripción de los derechos de licencia |
Avail.Transaction.FormatProfile |
FormatProfile |
Avail.transaction.ContractID |
ID de contrato |
Disponible. Transacción. Otras instrucciones |
Otras instrucciones |
Transacción disponible. _ID de transacción |
ID válido |
Disponible.Transacción.Plazo. _Nombre del termino.Identidad del canal |
Identidad de grupo |
Disponible. Transacción. Término. _Nombre del término. Fecha de anuncio |
Fecha de anuncio |
Disponibilidad. Transacción. Plazo. _TermName.SuppressionLiftDate |
SuppressionLiftDate |
Disponibilidad. Transacción. Plazo. _Nombre del plazo. Duración del alquiler |
Duración del alquiler |
Disponibilidad. Transacción. Plazo. _TermName.WatchDuration |
Duración del reloj |
Disponibilidad. Transacción. Plazo. _TermName.Descargar |
Descargar |
Avail.Transaction.Term. _TermName.Tier |
Tipo de precio |
Disponibilidad. Transacción. Plazo. _Nombre del termino.Categoría |
Tipo de precio |
Disponibilidad. Transacción. Plazo. _TermName.WSP |
Tipo de precio |
Disponibilidad. Transacción. Plazo. _TermName.srp |
SRP |
Avail.Transaction.Term.Money.Value |
Precio |
Disponibilidad. Transacción. Plazo. Dinero. _moneda |
Moneda del precio |
Disponibilidad. Transacción. Plazo. Exclusividad |
Exclusividad |
Atributos exclusivos de Avail.Transaction.Term |
Atributos exclusivos |
Avail.shareTitlement.EcosystemID |
DMA_ID |
Avail.SharedTitlement.Ecosystem |
DMA_ID |
Métodos
En las siguientes secciones se describen los diferentes métodos de solicitud de API que puedes usar con la API de Avils, incluidos sus puntos de enlace específicos y el aspecto que debe tener el cuerpo de cada solicitud y respuesta.
Categoría: Full Extract
GET:- Punto final:
/avails/ {licensor} /full-extract/ {ALID}? territorio= {territory} &BusinessLine= {BusinessLine} - Cuerpo de la solicitud: -
- ResponseBody: Disponible con transacciones para un ámbito
PONER:
- Punto final:
/avails/ {licensor} /full-extract/ {ALID} - Cuerpo
de la solicitud: {... Aprovechar los datos} - ResponseBody: Respuesta de éxito/fracaso
ELIMINAR:
- Punto final:
/avails/ {licensor} /full-extract/ {ALID}? territorio= {territory} &BusinessLine= {BusinessLine} &ContractID= {CPH | FIXED_FEE} &ChannelIdentity= {channelIdentity} - Cuerpo de la solicitud: -
- ResponseBody: Respuesta de éxito/fracaso
PUBLICACIÓN:
- Punto final:
/avails/ {licensor} /full-extract/ {ALID} /validate - Cuerpo
de la solicitud: {... Aprovechar los datos} - ResponseBody: Respuesta de éxito/fracaso
Categoría:
Subcategoría por lotes: Extracto completo POST:
- Punto final:
/avails/full-extract/batch/get - Cuerpo de la solicitud:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}' }... ] } - Cuerpo de respuesta:
[ { 'requestItemId':'<requestId>', 'success':'<true | false>', 'avail':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
PUBLICACIÓN:
- Punto final:
/avails/extracción completa/batch/put - Cuerpo de la solicitud:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}' 'body': { avails: [<Avail data>] } }... ] } - Cuerpo de respuesta:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
PUBLICACIÓN:
- Punto final:
/avails/full-extract/batch/delete - Cuerpo de la solicitud:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}&contractId={CPH | FIXED_FEE}&channelIdentity={channelIdentity}' }... ] } - Cuerpo de respuesta:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
PUBLICACIÓN:
- Punto final:
/avails/full-extract/batch/validate - Cuerpo de la solicitud:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}/validate' 'body': { avails: [<Avail data>] } }... ] } - Cuerpo de respuesta:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
Líneas de negocio
En el caso de Full Extract, todos los Avalls para una línea de negocio y un territorio deben entregarse juntos. Se admiten las siguientes líneas de negocio:
- PRIME_SUBSCRIPTION
- TVOD
- VOD
- CANALES
Los valores de BusinessLine se pueden determinar mediante la combinación de LicenseType y BenefitID, como se muestra en la siguiente tabla.
Tipo de licencia |
ID de beneficio |
Línea de negocios |
EST |
- |
TVOD |
VOD |
- |
TVOD |
POETA |
- |
TVOD |
SVOD |
PRIME |
PRIME_SUBSCRIPTION |
SVOD |
A4K |
PRIME_SUBSCRIPTION |
SVOD |
CUALQUIERA (no PRIME ni A4K) |
CANALES |
FVOD |
¿ALGUNA |
FVOD |
