O Prime Video oferece aos parceiros dois pacotes de API abrangentes projetados para agilizar o gerenciamento de conteúdo e fornecer informações comerciais valiosas. Este guia descreve o processo completo de integração do Pacote de API de Conteúdo e do Pacote de API do Analytics, incluindo requisitos de autenticação, configuração técnica e principais diferenças entre os dois.
Etapa 1: Solicitar acesso e Gerar credenciais
Fale com seu contato do Prime Video ou faça uma solicitação de acesso por meio do Fale conosco para solicitar acesso ao Pacote de API de Conteúdo.
Etapa 2: Gerar credenciais e Enviar
Depois que sua solicitação de acesso for aprovada, gere uma chave privada e uma Solicitação de Assinatura de Certificado (CSR) para cada ambiente e compartilhe-as com seu contato designado do Prime Video.
Gerar sua CSR
Você pode usar qualquer ferramenta de certificação para gerar suas CSRs. Se quiser usar o OpenSSL, você pode executar os dois comandos a seguir:openssl genrsa -out client.key 2048
openssl req -new -key client.key -out prod_client.csr
Enviar sua CSR para seu contato do Prime Video
A CSR contém todas as informações necessárias para gerar seu certificado de API. Esse é o arquivo que você enviará ao seu contato como parte da solicitação de integração. Depois que o Prime Video receber sua CSR, você não precisará desse arquivo novamente.
Observação: É muito importante que você mantenha seus arquivos de chave privada seguros e nunca os compartilhe com ninguém, incluindo o Prime Video. Nunca pediremos esse arquivo. Você o usará mais tarde ao fazer suas chamadas de API para nós.
Etapa 3: Receber suas credenciais
Depois que sua solicitação for aprovada, você receberá um e-mail da equipe do Prime Video com as seguintes informações:
- O certificado público que você usará para fazer chamadas para nós.
- Sua chave de API para cabeçalhos de requisição
- Os endpoints de URL para as chamadas de API.
- Informações sobre o TPS para o qual você está configurado com seu certificado.
Etapa 4: Configurar sua integração
Parabéns! Agora você pode usar sua chave privada, certificado público e chave de API para chamar a API. Aqui estão exemplos de integrações usando diferentes tecnologias:
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) => {
// ...
});
Etapa 5: Testar sua integração
Para a API Avails, oferecemos suporte de teste para garantir que você possa enviar, atualizar e expirar os avails com sucesso via API. Como essas operações afetam diretamente os ativos (não apenas a recuperação de dados), é altamente recomendável que todos os parceiros testem sua integração minuciosamente. Para as APIs Offer Status e Asset Status, já que elas são somente para leitura, você pode testar usando a conta de Produção.
Etapa 6: Começar a usar a API
Parabéns! Seu teste foi concluído e validado. Agora você pode começar a usar o ambiente de produção com suas credenciais de produção para gerenciar seu conteúdo no Prime Video. Sua integração está pronta para simplificar suas operações de conteúdo e fornecer visibilidade em tempo real do seu catálogo.
Etapa 1: Criar seu perfil de segurança
Como parte dessa etapa, você configurará as credenciais do aplicativo e definirá suas configurações de autenticação por meio do console de desenvolvedores da Amazon.
Registrar sua inscrição
- Acesse o Console de desenvolvedores da Amazon para iniciar o processo de registro
- Faça login com sua conta de desenvolvedor existente da Amazon ou crie uma nova conta se você não tiver uma
- Clique em Criar um novo perfil de segurança para começar a definir as configurações de autenticação do seu aplicativo
Configurar seu perfil
- Nome do perfil de segurança: Escolha um nome descritivo que identifique claramente sua integração (por exemplo, “Integração de dados de desempenho” ou “Acesso à API do Analytics”)
- Descrição: Forneça uma explicação clara sobre a finalidade do seu aplicativo e como ele usará as APIs do Analytics
- URL da Notificação de privacidade: Inclua uma URL que explique aos usuários como seu aplicativo tratará e protegerá seus dados
- Clique em Salvar para criar seu perfil de segurança
- Você deverá receber uma mensagem de sucesso depois de configurar corretamente
Definir sua URL de direcionamento
- Acesse seu perfil e selecione as guias Perfil de segurança para Gerenciar em seu perfil de segurança recém-criado:
- Em seguida, selecione Configurações da Web para configurar o comportamento de redirecionamento do seu aplicativo
- Adicione sua URL de redirecionamento — esse é o endpoint seguro para o qual os usuários serão enviados após autorizarem seu aplicativo (é necessário usar https:// ou https://localhost para desenvolvimento local)
Importante: Salve essa URL com segurança — você precisará usar essa URL exata na próxima etapa ao gerar seu código de autorização.
Receber suas credenciais
- Acesse a guia Configurações da Web para acessar suas credenciais do aplicativo
- Copie seu ID do cliente (que serve como identificador exclusivo do seu aplicativo) e o Segredo do cliente (isso funciona como a senha do seu aplicativo)
- Armazene as duas credenciais com segurança no sistema de gerenciamento de segredos da sua organização — elas serão usadas para autenticar todas as suas requisições de API
Etapa 2: Autorizar sua inscrição
Como parte dessa etapa, você autorizará seu aplicativo a acessar o Prime Video Slate em nome da sua organização, estabelecendo as permissões necessárias para recuperar dados e análises de desempenho por meio das APIs.
Adicionar seu aplicativo ao Slate
- Faça login na sua conta do Prime Video Slate usando as credenciais da sua organização
- Acesse as Configurações da conta no canto superior direito e selecione Aplicativos no menu suspenso
- Clique em Adicionar aplicativo para iniciar o processo de autorização
- Insira seu ID do cliente (da Etapa 1) no campo apresentado
- Marque a caixa de seleção Relatórios para conceder ao seu aplicativo acesso aos dados e relatórios de desempenho
- Clique em Adicionar aplicativo para concluir o registro no Slate
Gerar seu código de autorização
- Crie sua URL de autorização substituindo os espaços reservados entre colchetes pelas suas credenciais reais da Etapa 1:
https://www.amazon.com/ap/oa?client_id=[YOUR_CLIENT_ID]&redirect_uri=[YOUR_REDIRECT_URI]&scope=videocentral::reports:read&response_type=code:
- Abra essa URL em seu navegador para iniciar o fluxo de autorização
- Faça login com as credenciais da sua conta Slate quando solicitado
- Analise as permissões que seu aplicativo está solicitando e clique em Permitir para conceder acesso
- Após a autorização, você acessará a URL de redirecionamento especificada — copie o código de autorização da string de consulta da URL (ele aparecerá como
?code=YOUR_CODE
Práticas recomendadas: Recomendamos criar uma conta Slate dedicada (por exemplo, api_access@yourcompany.com) com as permissões mínimas necessárias especificamente para acesso à API. Essa abordagem aprimora a segurança e facilita o gerenciamento e a auditoria do uso da API em toda a organização.
Observação: se você remover as permissões do usuário que autoriza a usar relatórios, o aplicativo também terá sua permissão para usar relatórios revogados.
Etapa 3: Solicitar seus tokens de acesso
Como parte dessa etapa, você usará seu código de autorização para obter os tokens necessários para fazer chamadas de API autenticadas. O token de acesso permite que seu aplicativo recupere dados de desempenho, enquanto o token de atualização permite gerar novos tokens de acesso sem repetir o processo de autorização.
Os códigos de autorização são tokens de uso único. Quando usados para recuperar um access_token eles retornam um refresh_token que pode ser usado para recuperar o próximo access_token. A seção a seguir leva mostra como recuperar seu primeirorefresh_token.
Solicitação inicial de token (somente na primeira vez):
Para solicitar um token:
- Insira o client_id, o client_secret, o authorization_code e o grant_type como dados de formulário codificados da URL.
- Faça uma requisição HTTP.
O comando curl para gerar tokens a partir do authorization_code é mostrado no exemplo a seguir.
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'
Atualizando seu token de acesso:
Para todas as sessões subsequentes após sua solicitação inicial de token, use seu token de atualização para obter novos tokens de acesso: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]'
Etapa 4: Configurar seu aplicativo
Parabéns! Agora você tem todas as credenciais necessárias para chamar as APIs de desempenho. Como parte dessa etapa, você configurará seu aplicativo para incluir seu token de acesso no cabeçalho de autorização de cada solicitação de API, permitindo que você recupere dados de assinatura, métricas de desempenho e análises do seu conteúdo.
Exemplo de solicitação de API:
curl --request GET \
--url https://videocentral.amazon.com/apis/v1/accounts \
--header 'authorization: bearer Atza|IwEBIPSxTCdGGC-xL-ywFib_lJfg-D7d435Jw739GWa3xy6dHJ
Este exemplo demonstra como autenticar suas solicitações: substitua [YOUR_ACCESS_TOKEN]
Etapa 5: Integração de testes
É altamente recomendável que todos os parceiros testem minuciosamente sua integração para garantir acesso confiável aos dados de desempenho. Como parte dessa etapa, você validará se o fluxo de autenticação funciona corretamente, se as chamadas de API retornam os dados esperados e se o tratamento de erros está configurado corretamente.
Etapa 6: Começar a usar
Depois que o teste for concluído e você validar que sua integração funciona de forma confiável, você poderá começar a usar o ambiente de produção para recuperar dados e análises de desempenho em tempo real do seu conteúdo no Prime Video. Seus pipelines de dados agora podem consumir os arquivos de conjunto de dados somente anexados para realizar a análise granular de que sua organização precisa.
Leia mais sobre as estruturas de dados da API do Analytics disponíveis aqui:
