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 de parceiros, o Slate Analytics. Ao contrário de outros relatórios do Slate, os conjuntos de dados são somente anexados (cada arquivo tem novos dados), não estão disponíveis para download na interface do usuário do Slate (mas podem ser acessados somente pela API) e são criados explicitamente para que engenheiros de dados parceiros consumam dados granulares e realizem análises. Este tópico ajuda os engenheiros de dados a configurar seus pipelines para 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 pelas quais os parceiros podem usar esses dados.

Uso prático de conjuntos de dados
Fornecemos conjuntos
de dados aos consumidores na forma de um changelog. Cada evento é publicado apenas uma vez. No entanto, se algum valor de coluna de uma linha fornecida anteriormente precisar ser atualizado, publicaremos uma nova versão do registro para refletir as alterações em seu próximo arquivo disponível. O changelog é somente para anexar, para garantir que todas as modificações de dados sejam capturadas. Os engenheiros de dados podem usar esse changelog para atualizar suas tabelas de dados diretamente.

Ao processar o changelog, é essencial sempre usar o registro mais recente para 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. Um valor de 1 indica que o registro foi excluído, enquanto um valor de 0 representa um registro ativo. Essa abordagem de registro de alterações permite gerenciar com eficiência dados novos e alterados e garante que suas tabelas de dados permaneçam precisas e atualizadas com as informações mais recentes.

Preliminares da API de conjuntos de dados

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

Integração à API de conjuntos de dados
Para recuperar conjuntos de dados, você precisa primeiro integrar o conjunto de APIs de conjuntos de dados. Mais detalhes podem ser encontrados aqui.

O URI base é: https://videocentral.amazon.com/apis/v2. Todos os pedidos devem incluir um token de autenticação LWA válido no cabeçalho de autorização do pedido. 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 não autorizada.

Paginação Todas as respostas da
API 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	Description
limite	10	O número de documentos retornados em uma única página (o tamanho da página).
compensação	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	Description
total	A contagem total de documentos em todas as páginas.
próximo	O URL para a próxima página. Nulo se for a última página.

Use a API de conjuntos de dados

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

Listar contas
/v2/accounts

Esse 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 seu channel/studio_id.

Exemplo de solicitação

Exemplo de resposta

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

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

Exemplo de solicitação

Exemplo de resposta

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

Esse recurso retorna uma lista de empresas (como nomes de canais específicos) disponíveis para essa conta, dependendo da linha de negócios em questão.

Exemplo de solicitação

Exemplo de resposta

Listar conjuntos de dados disponíveis

/v2/accounts/ {acccount_id}/{group_id}/{business_id}
/datasets Esse 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 livro foi adicionado.

Exemplo de solicitação

Exemplo de resposta

Obtenha o (s) arquivo (s) do conjunto de dados
/v2/accounts/ {account_id}/{group_id}/{business_id} /datasets/ {dataset_id} Esse recurso fornece uma lista dos arquivos do conjunto de dados.

Dependendo do intervalo de tempo solicitado, a lista pode incluir um grande número de arquivos. O campo total indica quantos arquivos esperar. Depois de concluir um preenchimento completo, você pode se manter atualizado continuando a solicitar arquivos usando um startDateTime igual ao último timestamp recuperado e um endDateTime definido com a hora atual.

Novos conjuntos de dados são publicados aproximadamente a cada 4 horas e podem conter eventos que ocorreram nas 12 horas anteriores. Recomendamos chamar nossa API várias vezes por dia, aproximadamente a cada 4-6 horas, para garantir que seus dados locais estejam o mais completos e atualizados possível. Se houver um atraso na publicação, nos 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	Description
Data e hora de início	A recomendação é definir a partir da última vez que foi retirada. (Formato: YYYY-MM-DDTHH:MM:SSZ - data e hora UTC)
Data e hora de término	A recomendação é definir no momento da puxão/hora atual. (Formato: YYYY-MM-DDTHH:MM:SSZ - data e hora UTC)
limite	O limite máximo é de 1000 links por página.

Nota: Nossa retenção máxima de dados é de 2 anos. Solicitações de conjuntos de dados com um registro de data e hora anterior a dois anos não retornarão nenhum resultado.

Exemplo de solicitação

Exemplo de resposta

Notas:

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

Definições do conjunto de dados

As tabelas nesta 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	Type	Definição
ID do evento de assinatura (pk)	string	O ID exclusivo de cada evento de assinatura vendido por meio desse registro.
tipo de evento_de_assinatura	string	O tipo de evento de assinatura que ocorreu: Start: o cliente se inscreveu em um canal no 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. Cancelar: o cliente cancelou sua assinatura. Suspender: a assinatura do cliente está 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 quando o cliente atualizar suas informações de cobrança e o pagamento for processado com sucesso. Ativo - AR ATIVADO: o cliente está ativo e ativou a renovação automática. Ativo - AR OFF: o cliente está ativo, mas desativou a renovação automática.
horário_evento_de assinatura utc	carimbo de data/hora	A hora em que o evento de assinatura ocorreu, padronizada para UTC.
fuso horário do evento de assinatura	string	O fuso horário do mercado de assinaturas.
ácido	string	Identificador de cliente anônimo (CID). Esse identificador de cliente persistirá em todos os eventos em um único canal principal para permitir a movimentação entre níveis e o rastreamento do ciclo de vida do cliente.
id_oferta	string	O ID da oferta de assinatura específica à qual o evento ocorreu.
nome_oferta	string	O nome legível da oferta.
tipo_oferta	string	O tipo de oferta.
oferta_marketplace	string	O mercado em que a oferta de assinatura estava ativa.
tipo_de_faturamento_oferta	string	O tipo de pagamento exigido para a oferta: HO: Oferta definitiva; pagamento obrigatório. FT: Teste gratuito; nenhum pagamento é necessário.
quantidade_pagamento_oferta	string	O valor do faturamento do offer_id.
id_benefício	string	O ID do benefício do Prime Video em que a oferta está configurada.
rótulo_canal	string	O nome do canal em que a oferta se encontra. Nota: 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 em que a oferta se encontra. Nota: Se esta coluna mostrar um valor nulo e você tiver dúvidas, entre em contato com seu CAM ou PsM.
é_promo	int	Indica se uma oferta está em uma promoção no momento do evento (0 = sem promoção, 1 = sim).
create_time_utc	carimbo de data/hora	A hora em que o registro do registro de eventos da assinatura foi criado, padronizado para UTC.
horário_da_última atualização utc	carimbo de data/hora	A hora em que o registro do registro de eventos da assinatura foi atualizado pela última vez, padronizado para UTC.
é_excluído	int	Indica se um registro que foi criado anteriormente deve ser excluído (0 = deve persistir, 1 = deve ser excluído).

Conjunto de dados de reprodução

Coluna	Type	Definição
ID da sessão (pk)	string	O ID exclusivo da sessão de reprodução.
ID do mercado	int	O ID exclusivo do mercado de reprodução.
marketplace_desc	string	Uma descrição amigável para o mercado de reprodução.
ácido	string	O identificador do usuário, anonimizado com UUID.
id_benefício	string	O benefício associado ao conteúdo que foi transmitido.
id_catálogo	string	Chave estrangeira (FK) usada para unir à tabela do catálogo.
id_da_oferta de assinatura	string	A assinatura offer_id do cliente está inscrito no momento da transmissão (Ativa ou ApprovalPending).
ID do evento de assinatura	string	Chave estrangeira (FK) para ingressar no registro de eventos da assinatura para obter o status exato do assinante no momento da reprodução (Ativo)
segmento_inicial_utc	carimbo de data/hora	Início do segmento de reprodução em UTC.
segmento_final utc	carimbo de data/hora	End do segmento de reprodução em UTC.
segundos_visualizados	int	Segundos em que o usuário transmitiu conteúdo durante a reprodução.
posição_início	duplo	Segundo da transmissão em que a sessão de reprodução começou.
posição_fim	duplo	Segundo da transmissão em que a sessão de reprodução terminou.
tipo_de_conexão	string	Conexão usada pelo cliente para transmitir o conteúdo.
tipo_de_fluxo	string	Classificação entre transmissões de vídeo sob demanda, ao vivo ou logo após a transmissão (JAB).
classe_dispositivo	string	Tipo de dispositivo (como sala de estar, celular, Web ou outros).
sub_classe do dispositivo	string	Tipo granular de dispositivo (como console de jogos, smart_tv, roku).
geo_dma	string	A Área de Mercado Designada (DMA) geográfica de 3 dígitos da área onde o fluxo foi gerado.
método_reprodução	string	Determina se a reprodução é online ou offline.
qualidade	string	Qualidade de reprodução (como 1080p ou 4K)
tipo_evento	string	O tipo de evento definidor (playback_segments)
create_time_utc	carimbo de data/hora	Carimbo de data e hora em que o registro foi adicionado à tabela, em UTC.
horário_da_última atualização utc	carimbo de data/hora	Data e hora da última atualização em que o registro foi modificado, em UTC.
é_excluído	int	Sinalize para indicar aos parceiros se o registro deve ser excluído em seu sistema.

Conjunto de dados do catálogo

Coluna	Type	Definição
identificação (pk)	string	O ID exclusivo do livro.
ID do mercado	int	O ID exclusivo do mercado de ofertas.
id_benefício	string	O benefício associado ao conteúdo estendido.
título	string	O título da série/filme.
SKU do fornecedor	string	Um identificador arbitrário que o fornecedor gera para cada um de seus filmes ou episódios.
temporada	inteiro	O número da temporada (para conteúdo episódico).
episódio	inteiro	O número do episódio.
nome_do_episódio	string	O nome do episódio (opcional).
minutos de tempo de execução	inteiro	O tempo de execução do conteúdo visualizado.
nome_do_canal_linear ao vivo	string	O nome do canal para conteúdo ao vivo.
tipo_conteúdo	string	Tanto na TV quanto no cinema.
qualidade_conteúdo	string	HD ou SD
grupo_conteúdo	string	3P_SUBS
create_time_utc	carimbo de data/hora	Carimbo de data e hora em que o registro foi adicionado à tabela, em UTC.
horário_da_última atualização utc	carimbo de data/hora	Data e hora da última atualização em que o registro foi modificado, em UTC.
é_excluído	int	Sinalize para indicar 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 juntar dados de reprodução ao registro de eventos da assinatura na coluna subscription_event_id. Isso fornece o status mais recente da assinatura antes dessa transmissão. 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 títulos mais assistidos pela primeira vez pelos clientes após terem iniciado uma assinatura.

Orquestração de amostras

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 de API a cada 6 horas. Ele rastreia a data e hora da última solicitação bem-sucedida persistindo-a localmente e usa esse valor, mais um segundo, como StartDateTime para a próxima chamada. O script calcula 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 todas as janelas de tempo e pode ser programada via cron ou outro agendador de tarefas.