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, ou seja, recebem 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 dos conjuntos de dados

Fornecemos conjuntos de dados aos consumidores na forma de registros de alterações. Cada evento é publicado apenas uma vez. No entanto, se algum valor de uma linha fornecida anteriormente na coluna precisar ser atualizado, publicaremos uma nova versão do registro para refletir as alterações no 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 gerenciar com eficiência dados novos e alterados, além de garantir que as tabelas de dados sejam precisas e estejam atualizadas com as informações mais recentes.

Etapas prévias à API de conjuntos de dados

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

Autenticação
Para recuperar conjuntos de dados, é necessário ter:

Um perfil de segurança do Login com a Amazon
Um código de autorização para solicitar um token
Um token para todas as solicitações de curl

O URI base é: https://videocentral.amazon.com/apis/v2. Todas as solicitações devem incluir um token de autenticação do 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 expirou, a API de conjuntos de dados retornará uma exceção não autorizada.

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 devolvidos em uma única página (o tamanho de página).
offset	0	O número de páginas para pular (o número de página).

Todas as respostas paginadas contêm os campos a seguir.

Campo	Descrição
total	O total de documentos em todas as páginas.
next	O URL para a página seguinte. 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 listam os recursos disponíveis, como contas, grupos, negócios e conjuntos de dados, antes de recuperar os 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 que o usuário pode acessar. O conjunto de contas pode ser acessado no Slate por meio da lista suspensa de contas no canto superior direito do portal. Você também pode usar esses links para encontrar seu account_id ou 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 das linhas de negócios (como canais) que o usuário pode acessar.

Exemplo de solicitação

Exemplo de resposta

Listar negócios
/v2/accounts/{account_id}/{group_id}

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

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 nas 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 arquivos 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 esperada de arquivos. Após ter reprocessado todos os arquivos, você pode se manter atualizado solicitando continuamente arquivos usando um startDateTime igual ao último carimbo de data/hora recuperado e um endDateTime definido como o horário atual.

Novos conjuntos de dados são publicados aproximadamente a cada 4 horas e podem conter eventos que ocorreram nas 12 horas anteriores. Recomendamos fazer chamadas a nossa API várias vezes por dia, aproximadamente a cada 4 a 6 horas, para garantir que seus dados locais estejam o mais completos e atualizados possível. Se houver um atraso na publicação, enviaremos comunicações por e-mail o mais rápido 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	Recomenda-se definir a partir da hora da última extração. (Formato: AAAA-MM-DDTHH:MM:SSZ - horário UTC)
endDateTime	Recomenda-se definir na hora da extração/hora atual. (Formato: AAAA-MM-DDTHH:MM:SSZ - horário UTC)
limit	O limite máximo é de 1.000 links por página.

Observação: o período máximo da nossa retenção de dados é de 2 anos. Solicitações de conjuntos de dados com carimbo de data/hora mais antigo que 2 anos não retornarão nenhum resultado.

Exemplo de solicitação

Exemplo de resposta

Observações:

O tamanho máximo do arquivo zip é de 300 MB. Os arquivos que excederem esse limite serão divididos em vários arquivos.
O tempo de vida útil (TTL) do URL com permissão temporária é de 60 minutos.

Definições do conjunto de dados

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

Conjunto de dados de assinatura

Coluna	Tipo	Definição
subscription_event_id (pk)	string	O ID exclusivo de 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 estava inscrito 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. Ativo – AR ativada: o cliente está ativo e ativou a renovação automática. Ativo – AR 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 do mercado da assinatura.
cid	string	Identificador de cliente (CID) anônimo. Esse identificador de cliente persistirá em todos os eventos em um único canal principal para permitir o movimento entre camadas e o rastreamento do ciclo de vida do cliente.
offer_id	string	O ID da oferta de assinatura específica relacionado ao evento ocorrido.
offer_name	string	O nome da oferta legível por humanos.
offer_type	string	O tipo de oferta.
offer_marketplace	string	O mercado em que a oferta de assinatura estava ativa.
offer_billing_type	string	O tipo de pagamento exigido para a oferta: HO: assinatura paga (Hard Offer); pagamento necessário. FT: período de teste gratuito (Free Trial); nenhum pagamento é necessário.
offer_payment_amount	string	O valor da cobrança do offer_id.
benefit_id	string	O ID do benefício Prime Video de acordo com o qual a oferta está configurada.
channel_label	string	O nome do canal no qual a oferta está inserida. Observação: se esta coluna mostrar um valor nulo e você tiver dúvidas, entre em contato com seu CAM ou PSM.
channel_tier_label	string	O nome do canal no qual a oferta está inserida. Observação: se esta coluna mostrar um valor nulo e você tiver dúvidas, entre em contato com seu CAM ou PsM.
is_promo	int	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	int	Indica se um registro criado anteriormente deve ser excluído (0 = deve ser mantido, 1= deve ser excluído).

Conjunto de dados de reprodução

Coluna	Tipo	Definição
session_id (pk)	string	O ID exclusivo da sessão de reprodução.
marketplace_id	int	O ID exclusivo do mercado no qual ocorre a reprodução.
marketplace_desc	string	Descrição familiar para o mercado no qual ocorre a reprodução.
cid	string	O identificador do usuário, anonimizado com UUID.
benefit_id	string	O benefício associado ao conteúdo transmitido.
catalog_id	string	Chave estrangeira (FK) usada para entrar na tabela do catálogo.
subscription_offer_id	string	O offer_id da assinatura do cliente no momento do streaming (Active ou ApprovalPending).
subscription_event_id	string	Chave estrangeira (FK) para entrar no registro de eventos de assinatura e obter o status exato do assinante no momento da reprodução (Active).
start_segment_utc	timestamp	Segmento do início da reprodução no horário UTC.
end_segment_utc	timestamp	Segmento do fim da reprodução no horário UTC.
seconds_viewed	int	Segundos durante os quais o usuário fez streaming do conteúdo durante a reprodução.
position_start	double	Segundo no qual teve início o streaming durante a sessão de reprodução.
position_end	double	Segundo no qual terminou o streaming durante a sessão de reprodução.
connection_type	string	Conexão usada pelo cliente para fazer streaming do conteúdo.
stream_type	string	Classificação do tipo de streaming: vídeo sob demanda (VOD), 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 e roku.
geo_dma	string	A área de mercado designada (DMA) geográfica de 3 dígitos onde o streaming foi gerado.
playback_method	string	Determina se a reprodução é online ou offline.
quality	string	Qualidade da reprodução, como 1080p ou 4K.
event_type	string	O tipo de evento determinado (playback_segments).
create_time_utc	timestamp	Carimbo de data/hora em que o registro foi adicionado à tabela, no horário UTC.
last_update_time_utc	timestamp	Carimbo de data/hora da última atualização no momento em que o registro foi modificado, no horário UTC.
is_deleted	int	Sinal que indica aos parceiros se o registro deve ser excluído em seu sistema.

Conjunto de dados de catálogo

Coluna	Tipo	Definição
id (pk)	string	O ID exclusivo do título.
marketplace_id	int	O ID exclusivo do mercado da oferta.
benefit_id	string	O benefício associado ao conteúdo mais amplo.
title	string	O título da série/filme.
vendor_sku	string	Um identificador aleatório que o fornecedor gera para cada um de seus filmes ou episódios.
season	integer	O número da temporada (para conteúdo em episódios).
episode	integer	O número do episódio.
episode_name	string	O nome do episódio (opcional).
runtime_minutes	integer	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	Carimbo de data/hora em que o registro foi adicionado à tabela, no horário UTC.
last_update_time_utc	timestamp	Carimbo de data/hora da última atualização no momento em que o registro foi modificado, no horário UTC.
is_deleted	int	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 sobre reprodução ao registro de eventos de assinatura na coluna subscription_event_id. Isso fornece o status mais recente da assinatura antes de tal streaming. 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 depois que iniciarem uma assinatura.

Exemplo de orquestração

Se você quiser automatizar a extração de dados da API de conjuntos de dados em uma programação recorrente, o exemplo de script Python a seguir demonstra como fazer chamadas incrementais à API a cada 6 horas. Ele rastreia o carimbo de data/hora da última solicitação bem-sucedida salvando-o localmente de forma permanente e usa esse valor, acrescido de um segundo, como startDateTime para a próxima chamada. 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 não sobreposta de dados em todos os intervalos de tempo e pode ser agendada por meio do cron ou de outro recurso de agendamento de tarefas.