Video Central

Descripción general de la API de conjuntos de datos

La API de conjuntos de datos forma parte de nuestro nuevo producto de datos para socios, Slate Analytics. A diferencia de otros informes de Slate, los conjuntos de datos solo se pueden adjuntar (cada archivo contiene datos nuevos), no se pueden descargar en la interfaz de usuario de Slate (solo se puede acceder a ellos a través de la API) y se han creado de forma explícita para que los ingenieros de datos asociados puedan consumir datos detallados y realizar análisis. Este tema ayuda a los ingenieros de datos a configurar sus procesos para recuperar el conjunto de datos, define los valores de los archivos del conjunto de datos y proporciona ejemplos de consultas y sugerencias sobre las formas óptimas en que los socios pueden utilizar estos datos.

Uso práctico de los conjuntos de datos

Proporcionamos conjuntos de datos a los consumidores en forma de registro de cambios. Cada evento se publica solo una vez. Sin embargo, si es necesario actualizar los valores de las columnas de 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 solo se puede adjuntar, para garantizar que se recopilen todas las modificaciones de los datos. Los ingenieros de datos pueden usar este registro de cambios para actualizar sus tablas de datos directamente.

Al procesar el registro de cambios, es fundamental utilizar siempre el registro más reciente de un event_id determinado, basado 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 se ha eliminado, mientras que un valor de 0 representa un registro activo. Este enfoque de registro de cambios le permite administrar de manera eficaz los datos nuevos y cambiantes, y garantiza que las tablas de datos permanezcan precisas y actualizadas con la información más reciente.

Preliminares de la API de conjuntos de datos

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

Incorporación a la API de conjuntos de datos
Para recuperar conjuntos de datos, primero debe incorporarse al conjunto de API de conjuntos de datos. Puede encontrar más detalles aquí.

El URI base es: https://videocentral.amazon.com/apis/v2. Todas las solicitudes deben incluir un token de autenticación 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 caducado, la API de conjuntos de datos devolverá una excepción no autorizada.

Paginación Todas
las respuestas de la API de Slate están paginadas. Los parámetros de paginación se especifican mediante los parámetros de las solicitudes.

Parámetro de solicitud	Valor predeterminado	Description
límite	10	El número de documentos devueltos en una sola página (el tamaño de la página).
desplazamiento	0	El número de páginas que se van a omitir (el número de página).

Todas las respuestas paginadas contienen los siguientes campos.

Campo	Description
total	El recuento total de documentos en todas las páginas.
siguiente	La URL de la página siguiente. Si es la última página, es nulo.

Utilice la API de conjuntos de datos

Para acceder a los conjuntos de datos mediante programación, 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 recuperar las URL descargables de los archivos de datos. Esta secuencia está diseñada para respaldar la automatización y se puede integrar en canalizaciones de datos recurrentes o flujos de trabajo programados.

Listar cuentas
/v2/accounts

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

Ejemplo de solicitud

Ejemplo de respuesta

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

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

Ejemplo de solicitud

Ejemplo de respuesta

Lista de empresas
/v2/accounts/ {account_id}/{group_id}

Este recurso devuelve una lista de empresas (como nombres de canales específicos) disponibles para esta cuenta, en función de la línea de negocio en cuestión.

Ejemplo de solicitud

Ejemplo de respuesta

Listar los 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 conjuntos de datos disponibles y sus atributos se incluyen en las definiciones de los conjuntos de datos, más adelante en este tema). Los conjuntos de datos actualmente disponibles para descargar son:

Suscripción: eventos del ciclo de vida del cliente, como el momento en que un cliente se suscribió.
Reproducción: reproduce los eventos de la sesión en los que los clientes interactuaron con el contenido.
Catálogo: eventos en los que los metadatos del catálogo han cambiado, por ejemplo, cuando se ha añadido un título nuevo.

Ejemplo de solicitud

Ejemplo de respuesta

Obtenga los archivos del conjunto de datos
/v2/accounts/ {account_id}/{group_id}/{business_id} /datasets/ {dataset_id} Este recurso proporciona una lista de los archivos del conjunto de datos.

Según el intervalo de tiempo solicitado, la lista puede incluir una gran cantidad de archivos. El campo total indica cuántos archivos se esperan. Tras rellenar todos los datos, puedes seguir solicitando archivos para mantenerte actualizado utilizando un StartDateTime igual a la última marca de tiempo recuperada y un EndDateTime establecido en la hora actual.

Los nuevos conjuntos de datos se publican aproximadamente cada 4 horas y pueden contener eventos que se hayan producido en las 12 horas anteriores. Te recomendamos que llames a nuestra API varias veces al día, aproximadamente cada 4 a 6 horas, para asegurarte de que tus datos locales estén lo más completos y actualizados posible. Si sufrimos algún retraso en la publicación, nos comunicaremos por correo electrónico lo antes posible.

En la siguiente tabla se describen los parámetros de solicitud disponibles para los archivos de conjuntos de datos.

Parámetro de solicitud	Description
Fecha y hora de inicio	La recomendación es establecer desde la última vez que se extrajo. (Formato: YYYY-MM-DDTHH:MM:SSZ - marca de tiempo UTC)
Fecha y hora de finalización	La recomendación es establecer la hora de extracción o la hora actual. (Formato: YYYY-MM-DDTHH:MM:SSZ - marca de tiempo UTC)
límite	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 fecha y hora anteriores a 2 años no arrojará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 de la URL prefirmada (TTL) es de 60 minutos.

definiciones de conjuntos de datos

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

Conjunto de datos de suscripciones

Columna	Type	Definición
subscription_event_id (pk)	cadena	El ID único de cada evento de suscripción que se vende a través de este registro.
tipo_evento_de_suscripción	cadena	El tipo de evento de suscripción que se produjo: Start: el cliente se suscribió a un canal al que no estaba suscrito anteriormente. Renovación: el cliente se suscribió a un canal y ya estaba activo en ese canal antes del evento de suscripción. Cancelar: el cliente canceló su suscripción. Suspender: la suscripción del cliente está suspendida temporalmente 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 una vez que el cliente actualice su información de facturación y el pago se procese correctamente. Activo: AR activado: el cliente está activo y ha activado la renovación automática. Activo: AR desactivado: el cliente está activo, pero ha desactivado la renovación automática.
suscripción_event_time_utc	marca de tiempo	Hora a la que se produjo el evento de suscripción, estandarizada en UTC.
suscription_event_time_zone	cadena	La zona horaria del mercado de suscripciones.
ácido	cadena	Identificador de cliente (CID) anonimizado. Este identificador de cliente se conservará para todos los eventos en un único canal principal para permitir el seguimiento de los movimientos entre niveles y el ciclo de vida del cliente.
id_oferta	cadena	El ID de la oferta de suscripción específica en relación con la que se produjo el evento.
nombre_oferta	cadena	El nombre legible para los humanos de la oferta.
tipo_oferta	cadena	El tipo de oferta.
oferta_mercado	cadena	El mercado en el que estaba disponible la oferta de suscripción.
tipo_de_facturación_oferta	cadena	El tipo de pago requerido para la oferta: HO: oferta dura; se requiere pago. FT: prueba gratuita; no es necesario realizar ningún pago.
oferta_importe de pago	cadena	El importe de facturación del offer_id.
id_beneficio	cadena	El ID de la prestación de Prime Video con la que se configura la oferta.
etiqueta_canal	cadena	El nombre del canal en el que se encuentra la oferta. Nota: Si esta columna muestra un valor nulo y tienes dudas, ponte en contacto con tu CAM o PSm.
channel_tier_label	cadena	El nombre del canal en el que se encuentra la oferta. Nota: Si esta columna muestra un valor nulo y tienes dudas, ponte en contacto con tu CAM o PSm.
is_promo	int	Indica si una oferta está incluida en una promoción en el momento del evento (0 = sin promoción, 1 = sí, promoción).
create_time_utc	marca de tiempo	Hora en que se creó el registro de eventos de la suscripción, estandarizada en UTC.
última actualización_hora_utc	marca de tiempo	Hora a la que se actualizó por última vez el registro de eventos de la suscripción, estandarizada en UTC.
está_eliminado	int	Indica si un registro que se creó anteriormente debe eliminarse (0 = debe persistir, 1 = debe eliminarse).

Conjunto de datos de reproducción

Columna	Type	Definición
session_id (pk)	cadena	El ID único de la sesión de reproducción.
marketplace_id	int	El ID único del mercado de reproducción.
marketplace_desc	cadena	Una descripción sencilla para el mercado de la reproducción.
ácido	cadena	El identificador de usuario, anonimizado con el UUID.
id_beneficio	cadena	El beneficio asociado al contenido que se transmitió.
id_catálogo	cadena	Clave externa (FK) utilizada para unirse a la tabla de catálogo.
id_oferta_suscripción	cadena	La suscripción offer_id a la que está suscrito el cliente en el momento de la transmisión (activa o pendiente de aprobación).
identificador del evento de suscripción	cadena	Clave externa (FK) para unirse al registro de eventos de suscripción y obtener el estado exacto del suscriptor en el momento de la reproducción (activa)
start_segment_utc	marca de tiempo	Start del segmento de reproducción en UTC.
segmento_final_utc	marca de tiempo	End del segmento de reproducción en UTC.
segundos_vistos	int	Segundos del contenido reproducido por el usuario durante la reproducción.
posición_inicio	doble	Segundo lugar de la transmisión en el que se inició la sesión de reproducción.
posición_fin	doble	Segundo lugar de la transmisión en el que finalizó la sesión de reproducción.
tipo_de_conexión	cadena	Conexión utilizada por el cliente para transmitir el contenido.
tipo_de_flujo	cadena	Clasificación entre transmisiones de vídeo bajo demanda, en directo o justo después de la emisión (JAB).
clase_dispositivo	cadena	Tipo de dispositivo (como sala de estar, móvil, web u otros).
subclase de dispositivo	cadena	Dispositivo de tipo granular (como consola de juegos, smart_tv, roku).
geo_dma	cadena	El área geográfica de mercado designada (DMA) de 3 dígitos del área donde se generó la transmisión.
método_reproducción	cadena	Indica si la reproducción es en línea o fuera de línea.
calidad	cadena	Calidad de reproducción (como 1080p o 4K)
tipo_evento	cadena	El tipo de evento definitorio (playback_segments)
create_time_utc	marca de tiempo	Marca de tiempo del momento en que se agregó el registro a la tabla, en UTC.
última actualización_hora_utc	marca de tiempo	Fecha y hora actualizadas por última vez cuando se modificó el registro, en UTC.
está_eliminado	int	Marcador para indicar a los socios si el registro debe eliminarse de su sistema.

Conjunto de datos de catálogo

Columna	Type	Definición
id (pk)	cadena	El ID único del título.
marketplace_id	int	El ID único del mercado de ofertas.
id_beneficio	cadena	Se amplió el beneficio asociado al contenido.
título	cadena	El título de la serie/película.
vendedor_sku	cadena	Un identificador arbitrario que el vendedor genera para cada una de sus películas o episodios.
temporada	entero	El número de la temporada (para contenido episódico).
episodio	entero	El número del episodio.
nombre_episodio	cadena	El nombre del episodio (opcional).
minutos_tiempo de ejecución	entero	El tiempo de ejecución del contenido visualizado.
live_linear_nombre_canal	cadena	El nombre del canal para el contenido en directo.
tipo_contenido	cadena	TV o película.
calidad_contenido	cadena	HD o SD
grupo_contenido	cadena	3P_SUBS
create_time_utc	marca de tiempo	Marca de tiempo del momento en que se agregó el registro a la tabla, en UTC.
última actualización_hora_utc	marca de tiempo	Fecha y hora actualizadas por última vez cuando se modificó el registro, en UTC.
está_eliminado	int	Marcador para indicar a los socios si el registro debe eliminarse de su sistema.

Ejemplos de consultas

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

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

Ejemplo de orquestación

Si desea automatizar la extracción de datos de la API de conjuntos de datos de forma periódica, en el siguiente ejemplo de secuencia de comandos de Python se muestra cómo realizar llamadas incrementales a la API cada 6 horas. Realiza un seguimiento de la marca de tiempo de la última solicitud correcta mediante su persistencia local y utiliza ese valor (más un segundo) como fecha inicial y hora para la siguiente llamada. El script calcula EndDateTime como 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 solapamientos en todas las ventanas temporales y se puede programar mediante cron u otro programador de tareas.