A API Avails é baseada na Partner API Framework, que oferece uma interface unificada para APIs acessíveis externamente. Essa estrutura permite que estúdios, empresas de pós-produção e outros parceiros de atendimento gerenciem programaticamente seu catálogo de vídeos no Prime Video.
Comece
Para acessar a API Avails, você precisará de um certificado MTLS e uma chave de API. Esta seção fornece as etapas para gerar uma Solicitação de Assinatura de Certificado (CSR), solicitar um certificado MTLS e fazer solicitações de API à API Avails.
Etapa 1: O cliente cria sua chave privada e a Solicitação de Assinatura de Certificado (CSR) usando o openssl.
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr
Etapa 2: O cliente envia um e-mail para pv-partner-apis-support@amazon.com com client.csr anexado. (A equipe responderá com um certificado em até 1 dia útil.) O trecho de código a seguir é um exemplo sugerido. EMAIL TEMPLATE
Partner Details
PartnerName :
Partner Alias :
Partner Resource Access : [Avails-Read,Avails-Write]
Request Limit :
Attachment
Partner Certificate signing request (client.csr).
Etapa 3: o cliente recebe certificado público, cacert e chave de API da equipe de API do parceiro. O trecho de código a seguir fornece um exemplo das mensagens que você pode receber. 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)
Etapa 4: o cliente usa PublicKey, certificado público do parceiro e chave de API para chamar a API.
Aqui estão alguns exemplos de integrações usando tecnologias diferentes.
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) => {
// ...
});
Revogar o acesso ao certificado MTLS
Ocasionalmente, um certificado MTLS pode precisar ser revogado. Se você precisar que um de seus certificados seja revogado, envie as informações mostradas no exemplo a seguir por e-mail para pv-partner-apis-support@amazon.com. EMAIL TEMPLATE
Partner Details
PartnerName :
Partner Alias :
Owner Email Id :
Certificate Serial Number :
ApiKey :
Mapeamento de esquema do MDDF para EMA Avail
Estamos usando o esquema MDDF Avail em JSON. Um diagrama do esquema está disponível no MovieLabs no seguinte link: https://www.movielabs.com/md/avails/v2.6/avails-v2.6.1/avails-v2.6.1.html#Link2. A tabela a seguir mostra o mapeamento do EMA para as propriedades e atributos do MDDF Avail suportados.
Prime Video MDDF JSON |
Planilha EMA do Prime Video |
Avail.compatibility.specVersion |
1.7.3 |
Disponível. Um ID |
ALID |
Disponível. Disposição.Tipo de entrada |
Tipo de entrada |
avail.licensor.displayName |
Nome de exibição |
Ativo disponível. _ID do conteúdo |
ALID |
avail.asset.workType |
Tipo de trabalho |
avail.asset.metadata.titleInternalAliias |
Apelido interno do título |
avail.asset.episodeMetadata.TitleInternal Aliias |
Título do episódio Internal Alias |
avail.asset.episodeMetadata.Número do episódio.Número |
Número do episódio |
avail.asset.episodeMetadata.SeasonMetadata.SeasonTitleInternalAlias |
Apelido interno do título da temporada |
avail.asset.episodeMetadata.SeasonMetadata.SeasonContentID |
TID sazonal |
avail.asset.episodeMetadata.SeasonMetadata.SeasonNumber.Number |
Número da temporada |
avail.asset.episodeMetadata.SeasonMetadata.Number of Episodes |
Contagem de episódios |
avail.asset.episodeMetadata.seriesMetadata.seriesContentID |
Série ALDID |
avail.asset.episodeMetadata.seriesMetadata.seriesMetadata.serieTitleInternalAlias |
Título da série Internal Alias |
avail.asset.episodeMetadata.SeriesMetadata.Number of Seasons |
Contagem de temporadas |
avail.asset.seasonMetadata.SeasonTitleAliias interno |
Apelido interno do título da temporada |
avail.asset.seasonMetadata.SeasonContentID |
TID sazonal |
avail.asset.seasonMetadata.SeasonNumber.Number |
Número da temporada |
avail.asset.SeasonMetadata.Número de episódios |
Contagem de episódios |
avail.asset.seasonMetadata.seriesMetadata.seriesContentID |
Série ALDID |
avail.asset.seasonMetadata.seriesMetadata.seriesTitleInternalAlias |
Título da série Internal Alias |
avail.asset.SeasonMetadata.SeriesMetadata.Number of Seasons |
Contagem de temporadas |
AVAIL.TRANSACTION.LicenseType |
Tipo de licença |
Disponível.Transação.Território.País |
Território |
Disponibilizar.Transação.Iniciar |
Iniciar |
Avail.Transaction.End |
Fim |
Avail.transaction.AllowedLanguage |
Idiomas permitidos |
Linguagem avail.transaction.holdback |
Linguagem Holdback |
avail.transaction.assetLanguage.value |
Idioma do ativo |
Avail.transaction.assetLanguage. _ativo |
Tipo de localização |
Avail.transaction.license Descrição dos direitos |
Descrição dos direitos de licença |
Avail.Transaction.Format Profile |
Formatar perfil |
Avail.transaction.ID do contrato |
ID do contrato |
Avail.Transaction. Outras instruções |
Outras instruções |
Disponível. Transação. _ID da transação |
ID disponível |
Disponível. Transação. Prazo. _TermName.Identidade do canal |
Identidade do grupo |
Disponível. Transação. Prazo. _TermName.Data de anúncio |
Data do anúncio |
Disponível. Transação. Prazo. _TermName.SuppressionLiftDate |
Data de elevação da supressão |
Disponível. Transação. Prazo. _TermName. duração do aluguel |
Duração do aluguel |
Disponível. Transação. Prazo. _TermName.WatchDuration |
Duração do relógio |
Disponível. Transação. Prazo. _TermName.Baixar |
Baixar |
Disponível. Transação. Prazo. _TermName.tier |
Tipo de preço |
Disponível. Transação. Prazo. _TermName.Categoria |
Tipo de preço |
Disponível. Transação. Prazo. _TermName.wsp |
Tipo de preço |
Disponível. Transação. Prazo. _TermName.srp |
SRP |
avail.transaction.term.money.value |
Preço |
Disponível.Transaction.Term.Money. _moeda |
Preço Moeda |
Disponível.Transação.Termo.Exclusividade |
Exclusividade |
avail.transaction.term.ExclusiveAttributes |
Atributos exclusivos |
avail.sharedEntitlement.EcossystemId |
ID_DMA |
Avail.SharedEntitlement.Ecosystem |
ID_DMA |
Métodos
As seções a seguir descrevem os diferentes métodos de solicitação de API que você pode usar com a API Avails, incluindo seus endpoints específicos, e qual deve ser a aparência do corpo de cada solicitação e resposta.
Categoria: Extrato completo
GET:
- Ponto final:
/avails/ {licensor} /full-extract/ {ALID}? território = {território} &BusinessLine = {BusinessLine} - Corpo da solicitação: -
- ResponseBody: Aproveite as transações para um escopo
COLOQUE:
- Ponto final:
/avails/ {licensor} /full-extract/ {ALID} - Corpo da solicitação:
{... Disponibilizar dados} - ResponseBody: Resposta de sucesso/falha
EXCLUIR:
- Ponto final:
/avails/ {licensor} /full-extract/ {ALID}? território = {território} &BusinessLine= {BusinessLine} &ContractId= {CPH | FIXED_FEE} &ChannelIdentity= {ChannelIdentity} - Corpo da solicitação: -
- ResponseBody: Resposta de sucesso/falha
POSTAGEM:
- Ponto final:
/avails/ {licensor} /full-extract/ {ALID} /validate - Corpo da solicitação:
{... Disponibilizar dados} - ResponseBody: Resposta de sucesso/falha
Categoria:
Subcategoria do lote: Extração completa
POST:
- Ponto final:
/avails/full-extract/batch/get - Corpo da solicitação:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}' }... ] } - Corpo de resposta:
[ { 'requestItemId':'<requestId>', 'success':'<true | false>', 'avail':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
POSTAGEM:
- Ponto final:
/avails/full-extract/batch/put - Corpo da solicitação:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}' 'body': { avails: [<Avail data>] } }... ] } - Corpo de resposta:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
POSTAGEM:
- Ponto final:
/avails/full-extract/batch/delete - Corpo da solicitação:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}?territory={territory}&businessLine={businessLine}&contractId={CPH | FIXED_FEE}&channelIdentity={channelIdentity}' }... ] } - Corpo de resposta:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
POSTAGEM:
- Ponto final:
/avails/full-extract/batch/validate - Corpo da solicitação:
{ [ { 'requestId': '<RequestId>', 'path':'/avails/{licensor}/full-extract/{ALID}/validate' 'body': { avails: [<Avail data>] } }... ] } - Corpo de resposta:
[ { 'requestId':'<requestId>', 'statusCode':'<statusCode>', 'body':'<responseBody>', 'errorMessage':'<errorMessage>' }... ]
Linhas de negócios
Para o Full Extract, todos os Avails para uma linha de negócios + território devem ser entregues juntos. As seguintes linhas de negócios são suportadas:
- PRIME_SUBSCRIÇÃO
- TVOD
- VOD
- CANAIS
Os valores do BusinessLine podem ser determinados pela combinação de LicenseType e BenefitID, conforme mostrado na tabela a seguir.
Tipo de licença |
ID do benefício |
Linha de negócios |
EST |
- |
TVOD |
VOD |
- |
TVOD |
POETA |
- |
TVOD |
SVOD |
PRIME |
ASSINATURA PRIME |
SVOD |
A4K |
ASSINATURA PRIME |
SVOD |
QUALQUER (não PRIME ou A4K) |
CANAIS |
VOD |
QUALQUER |
VOD |
