Introducción
La Analytics API le permite obtener datos analíticos para sus cuentas de Video Cloud directamente. También puede ver los informes de análisis integrados en el módulo de análisis de Video Cloud Studio. El acceso a los datos mediante programación le brinda flexibilidad adicional.
También vea el Referencia de API.
Usos típicos
A continuación, se muestran algunos usos típicos de la API:
- Crear gráficos y pantallas personalizados
- Trabajar con varias API juntas, por ejemplo, obtener datos de video usando el CMS API para los videos con más vistas durante la semana anterior
- Combinando sus datos analíticos de video con otros datos analíticos del sitio
- Para algunas soluciones de muestra, consulte
URL base
La URL base para el Analytics API es:
<code class = "language-http translate =" No "> https://analytics.api.brightcove.com/v1
Encabezados
Autenticacion requerida)
La Analytics API usa el Brightcove Servicio OAuth para autenticar llamadas.
Primero deberá obtener las credenciales del cliente (un client_id y client_secret). Ésta es una operación única que se puede realizar utilizando el Interfaz de usuario de credenciales de OAuth. Puede obtener credenciales de cliente directamente desde el servicio OAuth de Brightcove mediante CURL , Postman , o Insomnia.
Necesita permisos de lectura de análisis y lectura de video para las credenciales de cliente:
Si está creando sus credenciales directamente a través de la API de OAuth, los permisos necesarios son:
[
"video-cloud/analytics/read"
"video-cloud/video/read"
]
También necesitarás un access_token, que se obtiene utilizando el client_id y client_secret y se pasa un encabezado de autorización con tu solicitud de API:
Authorization: Bearer {access_token}
La access_token caduca después de cinco minutos, por lo que debe obtener uno para cada solicitud, o verificar para asegurarse de que su token aún sea válido. Ver Obtener tokens de acceso para obtener una explicación detallada de cómo obtener tokens de acceso, incluidos ejemplos de código.
Accept-Encoding: gzip (optional)
Pasar este encabezado hará que la respuesta se devuelva en forma comprimida. Esto puede mejorar el rendimiento de informes grandes.
Almacenamiento en caché
Por motivos de rendimiento, las respuestas de la API se almacenan en caché durante aproximadamente 5 minutos, aunque la cantidad exacta de tiempo puede variar según varios factores. Para cualquier Analytics API consulta, puede obtener información sobre la caché de los encabezados de respuesta:
La Cache-Control le indica el tiempo máximo durante el que se almacenarán en caché los resultados en segundos (en el ejemplo anterior, 24 segundos). La Last-Modified y Expires los encabezados le indican cuándo se creó la caché actual y cuándo caducará.
En la mayoría de los casos, esto probablemente no sea un problema, pero si la actualización de los datos analíticos es de importancia crítica, debe saber que cuanto más tiempo se ejecuta una consulta, más tiempo se almacenará en caché, y los informes solo obtienen datos en tiempo real (no conciliados por hora). no se almacenarán en caché mientras los que obtengan datos conciliados (solo o además de los datos en tiempo real). Encontrar un explicación completa de datos conciliados y en tiempo real Si te gusta; la versión corta es que el Analytics API se basa en dos depósitos de datos:
- datos no conciliados en tiempo real o por horas, que se ponen a disposición de inmediato y se almacenan durante 32 días
- datos conciliados, que se almacenan permanentemente; Los datos en tiempo real se concilian para mejorar la precisión y se almacenan en el repositorio de datos conciliados cada 24 horas.
Puede limitar los resultados a datos conciliados o en tiempo real utilizando el reconciliado parámetro.
Para minimizar el almacenamiento en caché:
- Utilizar el
reconciled=falseparámetro para limitar los resultados a datos en tiempo real - Utilice un pequeño rango de fechas y asegúrese de que todo el rango se encuentre dentro de los últimos 32 días
Tiempos de espera
La API de Analytics solicita un tiempo de espera después de 8 minutos si no se completa. Si ve tiempos de espera de menos de 8 minutos, entonces la causa es un límite del lado del cliente.
Cantidad máxima de artículos que puede devolver
El número máximo de artículos que se pueden devolver es un millón. En la mayoría de los casos, es poco probable que alcance el límite, pero si solicita informes sobre el date dimensión durante un gran lapso de tiempo, por ejemplo, es posible. Si alcanza el límite de un millón de artículos, deberá modificar la solicitud para reducir la cantidad de artículos devueltos. Generalmente, la forma más sencilla de hacer esto será reducir el rango de datos (usando el from y to parámetros discutidos más adelante).
Solicitudes concurrentes
Una sola cuenta está limitada a una solicitud a la vez. Se ejecutarán varias solicitudes simultáneas en serie.
Por ejemplo:
- Inicie una solicitud de API "A".
- Inicie la solicitud de API "B" para la misma cuenta.
- La solicitud "B" no se completará hasta que se complete "A".
- Si la solicitud "A" tarda demasiado, la solicitud "A" recibirá un error que dice "su solicitud está pendiente; inténtelo de nuevo".
- Si la solicitud "A" tarda demasiado, es posible que la solicitud "B" reciba el mismo error. Tenga en cuenta que la solicitud "B" obtendrá un error si el tiempo para completar A + B es mayor que nuestro valor de tiempo de espera.
Si realiza varias solicitudes simultáneas, se procesarán una a la vez, en el orden en que se reciban.
Las solicitudes que regresan con un "error pendiente" eventualmente se completarán y se guardarán en nuestra caché. Esto significa que las solicitudes futuras de los mismos datos regresarán casi instantáneamente, pero solo si la solicitud se realiza antes de que expire la caché de cinco minutos.
Sus sistemas deben manejar el error pendiente esperando de 2 a 4 minutos y haciendo la misma solicitud nuevamente.
Mejores prácticas
Tipos de solicitud
La Analytics API acepta tres tipos de solicitud
- Datos (también llamado informe)
- Un informe sobre uno o más dimensions. El punto final de una solicitud de informe es:
https://analytics.api.brightcove.com/v1/data?accounts={account_id(s)}&dimensions={dimensions} - Informe de participación
- Datos de participación detallados que están disponibles para períodos dentro de los últimos 32 días. Ver la sección de compromiso para más detalles.
- Punto final de información de video
- Una pieza específica de datos analíticos servida con una latencia mínima. Ver Punto final de datos de video para más información.
Donde filtros y rangos de fechas se puede aplicar a los informes. Las solicitudes de informes pueden tener parámetros adicionales detallados en este documento.
Dimensiones y campos
La información detallada sobre dimensiones y campos ahora se encuentra en un documento separado: Descripción general de dimensiones, campos y parámetros.
Parámetros
La información detallada sobre los parámetros ahora se encuentra en un documento separado: Descripción general de dimensiones, campos y parámetros.
Informes de participación
Los informes detallados de participación que muestran las vistas de cada centésima parte de los videos (o los promedios de todos los videos de una cuenta o jugador) están disponibles para períodos dentro de los últimos 32 días. (Las solicitudes de rangos de fechas fuera de los últimos 32 días devolverán un error).
Participación de la cuenta
Para obtener valores promedio de participación en los videos vistos, use el punto final:
https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id
Compromiso del jugador
Para obtener valores promedio de todos los videos vistos en un reproductor, use el punto final:
https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/players/:player_id
Participación de video
Para obtener datos de participación para un video específico, use el punto final:
https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/videos/:video_id
Análisis en vivo
La Analytics API proporciona dos puntos finales para recuperar análisis para transmisiones en vivo de Brightcove, ya sea por una serie de tiempo o por evento. Ver el Analytics API Reference para detalles.