Video Central

Visão geral da API de Conjuntos de Dados

A API de Conjuntos de Dados faz parte do nosso novo produto de dados para parceiros, o Slate Analytics. Ao contrário de outros relatórios do Slate, os conjuntos de dados apenas recebem adições (cada arquivo contém novos dados). Eles não estão disponíveis para download na interface do usuário do Slate e podem ser acessados somente por meio da API. Outro aspecto é que são criados explicitamente para que os engenheiros de dados dos parceiros trabalhem com dados granulares e realizem análises. Este tópico ajuda os engenheiros de dados a configurar seus pipelines a fim de recuperar o conjunto de dados, define os valores nos arquivos do conjunto de dados e fornece exemplos de consultas e sugestões sobre as melhores maneiras de os parceiros usarem esses dados.

Uso prático de conjuntos de dados

Os conjuntos de dados são fornecidos aos consumidores na forma de registros de alterações. Cada evento é publicado apenas uma vez. No entanto, se for necessário atualizar quaisquer valores de coluna para uma linha fornecida anteriormente, publicaremos uma nova versão do registo para refletir as alterações no seu próximo arquivo disponível. O registro de alterações é usado somente para adição, para garantir que todas as modificações de dados sejam capturadas. Os engenheiros de dados podem usar esse registro de alterações para atualizar suas tabelas de dados diretamente.

Ao processar registros de alterações, é essencial usar sempre o registro mais recente de um determinado event_id, com base na coluna last_update_time_utc. Isso garante que você sempre tenha a versão mais atualizada de cada registro. Se um registro precisar ser excluído, essa ação será refletida na coluna is_deleted. O valor 1 indica que o registro foi excluído, e o valor 0 representa um registro ativo. Essa abordagem de registro de alterações permite que você gerencie com eficiência dados novos e em constante mudança, além de garantir que suas tabelas de dados permaneçam precisas e atualizadas com as informações mais recentes.

Introdução à API de Conjuntos de Dados

Antes de fazer solicitações à API de Conjuntos de Dados, é importante entender os requisitos básicos para autenticação e paginação. Esta seção aborda como acessar a API com segurança e navegar por grandes conjuntos de dados com eficiência.

Integração com a API Analytics
Para recuperar conjuntos de dados, você precisa primeiro integrar-se ao pacote da API Analytics. Mais informações podem ser encontradas aqui.

A URI base é: https://videocentral.amazon.com/apis/v2. Todas as solicitações devem incluir um token de autenticação LWA válido no cabeçalho de autorização da solicitação. Por exemplo:

Se o cabeçalho da solicitação não incluir o token ou se o token expirar, a API de Conjuntos de Dados retornará uma exceção de não autorizado.

Paginação
Todas as respostas da API do Slate são paginadas. Os parâmetros de paginação são especificados por meio de parâmetros de solicitações.

Parâmetro de solicitação	Valor padrão	Descrição
limit	10	O número de documentos retornados em uma única página (o tamanho da página).
offset	0	O número de páginas a serem ignoradas (o número da página).

Todas as respostas paginadas contêm os seguintes campos.

Campo	Descrição
total	A contagem total de documentos em todas as páginas.
next	A URL para a próxima página. Nulo se for a última página.

Uso da API de Conjuntos de Dados

Para acessar os conjuntos de dados por meio de programação, os clientes devem seguir uma série de chamadas de API que enumeram os recursos disponíveis, como contas, grupos, negócios e conjuntos de dados, antes de recuperar URLs para download dos arquivos de dados. Essa sequência foi desenvolvida para oferecer suporte à automação e pode ser integrada a pipelines de dados recorrentes ou fluxos de trabalho programados.

Listar contas
/v2/accounts

Este recurso retorna a lista de contas do Slate às quais o usuário pode acessar. O conjunto de contas pode ser acessado no Slate por meio da lista suspensa de contas, localizada no canto superior direito do portal. Você também pode usar estes links para encontrar seu account_id ou seu channel/studio_id.

Exemplo de solicitação

Exemplo de resposta

Listar grupos (linhas de negócio)
/v2/accounts/{account_id}

Este recurso retorna os grupos de linhas de negócios (como canais) aos quais o usuário pode acessar.

Exemplo de solicitação

Exemplo de resposta

Listar empresas
/v2/accounts/{account_id}/{group_id}

Este recurso retorna uma lista de empresas (como nomes de canais específicos) disponíveis para esta conta, dependendo da linha de negócios fornecida.

Exemplo de solicitação

Exemplo de resposta

Listar conjuntos de dados disponíveis
/v2/accounts/{acccount_id}/{group_id}/{business_id}/datasets

Este recurso retorna a lista de conjuntos de dados disponíveis para um determinado canal ou estúdio. (A lista de conjuntos de dados disponíveis e seus atributos estão incluídos em Definições de conjuntos de dados, mais adiante neste tópico.) Os conjuntos de dados atualmente disponíveis para download são:

Assinatura: Eventos no ciclo de vida do cliente, como quando um cliente se inscreveu.
Reprodução: Eventos da sessão de reprodução em que os clientes interagiram com o conteúdo.
Catálogo: Eventos em que os metadados do seu catálogo foram alterados, como quando um novo título foi adicionado.

Exemplo de solicitação

Exemplo de resposta

Obter arquivo(s) de conjunto de dados
/v2/accounts/{account_id}/{group_id}/{business_id}/datasets/{dataset_id}

Este recurso fornece uma lista de arquivos de conjunto de dados. Dependendo do intervalo de tempo solicitado, a lista pode incluir um grande número de arquivos. O campo total indica a quantidade de arquivos esperada. Após o reprocessamento de todos os arquivos, é possível acompanhar as atualizações solicitando constantemente arquivos usando startDateTime igual ao último registro de data e hora recuperado e endDateTime definido para a hora atual.

Novos conjuntos de dados são publicados aproximadamente a cada 4 horas e podem conter eventos que ocorreram nas últimas 12 horas. É recomendável acessar nossa API várias vezes ao dia, aproximadamente a cada 4-6 horas, para garantir que seus dados locais estejam o mais completos e atualizados possível. Caso ocorra algum atraso na publicação, comunicaremos por e-mail assim que possível.

A tabela a seguir descreve os parâmetros de solicitação disponíveis para arquivos de conjunto de dados.

Parâmetro de solicitação	Descrição
startDateTime	A recomendação é definir a partir da última vez que foi extraído. (Formato: AAAA-MM-DDTHH:MM:SSZ – registro de data e hora em UTC)
endDateTime	A recomendação é definir no momento da extração/hora atual. (Formato: AAAA-MM-DDTHH:MM:SSZ – registro de data e hora em UTC)
limit	O limite máximo é de 1000 links por página.

Observação: Nosso período máximo de retenção de dados é de 2 anos. Solicitações de conjuntos de dados com um registro de data e hora anterior a 2 anos não retornarão nenhum resultado.

Exemplo de solicitação

Exemplo de resposta

Observações:

O tamanho máximo do arquivo compactado é de 300 MB. Os arquivos que excederem esse limite serão divididos em vários arquivos.
O tempo de vida útil (TTL) da URL pré-assinada é de 60 minutos.

Definições dos conjuntos de dados

As tabelas desta seção listam as colunas, os tipos de dados e as definições para cada um dos três conjuntos de dados disponíveis.

Conjunto de dados de assinatura

Coluna	Tipo	Definição
subscription_event_id (pk)	string	A ID exclusiva para cada evento de assinatura fornecido por meio desse registro.
subscription_event_type	string	O tipo de evento de assinatura que ocorreu: Início: O cliente se inscreveu em um canal ao qual não era assinante anteriormente. Renovação: O cliente se inscreveu em um canal e já estava ativo nesse canal antes do evento de assinatura. Cancelamento: O cliente cancelou sua assinatura. Suspensão: A assinatura do cliente foi temporariamente pausada devido a problemas de pagamento (fundos insuficientes ou informações de cobrança inválidas) A assinatura será retomada automaticamente e gerará um evento de renovação assim que o cliente atualizar suas informações de cobrança e o pagamento for processado com sucesso. Ativo – RA ativada O cliente está ativo e ativou a renovação automática. Ativo – RA desativada: O cliente está ativo, mas desativou a renovação automática.
subscription_event_time_utc	timestamp	A hora em que o evento de assinatura ocorreu, no horário padrão UTC.
subscription_event_time_zone	string	O fuso horário da loja de assinaturas.
cid	string	Identificador de cliente anônimo (CID). Esse identificador de cliente permanecerá para todos os eventos em um único canal principal, a fim de permitir o movimento entre níveis e o acompanhamento do ciclo de vida do cliente.
offer_id	string	A ID da oferta de assinatura específica à qual o evento está relacionado.
offer_name	string	O nome legível da oferta.
offer_type	string	O tipo de oferta.
offer_marketplace	string	A loja onde a oferta de assinatura estava disponível.
offer_billing_type	string	O tipo de pagamento exigido para a oferta: HO: Oferta definitiva; pagamento necessário. FT: Período de teste grátis; nenhum pagamento é necessário.
offer_payment_amount	string	O valor da cobrança da offer_id.
benefit_id	string	A ID do benefício Prime Video sob o qual a oferta está configurada.
channel_label	string	O nome do canal em que a oferta está disponível. Observação: Se esta coluna apresentar um valor nulo e você tiver alguma dúvida, entre em contato com seu CAM ou PsM.
channel_tier_label	string	O nome do canal em que a oferta está disponível. Observação: Se esta coluna apresentar um valor nulo e você tiver alguma dúvida, entre em contato com seu CAM ou PsM.
is_promo	inteiro	Indica se uma oferta está em promoção no momento do evento (0 = sem promoção, 1 = com promoção).
create_time_utc	timestamp	A hora em que o registro do evento de assinatura foi criado, no horário padrão UTC.
last_update_time_utc	timestamp	A hora em que o registro do evento de assinatura foi atualizado pela última vez, no horário padrão UTC.
is_deleted	inteiro	Indica se um registro criado anteriormente deve ser excluído (0 = deve permanecer, 1 = deve ser excluído).

Conjunto de dados de reprodução

Coluna	Tipo	Definição
session_id (pk)	string	A ID exclusiva para a sessão de reprodução.
marketplace_id	inteiro	A ID exclusiva para a loja de reprodução.
marketplace_desc	string	Uma descrição familiar para a loja de reprodução.
cid	string	O identificador do usuário, anonimizado com UUID.
benefit_id	string	O benefício associado ao conteúdo que foi transmitido.
catalog_id	string	Chave estrangeira (FK) usada para associar à tabela de catálogo.
subscription_offer_id	string	A offer_id da assinatura à qual o cliente está inscrito no momento da transmissão (Active ou ApprovalPending).
subscription_event_id	string	Chave estrangeira (FK) para associar ao registo de eventos de assinatura para obter o estado exato do assinante no momento da reprodução (Ativa)
start_segment_utc	timestamp	Início do segmento de reprodução no horário UTC.
end_segment_utc	timestamp	Fim do segmento de reprodução no horário UTC.
seconds_viewed	inteiro	Segundos de conteúdo transmitido pelo usuário durante a reprodução.
position_start	duplo	Segundo trecho do fluxo onde a sessão de reprodução começou.
position_end	duplo	Segundo trecho da transmissão onde a sessão de reprodução terminou.
connection_type	string	Conexão usada pelo cliente para transmitir o conteúdo.
stream_type	string	Classificação entre transmissões de vídeo sob demanda, ao vivo ou logo após a transmissão (JAB).
device_class	string	Tipo de dispositivo (como dispositivos de sala de estar, celular, web ou outros).
device_sub_class	string	Tipo granular de dispositivo (como console de jogos, smart_tv, roku).
geo_dma	string	A área de comercialização designada (DMA, na sigla em inglês), com três dígitos geográficos, onde o fluxo foi gerado.
playback_method	string	Considera se a reprodução é Online ou Offline.
quality	string	Qualidade de reprodução (como 1080p ou 4K)
event_type	string	O tipo de evento determinante (playback_segments)
create_time_utc	timestamp	Data e hora em que o registro foi adicionado à tabela, no horário UTC.
last_update_time_utc	timestamp	Data e hora da última atualização, quando o registro foi modificado, no horário UTC.
is_deleted	inteiro	Sinal que indica aos parceiros se o registro deve ser excluído em seu sistema.

Conjunto de dados do catálogo

Coluna	Tipo	Definição
id (pk)	string	A ID exclusiva do título.
marketplace_id	inteiro	A ID exclusiva para a loja de ofertas.
benefit_id	string	O benefício associado ao conteúdo estendido.
title	string	O título da série/filme.
vendor_sku	string	Um identificador aleatório que o fornecedor gera para cada um dos seus filmes ou episódios.
season	número inteiro	O número da temporada (para conteúdo em episódios).
episode	número inteiro	O número do episódio.
episode_name	string	O nome do episódio (opcional).
runtime_minutes	número inteiro	O tempo de exibição do conteúdo visualizado.
live_linear_channel_name	string	O nome do canal para conteúdo ao vivo.
content_type	string	Série ou Filme.
content_quality	string	HD ou SD
content_group	string	3P_SUBS
create_time_utc	timestamp	Data e hora em que o registro foi adicionado à tabela, no horário UTC.
last_update_time_utc	timestamp	Data e hora da última atualização, quando o registro foi modificado, no horário UTC.
is_deleted	inteiro	Sinal que indica aos parceiros se o registro deve ser excluído em seu sistema.

Exemplos de consultas

O exemplo de SQL a seguir demonstra como as tabelas do conjunto de dados se conectam. Você pode unir os dados de reprodução ao registro de eventos de assinatura na coluna subscription_event_id. Isso fornece o status de assinatura mais recente antes desse fluxo. Neste exemplo, a coluna catalog_id no conjunto de dados de reprodução é unida ao campo id em catalog_event_log para fornecer todos os metadados do catálogo.

O exemplo de SQL a seguir retornará os 10 primeiros títulos assistidos pelos clientes após o início de sua assinatura.

Exemplo de orquestração

Se você deseja automatizar a extração de dados da API de Conjuntos de Dados em uma programação recorrente, o seguinte script Python de exemplo demonstra como fazer solicitações incrementais à API a cada 6 horas. Ele rastreia o registro de data e hora da última solicitação bem-sucedida, salvando-o localmente, e usa esse valor, acrescido de um segundo, como startDateTime para a próxima solicitação. O script calcula o endDateTime como a hora atual, cria os parâmetros de consulta apropriados e envia uma solicitação GET com autenticação. Essa abordagem garante a recuperação contínua e sem sobreposição de dados em intervalos de tempo e pode ser programada por meio do cron ou de outro recurso de agendamento de tarefas.