soporte Contactar con Soporte | Estadoestado del sistema del sistema
Contenido de la página

    Resumen: Cotas, Campos y Parámetros

    Las dimensiones son las categorías de datos clave para Analytics API los informes de datos. En este tema se proporciona una guía interactiva sobre las dimensiones y los campos que se pueden devolver para ellas. También muestra qué dimensiones se pueden combinar en un informe y los campos disponibles para las diferentes combinaciones.

    Dimensiones y campos

    Las dimensiones son los depósitos de datos principales para el análisis. Para ver las guías completas de las dimensiones individuales, haga clic en el nombre de la dimensión en la lista siguiente.

     
     

    Seleccione las dimensiones a continuación para ver los campos que se pueden devolver para ella. También puede hacer clic en el botón Hacer una solicitud para realizar una solicitud de muestra y ver los resultados. Si selecciona varias dimensiones incompatibles, verá un mensaje en ese sentido.

    Entrada

    Seleccione las dimensiones sobre las que se debe informar:

     
     

    Campos a devolver:

     
     

    (utiliza una cuenta de Brightcove de ejemplo)

    Salida

    from Fecha más temprana para esta combinación de dimensiones:  

     

    Solicitud de API de ejemplo:

    Datos de respuesta

      Response will appear here...

    Notas

    1. Por defecto, video_view es el único campo devuelto - otros campos serán devueltos sólo si se especifican en el valor del fields parámetro.
    2. Si especifica un campo para devolver que no es compatible con la dimensión o la combinación de dimensiones, se devolverá un UNSUPPORTED_FIELD_COMBINATION_ERROR error.
    3. El bytes_delivered campo incluye todos los datos entregados por Video Cloud a los clientes, incluidos datos de vídeo, imágenes, pistas de texto y otros activos, así como el propio código del reproductor. Algunos de estos datos se obtienen de CDN y pueden no estar disponibles hasta 3 días.
    4. Además de los campos mostrados para la video dimensión, también puede devolver video.custom_fields.{field_name}

    Solicitud de ejemplo

    Un caso de uso típico para obtener un informe sobre varias dimensiones: desea un desglose de las vistas de vídeo entre dispositivos móviles y de escritorio, y también desea saber cuántas de las vistas de dispositivos móviles estaban en dispositivos iOS frente a dispositivos Android, y cuántas vistas de escritorio se encontraban en Mac frente a equipos Windows. Actualmente no hay un informe estándar en el módulo Studio Analytics que proporcione esta información, pero puede obtenerla a través de esta Analytics API llamada:

      https://analytics.api.brightcove.com/v1/data?accounts=57838016001&dimensions=video,device_type,device_os&from=2014-01-01&to=2014-04-01&fields=video_view

    (En este caso solicitamos visualizaciones de vídeo para el período comprendido entre el 1 de enero y el 1 de abril de 2014).

    Ejemplo de uso cURL

    Si desea probar la API usando cURL, aquí hay un par de notas:

    • Primero necesitará obtener un token de acceso
    • Dado que la URL de la solicitud siempre incluirá parámetros de URL, deberá incluirla entre comillas (simple o doble)

    Ejemplo

    Aquí hay un ejemplo de comando cURL:

      curl -s --header "Authorization: Bearer $ACCESS_TOKEN" \
      "https://analytics.api.brightcove.com/v1/data?accounts=$ACCOUNT_ID&dimensions=video&from=2017-04-04&limit=100"

    Si reemplaza $ACCESS_TOKEN con un token de acceso válido y $ACCOUNT_ID con su ID de cuenta, esta solicitud debería funcionar. Tenga en cuenta que puede usar esta aplicación de ejemplo para generar un token de acceso.

    Combinaciones de dimensiones admitidas

    Para una referencia rápida, la tabla siguiente muestra combinaciones de cotas compatibles o no. Tenga en cuenta que hay algunos casos en los que se pueden usar más de dos dimensiones. Puede averiguarlos utilizando la herramienta Dimensiones y campos de arriba.

    Combinaciones de dimensiones admitidas
      cuenta tipo_explorador ciudad país fecha fecha_hora dominio_destino ruta_destino dispositivo_os device_fabricante tipo_dispositivo live_stream jugador dominio referrer_ región términos de búsqueda plataforma social_web tipo_origen video
    account n/a Sí Sí Sí Sí Sí Sí Sí Sí Sí Sí   Sí Sí Sí Sí   Sí Sí
    browser_type Sí n/a     Sí Sí                          
    city Sí   n/a Sí Sí Sí                 Sí        
    country Sí   Sí n/a Sí Sí     Sí   Sí   Sí           Sí
    date Sí Sí Sí Sí n/a   Sí Sí Sí Sí Sí Sí Sí Sí Sí Sí Sí Sí Sí
    date_hour Sí Sí Sí Sí   n/a Sí Sí Sí Sí Sí Sí Sí Sí Sí Sí Sí Sí Sí
    destination_domain Sí       Sí Sí n/a           Sí           Sí
    destination_path Sí       Sí Sí   n/a                      
    device_os Sí     Sí Sí Sí     n/a       Sí   Sí       Sí
    device_manufacturer Sí       Sí Sí       n/a                  
    device_type Sí     Sí Sí Sí         n/a   Sí   Sí       Sí
    live_stream         Sí Sí           n/a              
    player Sí     Sí Sí Sí Sí   Sí   Sí   n/a Sí       Sí Sí
    referrer_domain Sí       Sí Sí             Sí n/a   Sí   Sí Sí
    region Sí   Sí Sí Sí Sí     Sí   Sí       n/a        
    search_terms Sí       Sí Sí               Sí   n/a   Sí  
    social_platform         Sí Sí                     n/a   Sí
    source_type Sí       Sí Sí             Sí Sí   Sí   n/a Sí
    video Sí     Sí Sí Sí Sí   Sí   Sí   Sí Sí     Sí Sí n/a

    Parámetros

    A continuación se muestra una tabla que resume los parámetros disponibles en Analytics API. El uso de los parámetros se discute con más detalle en las siguientes secciones.

    Parámetros Obligatorio Descripción Valores Predeterminado

    Cuentas

    Las cuentas de Video Cloud para las que desea un informe se especifican mediante el accounts parámetro. Por ejemplo:

      https://analytics.api.brightcove.com/v1/data?accounts={account1_id,account2_id}

    Donde filtros

    La sintaxis general de los filtros es:

    where=dimension1==value1;dimension2==value2

    Por ejemplo:

    https://analytics.api.brightcove.com/v1?accounts=account_id(s)&dimensions=device_type&where=video==video_id;device_type==tablet

    Las comas se tratan como ORs lógicas, y los puntos y coma como AND lógicos. Por ejemplo, where=video==1234,5678;player==9876 se interpreta como «donde video = 1234 O 5678 AND player = 9876"

    Espacios y caracteres especiales

    Los valores de cadena deben estar codificados en URI. También puedes escapar de caracteres especiales usando un «»:

    where=search_terms==boston,%20ma

    Puede utilizar cualquier dimensión como filtro, pero sólo si esa dimensión también está incluida en el dimensions que está solicitando.

    Filtrado por propiedades de vídeo

    Con el where=video.q=={property}:{value} filtro especial, puede limitar el informe a un conjunto específico de vídeos en función de una variedad de propiedades, entre las que se incluyen:

    • Etiquetas
    • reference_id
    • custom_fields [1]
    • {a_specific_custom_field}
    • created_at

    Notas

    [ 1] La sintaxis básica es where=video.q==custom_fields:value (coincide con el valor de cualquier campo personalizado) o where=video.q==myfield:value (coincide con el valor del campo personalizado específico myfield). Si está buscando en campos personalizados específicos, tenga en cuenta que debe buscar en el Nombre interno, no en el Nombre para mostrar:

    Nombre interno frente a nombre para mostrar
    Nombre interno frente a nombre para mostrar

    Una comprobación rápida de si está utilizando el nombre correcto: el nombre interno estará en minúsculas y no contendrá espacios.

    Ejemplos

    Aquí hay algunos where filtros de ejemplo para buscar etiquetas y campos personalizados:

    Etiqueta única
    where=video.q==tags:foo
    Múltiples etiquetas:
    where=video.q==tags:foo,bar
    Campos personalizados
    where=video.q==custom_fields:foo
    Etiquetas y campos personalizados
    where=video.q==tags:foo,bar+custom_fields:fish

    Para obtener una explicación completa de esta sintaxis de consulta, consulte Using the CMS API: Buscar vídeos.

    Resumen de filtros y valores permitidos

    En la tabla siguiente se muestran los valores permitidos para cada dimensión utilizada como filtro:

    Filtro de dimensión Valores permitidos

    Rango de fechas

    Los intervalos de fechas, especificados en from y to parámetros para todos los tipos de informes, se pueden indicar en diferentes formatos:

    • Valores de texto:
      • to=now ( disponible y el valor predeterminado para todas las solicitudes)
    • Valores de tiempo de época en milisegundos, como 1377047323000
    • Fechas expresadas en formato de fecha internacional estándar ISO 8601: YYYY-MM-DDformato, como 2013-09-12. Para las fechas expresadas en este formato:
      • Cualquier intervalo de fechas especificado se interpretará en la zona horaria establecida para la cuenta
      • La hora para la fecha de entrega se interpretará como medianoche ( 00:00:00) en la fecha especificada en la zona horaria establecida para la cuenta
    • Fechas relativas: puede expresar cualquiera de las to y from valores relativos al otro en d (días) oh (horas). Por ejemplo:
      • from=2015-01-01&to=31d
      • from=-48h&to=now
      • from=-2d&to=now ( dará los mismos resultados que el ejemplo anterior)
      • from=-365d&to=2014-12-31

      Tenga en cuenta que los números negativos (-2d) se interpretan como «antes» (el otro valor) y los números positivos (48h) se tratan como «de» (el otro valor)

    Para generar un informe sobre alguna dimensión como «video» para un solo día, establezca los valores a y desde a esa fecha:

    ...&dimensions=video&from=2013-11-01&to=2013-11-01

    Límite y desfase

    El limit es el número de elementos a devolver (predeterminado: 10). Para devolver todos los artículos, utilice limit=all. offset es el número de elementos a omitir (predeterminado: 0). Puedes usar y juntos para crear una aplicación que pagina a través de los resultados.limitoffset

    Datos reconciliados

    El reconciled parámetro es booleano. Si se establece en true, los resultados se limitarán a los datos conciliados. Si false, los resultados se limitarán a datos en tiempo real (no reconciliados por hora).

    Informes geográficos

    Dimensiones para el análisis geográfico

    • country - Como el código de país ISO-3611-1. por ejemplo: 'NOSOTROS'
    • region - Como el código de región ISO-3611-2. Por ejemplo: 'US-WA'
    • city - Nombre de la ciudad. por ejemplo: Seattle

    Nota: Para países o regiones desconocidos, la API devuelve «ZZ» como código (según ISO-3611-alpha2).

    Campos y ordenación

    Utilice el fields parámetro para especificar los campos que desea devolver. De forma predeterminada, video_view se devuelve y se devuelve el campo correspondiente a la dimensión sobre la que está informando (por ejemplo destination_domain ). Consulte las dimensiones y los campos para obtener más detalles.

    Utilice el sort parámetro para especificar qué campo de métrica se utiliza para ordenar los elementos devueltos; por ejemplo: sort=video_view. Puede invertir el orden de ordenación negando el campo de ordenación: sort= -video_view

    Campos calculados

    Puede agregar campos calculados a sus solicitudes de API utilizando la sintaxis:

    fields=calulated_field_name:expression

    Puede utilizar campos calculados para crear sus propios campos personalizados a partir de métricas existentes o para cambiar el nombre de un campo existente.

    El nombre del campo calculado puede ser cualquier cadena compatible con URI. La expresión puede incluir nombres de campo regulares y los siguientes operadores aritméticos:

    • + ( adición)
    • - ( resta)
    • * ( multiplicación)
    • / ( división)
    • ^ ( exponente)
    • () ( paréntesis)

    Ejemplos

    fields=avg_seconds_viewed:video_seconds_viewed/video_view,video.name
    fields=avg_incomplete_ads:(ad_mode_begin-ad_mode_complete)/video_view,video.name
    fields=Video%20Views:video_view,video.name

    Solicitud de muestra

    Respuesta de muestra (a la solicitud anterior)

    {
      "item_count": 110,
      "items": [
        {
          "avg_seconds_viewed": 2152.2519913106444,
          "video.name": "Flamingos",
          "video_seconds_viewed": 2972260,
          "video": "4825279519001",
          "video_view": 1381
        },
        {
          "avg_seconds_viewed": 14.016225448334756,
          "video.name": "Tiger",
          "video_seconds_viewed": 16413,
          "video": "4093643993001",
          "video_view": 1171
        },
        {
          "avg_seconds_viewed": 12.06,
          "video.name": "Zebra",
          "video_seconds_viewed": 9045,
          "video": "3851389913001",
          "video_view": 750
        },
        {
          "avg_seconds_viewed": 23.343065693430656,
          "video.name": "Sea-SeaTurtle",
          "video_seconds_viewed": 15990,
          "video": "1754276205001",
          "video_view": 685
        }
      ],
      "summary": {
        "avg_seconds_viewed": 274.27374399301004,
        "video_seconds_viewed": 3139063,
        "video_view": 11445
      }
    }

    Última actualización de la página el 29-09-2020