O Prime Video oferece aos parceiros dois pacotes abrangentes de API projetados para simplificar o gerenciamento de conteúdo e fornecer informações comerciais valiosas. Este guia descreve o processo completo de integração do Content API Suite e do Analytics API Suite, incluindo requisitos de autenticação, configuração técnica e as principais diferenças entre os dois.
Etapa 1: Solicitar acesso e gerar credenciais
Entre em contato com seu contato do Prime Video ou faça uma solicitação de acesso via Fale conosco para solicitar acesso ao Content API Suite.
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.
Gere seu CSR
Você pode usar qualquer ferramenta de certificação para gerar seus 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 o Prime Video Contact
A CSR contém todas as informações de que precisamos para gerar seu certificado de API. Esse é o arquivo que você enviará ao seu contato como parte de sua 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 solicitaremos esse arquivo. Você o usará mais tarde ao fazer suas chamadas de API para nós.
Etapa 3: receba 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 solicitaçã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
Aqui estão exemplos de integrações usando diferentes tecnologias:
Bash
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
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'})
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: Teste sua integração
Para a API Avails, oferecemos suporte de testes para garantir que você possa enviar, atualizar e expirar com sucesso os avails 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 Status da Oferta e Status do Ativo, como elas são somente para leitura, você pode testar usando a conta de produção.
Etapa 6: Comece a usar a API
Parabéns! Seu teste está completo 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 do desenvolvedor da Amazon.
Registre sua inscrição
- Navegue até o Amazon Developer Console para iniciar o processo de registro
- Faça login com sua conta de desenvolvedor da Amazon existente 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.
Configure seu perfil
- Security Profile Name: escolha um nome descritivo que identifique claramente sua integração (por exemplo, “Performance Data Integration” ou “Analytics API Access”)
- Descrição: forneça uma explicação clara da finalidade do seu aplicativo e de como ele usará as APIs do Analytics
- URL do Aviso de Privacidade: inclua um URL que explique aos usuários como seu aplicativo manipulará e protegerá seus dados
- Clique em Salvar para criar seu perfil de segurança
- Você deve receber uma mensagem de sucesso depois de configurada corretamente
Defina seu URL de redirecionamento
- 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.
- Adicionar seu 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 esse URL com segurança. Você precisará usar esse URL exato na próxima etapa ao gerar seu código de autorização.
Receba suas credenciais
- Navegue até a guia Configurações da Web para acessar as credenciais do seu aplicativo
- Copie seu ID do cliente (isso serve como identificador exclusivo do seu aplicativo) e o segredo do cliente (isso funciona como a senha do seu aplicativo)
- Armazene ambas as credenciais com segurança no sistema de gerenciamento de segredos da sua organização. Elas serão usadas para autenticar todas as suas solicitaçõ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
- Navegue até 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 de cliente (da Etapa 1) no campo fornecido
- 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
Gere seu código de autorização
- Crie seu URL de autorização substituindo os espaços reservados entre colchetes por 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 esse URL no seu navegador para iniciar o fluxo de autorização
- Faça login com as credenciais da sua conta Slate quando solicitado
- Revise as permissões que seu aplicativo está solicitando e clique em Permitir para conceder acesso
- Após a autorização, você será redirecionado para o URL de redirecionamento especificado — copie o código de autorização da string de consulta do URL (ele aparecerá como
?code=YOUR_CODE
Prática recomendada: recomendamos criar uma conta Slate dedicada (por exemplo, api_access@yourcompany.com) com o mínimo de permissões 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 autorizador de usar relatórios, o aplicativo também terá sua permissão para usar relatórios revogada.
Etapa 3: solicite 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 mostra como recuperar seu primeiro refresh_token.
Solicitação inicial de token (somente na primeira vez):
Para solicitar um token:
- Insira client_id, client_secret, authorization_code e grant_type como dados de formulário codificados em URL.
- Faça uma solicitaçã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=authorization_code' \
--data 'code=[AUTH_CODE]' \
--data 'client_id=[ID]' \
--data 'client_secret=[SECRET] \
--data 'redirect_uri=[URI]'
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 de 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 — substituir[YOUR_ACCESS_TOKEN]
Etapa 5: Testar a integração
É 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: Comece a usar
Depois que o teste estiver concluído e você tiver validado 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 para seu conteúdo no Prime Video. Seus pipelines de dados agora podem consumir os arquivos do conjunto de dados somente para anexar para realizar a análise granular de que sua organização precisa.
Leia mais sobre as estruturas de dados da API Analytics disponíveis aqui:
