Video Central

Descripción general de la API de Datasets

La API de Datasets forma parte de nuestro nuevo producto de datos para socios, Slate Analytics. A diferencia de otros informes de Slate, los conjuntos de datos son de solo adición (cada archivo contiene datos nuevos), no están disponibles para su descarga en la interfaz de usuario de Slate (son accesibles únicamente a través de la API) y están desarrollados específicamente para que los ingenieros de datos de los socios consuman datos granulares y realicen análisis. Este tema ayuda a los ingenieros de datos a configurar sus procesos de datos (canalizaciones) para obtener conjuntos de datos, define los valores en los archivos de los conjuntos de datos y proporciona consultas de ejemplo y sugerencias sobre las formas óptimas en que los socios pueden utilizar esta información.

Uso práctico de los conjuntos de datos

Proporcionamos los conjuntos de datos a los consumidores en forma de un registro de cambios. Cada evento se publica una sola vez. Sin embargo, si es necesario actualizar cualquier valor de las columnas para una fila proporcionada anteriormente, publicaremos una nueva versión del registro para reflejar los cambios en el próximo archivo disponible. El registro de cambios es de solo adición para garantizar que se capturen todas las modificaciones de los datos. Los ingenieros de datos pueden utilizar este registro de cambios para actualizar sus tablas de datos directamente.

Al procesar el registro de cambios, es fundamental utilizar siempre el último registro para un event_id determinado, basándose en la columna last_update_time_utc. Esto garantiza que siempre tengas la versión más actualizada de cada registro. Si es necesario eliminar un registro, esta acción se refleja en la columna is_deleted. Un valor de 1 indica que el registro ha sido eliminado, mientras que un valor de 0 representa un registro activo. Este enfoque de registro de cambios te permite gestionar eficazmente los datos nuevos y cambiantes, y garantiza que tus tablas de datos permanezcan precisas y actualizadas con la información más reciente.

Requisitos previos de la API de Datasets

Antes de realizar solicitudes a la API de Datasets, es importante comprender los requisitos básicos de autenticación y paginación. Esta sección explica cómo acceder a la API de forma segura y cómo navegar por grandes conjuntos de datos de manera eficiente.

Integración a la API de Analytics
Para obtener conjuntos de datos, primero debes realizar el proceso de integración a la suite de la API de Analytics. Puedes encontrar más detalles aquí.

La URI base es: https://videocentral.amazon.com/apis/v2. Todas las solicitudes deben incluir un token de autenticación de LWA válido en el encabezado de autorización de la solicitud. Por ejemplo:

Si el encabezado de la solicitud no incluye el token, o si el token ha expirado, la API de Datasets devolverá una excepción de falta de autorización.

Paginación
Todas las respuestas de la API de Slate están paginadas. Los parámetros de paginación se especifican a través de los parámetros de la solicitud.

Parámetro de solicitud	Valor predeterminado	Descripción
limit	10	El número de documentos devueltos en una sola página (el tamaño de la página).
offset	0	El número de páginas que se deben omitir (el número de página).

Todas las respuestas paginadas contienen los siguientes campos.

Campo	Descripción
total	El recuento total de documentos de todas las páginas.
next	La dirección URL de la página siguiente. Es un valor nulo si es la última página.

Uso de la API de Datasets

Para acceder a los conjuntos de datos de forma programática, los clientes deben seguir una serie de llamadas a la API que enumeran los recursos disponibles, como cuentas, grupos, empresas y conjuntos de datos, antes de obtener las URL de descarga de los archivos de datos. Esta secuencia está diseñada para admitir la automatización y puede integrarse en flujos de trabajo programados o en procesos de datos recurrentes.

Listar cuentas
/v2/accounts

Este recurso devuelve la lista de cuentas de Slate a las que el usuario puede acceder. El conjunto de cuentas es accesible en Slate a través de la lista desplegable de cuentas situada cerca de la esquina superior derecha del portal. También puedes utilizar estos enlaces para encontrar tu account_id o tu channel/studio_id.

Ejemplo de solicitud

Ejemplo de respuesta

Listar grupos (líneas de negocio)
/v2/accounts/{account_id}

Este recurso devuelve los grupos de líneas de negocio (como canales) a los que el usuario puede acceder.

Ejemplo de solicitud

Ejemplo de respuesta

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

Este recurso devuelve una lista de empresas (como nombres de canales específicos) disponibles para esta cuenta, según la línea de negocio proporcionada.

Ejemplo de solicitud

Ejemplo de respuesta

Listar conjuntos de datos disponibles
/v2/accounts/{acccount_id}/{group_id}/{business_id}/datasets

Este recurso devuelve la lista de conjuntos de datos disponibles para un canal o estudio determinado. (La lista de los conjuntos de datos disponibles y sus atributos se incluyen en la sección Definiciones de conjuntos de datos, más adelante en este tema). Los conjuntos de datos disponibles actualmente para descargar son:

Suscripción: Eventos en el ciclo de vida del cliente, como el momento en que un cliente se suscribió.
Reproducción: Eventos de sesiones de reproducción en los que los clientes interactuaron con el contenido.
Catálogo: Eventos en los que los metadatos de su catálogo han cambiado, como cuando se agregó un nuevo título.

Ejemplo de solicitud

Ejemplo de respuesta

Obtener archivos del conjunto de datos
/v2/accounts/{account_id}/{group_id}/{business_id}/datasets{dataset_id}

Este recurso proporciona una lista de archivos del conjunto de datos. Dependiendo del rango de tiempo solicitado, la lista puede incluir una gran cantidad de archivos. El campo total indica cuántos archivos se pueden esperar. Después de completar un proceso de carga histórica completo, puedes mantenerte actualizado solicitando archivos continuamente mediante un startDateTime igual a la última marca de tiempo obtenida y un endDateTime configurado con la hora actual.

Los nuevos conjuntos de datos se publican aproximadamente cada 4 horas y pueden contener eventos que ocurrieron en las últimas 12 horas. Recomendamos llamar a nuestra API varias veces al día, aproximadamente cada 4 a 6 horas, para garantizar que tus datos locales estén lo más completos y actualizados posible. Si experimentamos un retraso en la publicación, lo comunicaremos por correo electrónico lo antes posible.

La siguiente tabla describe los parámetros de solicitud disponibles para los archivos del conjunto de datos.

Parámetro de solicitud	Descripción
startDateTime	Se recomienda establecerlo a partir de la última vez que se extrajeron los datos. (Formato: YYYY-MM-DDTHH:MM:SSZ - marca de tiempo UTC)
endDateTime	Se recomienda establecerlo en el momento de la extracción o la hora actual. (Formato: YYYY-MM-DDTHH:MM:SSZ - marca de tiempo UTC)
limit	El límite máximo es de 1000 enlaces por página.

Nota: Nuestra retención máxima de datos es de 2 años. Las solicitudes de conjuntos de datos con una marca de tiempo anterior a hace 2 años no devolverán ningún resultado.

Ejemplo de solicitud

Ejemplo de respuesta

Notas:

El tamaño máximo del archivo zip es de 300 MB. Los archivos que superen ese límite se dividirán en varios archivos.
El tiempo de vida (TTL) de la URL prefirmada es de 60 minutos.

Definiciones de conjuntos de datos

Las tablas en esta sección enumeran las columnas, los tipos de datos y las definiciones de cada uno de los 3 conjuntos de datos disponibles.

Conjunto de datos de suscripción

Columna	Tipo	Definición
subscription_event_id (pk)	string	El ID único para cada evento de suscripción emitido a través de este registro.
subscription_event_type	string	El tipo de evento de suscripción que ocurrió: Start: El cliente se suscribió a un canal al que no estaba suscrito anteriormente. Renewal: El cliente se suscribió a un canal y ya estaba activo en ese canal antes del evento de suscripción. Cancel: El cliente canceló su suscripción. Suspend: La suscripción del cliente está temporalmente en pausa debido a problemas de pago (fondos insuficientes o información de facturación no válida). La suscripción se reanudará automáticamente y generará un evento de renovación cuando el cliente actualice su información de facturación y el pago se procese de forma correcta. Active - AR ON: El cliente está activo y ha activado la renovación automática. Active - AR OFF: El cliente está activo, pero ha desactivado la renovación automática.
subscription_event_time_utc	timestamp	La hora en que se produjo el evento de suscripción, estandarizada a UTC.
subscription_event_time_zone	string	La zona horaria del sitio web de la suscripción.
cid	string	Identificador de cliente anonimizado (CID). Este identificador de cliente persistirá para todos los eventos bajo un único canal principal para permitir el movimiento entre niveles y el seguimiento del ciclo de vida del cliente.
offer_id	string	El identificador de la oferta de la suscripción específica con la que se produjo el evento.
offer_name	string	El nombre legible de la oferta.
offer_type	string	El tipo de oferta.
offer_marketplace	string	El sitio web en el que estaba disponible la oferta de suscripción.
offer_billing_type	string	El tipo de pago requerido para la oferta: HO: Oferta de pago inmediato; se requiere pago. FT: Prueba gratis; no se requiere pago.
offer_payment_amount	string	El monto de facturación de offer_id.
benefit_id	string	El ID del beneficio de Prime Video bajo el cual está configurada la oferta.
channel_label	string	El nombre del canal en el que está la oferta. Nota: Si esta columna muestra un valor nulo y tiene alguna duda, ponte en contacto con tu CAM o PsM.
channel_tier_label	string	El nombre del canal en el que está la oferta. Nota: Si esta columna muestra un valor nulo y tiene alguna duda, ponte en contacto con tu CAM o PsM.
is_promo	int	Indica si una oferta tiene una promoción en el momento del evento (0 = sin promoción, 1 = con promoción).
create_time_utc	timestamp	La hora en que se creó el registro del registro de eventos de suscripción, estandarizada a UTC.
last_update_time_utc	timestamp	La hora en que se actualizó por última vez el registro del registro de eventos de suscripción, estandarizada a UTC.
is_deleted	int	Indica si un registro que se creó previamente se debe eliminar (0 = se debe conservar, 1 = se debe eliminar).

Conjunto de datos de reproducción

Columna	Tipo	Definición
session_id (pk)	string	El identificador único de la sesión de reproducción.
marketplace_id	int	El identificador único del sitio web de reproducción.
marketplace_desc	string	Una descripción amigable para el sitio web de reproducción.
cid	string	El identificador de usuario, anonimizado con UUID.
benefit_id	string	El beneficio relacionado con el contenido que se transmitió.
catalog_id	string	Clave externa (FK) utilizada para unirse a la tabla de catálogo.
subscription_offer_id	string	El offer_id de suscripción al que el cliente está suscrito en el momento de la transmisión (Active o ApprovalPending).
subscription_event_id	string	Clave externa (FK) para unirse al registro de eventos de suscripción para obtener el estado exacto del suscriptor en el momento de la reproducción (Active)
start_segment_utc	timestamp	Inicio del segmento de reproducción en UTC.
end_segment_utc	timestamp	Fin del segmento de reproducción en UTC.
seconds_viewed	int	Segundos que el usuario transmitió contenido durante la reproducción.
position_start	double	Segundo de la transmisión en el que se inició la sesión de reproducción.
position_end	double	Segundo de la transmisión en el que finalizó la sesión de reproducción.
connection_type	string	Conexión utilizada por el cliente para transmitir el contenido.
stream_type	string	Clasificación entre transmisiones de Video-On-Demand (VOD), Live (En vivo) o Just After Broadcast (JAB).
device_class	string	Tipo de dispositivo (como Living Room, Mobile, Web u Otros).
device_sub_class	string	Tipo de dispositivo específico (como consola de juegos, smart_tv, roku).
geo_dma	string	El Área de Mercado Designada (DMA) geográfica de 3 dígitos del área donde se generó la transmisión.
playback_method	string	Indica si la reproducción es Online u Offline.
quality	string	Calidad de reproducción (como 1080p o 4K)
event_type	string	El tipo de evento que define el registro (playback_segments).
create_time_utc	timestamp	Marca de tiempo de cuando el registro fue agregado a la tabla, en UTC.
last_update_time_utc	timestamp	Marca de tiempo de la última actualización cuando el registro fue modificado, en UTC.
is_deleted	int	Indicador para denotar a los socios si el registro debe eliminarse en su sistema.

Conjunto de datos de catálogo

Columna	Tipo	Definición
id (pk)	string	El identificador único del título.
marketplace_id	int	El identificador único del sitio web de la oferta.
benefit_id	string	El beneficio asociado con el contenido extendido.
title	string	El título de la serie o película.
vendor_sku	string	Un identificador arbitrario que el proveedor genera para cada una de sus películas o episodios.
season	integer	El número de temporada (para contenido en serie).
episode	integer	El número del episodio.
episode_name	string	El nombre del episodio (opcional).
runtime_minutes	integer	Duración del contenido visualizado.
live_linear_channel_name	string	El nombre del canal para el contenido en directo.
content_type	string	Ya sea TV o Película.
content_quality	string	HD o SD
content_group	string	3P_SUBS
create_time_utc	timestamp	Marca de tiempo de cuando el registro fue agregado a la tabla, en UTC.
last_update_time_utc	timestamp	Marca de tiempo de la última actualización cuando el registro fue modificado, en UTC.
is_deleted	int	Indicador para denotar a los socios si el registro debe eliminarse en su sistema.

Ejemplos de consultas

El siguiente ejemplo de SQL demuestra cómo se conectan las tablas del conjunto de datos. Puedes unir los datos de reproducción con el registro de eventos de suscripción mediante la columna subscription_event_id. Esto proporciona el estado de suscripción más reciente antes de esa reproducción. En este ejemplo, la columna catalog_id en el conjunto de datos de reproducción se une al campo id en catalog_event_log para proporcionar todos los metadatos del catálogo.

El siguiente ejemplo de SQL devolverá los 10 primeros títulos vistos por los clientes después de haber iniciado una suscripción.

Ejemplo de organización

Si deseas automatizar la extracción de datos desde la API de Datasets de forma recurrente, el siguiente script de ejemplo en Python demuestra cómo realizar llamadas incrementales a la API cada 6 horas. Este rastrea la marca de tiempo de la última solicitud exitosa almacenándola localmente y utiliza ese valor (más un segundo) como startDateTime para la siguiente llamada. El script calcula el endDateTime basándose en la hora actual, crea los parámetros de consulta adecuados y envía una solicitud GET con autenticación. Este enfoque garantiza una recuperación de datos continua y sin duplicados entre ventanas de tiempo, y puede programarse a través de cron u otro programador de tareas.