Panel y API de Video Insights

La API Video Insights de Vonage es una API GraphQL. Puedes usar el Video Insights Dashboard & API para obtener información sobre tus aplicaciones y sesiones de Vonage Video.

Video Insights Dashboard

Nota: Haga clic en aquí para obtener información sobre la retención de datos y la latencia.

El panel de control de Insights proporciona datos a nivel de aplicaciones. Para acceder a él, inicie sesión en su cuenta. Cuenta API de Video de VonageVe a la sección Análisis de video y luego selecciona una aplicación específica de Vonage Video.

API Insights, URL base y autenticación

La API Insights es una API GraphQL que le permite explorar los metadatos de sus sesiones a nivel de aplicaciones y sesiones. GraphQL es una alternativa al típico enfoque REST de acceso a datos a través de HTTP. Fue desarrollado por Facebook en 2012 y de código abierto en 2015. Echa un vistazo a Guía de iniciación a GraphQL para saber más.

La URL base de la API es:

Todas las solicitudes se realizan como HTTP POST.

Exploración del esquema de la API con GraphiQL

Navegar hasta https://tools.vonage.com/video/insights-api/ utilizando su navegador le lleva a la instancia Insights de GraphiQLuna herramienta que le permite explorar el esquema de la API GraphQL. Dado que la herramienta puede realizar solicitudes a la API, debes iniciar sesión para utilizarla.

Hay cinco ventanas en esta herramienta:

• En la esquina superior derecha de la herramienta, verá un icono Docs . Al hacer clic en él, se abre un panel que contiene la documentación del esquema. Cada campo y tipo de objeto de la documentación contiene una descripción. Haga clic en ella para explorar el esquema.
• En la parte izquierda de la página se encuentra Consulta panel. En este panel puede construir consultas para ejecutarlas contra la API. Al ir y venir entre el panel Docs y el panel Consulta le permite construir la consulta precisa que necesita sólo para la información que necesita. Al estar conectado, la autenticación para realizar consultas está garantizada.
• Por debajo del Consulta es el panel Variables de consulta panel. Aunque no es obligatorio, puede utilizarlo para especificar variables para su consulta. Por ejemplo, puede definir las siguientes variables en este panel:

{
    "APPLICATION_ID": "23456ab-12ab-1234-23bc-123456789abc",
    "START_TIME": "2025-01-01T08:00:00.000Z"
}

A continuación, en el panel Consulta, haga referencia a las variables declaradas:

query ($APPLICATION_ID: String!, $START_TIME: Date!) {
    application(applicationId: $APPLICATION_ID) {
      applicationData(
      start: $START_TIME,
      interval: AUTO,
      sdkType: [JS, IOS, ANDROID],
      groupBy: [SDK_TYPE]
          ) {
        resources {
          sdkType
          intervalStart
          intervalEnd
          usage {
            participantMinutes {
              from1To25Publishers
              from26To35Publishers
              from36PlusPublishers
            }
          }
        }
      }
    }
  }

• A la derecha del Consulta es el panel Respuesta panel. Al hacer clic en el botón Ejecutar de la herramienta, se ejecutará la consulta en el panel Consulta y el panel Respuesta muestra los resultados. Esta es la misma respuesta que obtendría si realizara la consulta mediante programación.
• Por último, haga clic en el botón Historia situado encima del panel de consulta para ver el historial de sus consultas recientes. Al hacer clic en uno de los elementos mostrados, se rellena el campo Consulta y el panel Variables de consulta con esos datos.

Obtención de los datos de las Applications

En applicationData del objeto de aplicación devuelve el campo ApplicationData que proporciona datos de informes agregados a nivel de aplicación.

Debe incluir un start fecha de la consulta. Este valor puede ser una cadena con formato ISO-8601 (como "2025-01-15T23:43:34.023Z") o un valor Int que represente una marca de tiempo de época. Los enteros de 10 dígitos o menos representan segundos de época. Los enteros de más de 10 dígitos representan milisegundos de época.

En ApplicationData incluye un objeto resources que es una matriz de Metric objetos. Tiene la opción de filtrar y agrupar los datos por tipo de SDK, versión del SDK, país, región, navegador o versión del navegador. Además, tiene la opción de cambiar el Interval en la que desea segmentar los datos (ya sea DAILY, WEEKLYo MONTHLY). Tenga en cuenta que si establece el Intervalsólo verá los intervalos de tiempo que contengan datos.

Nota: Los datos de Insights a nivel de aplicación suelen estar disponibles en 36 - 48 horas.

Nota: El filtrado por región, SDK y navegador no está disponible para los minutos de participante y archivo.

En Metric incluye información sobre el país, la región (estado de EE. UU., si corresponde), el tipo y la versión del SDK de Vonage Video, así como el navegador y la versión del navegador (si corresponde) para los resultados. El sitio Metric también incluye las siguientes propiedades:

• usage - Información sobre los minutos publicados en streaming, los minutos suscritos en streaming, el uso de archivo, el uso de difusión, el uso de SIP y el uso separado por niveles de editor
• quality - Información sobre la calidad del vídeo
• errors - Los porcentajes de fallos en la conexión a sesiones, la publicación y la suscripción

La siguiente consulta solicita resultados de ApplicationData que incluyen minutos de participantes para clientes que usan los SDK de Vonage Video JavaScript, Android e iOS:

{
  application(applicationId: "23456ab-12ab-1234-23bc-123456789abc") {
    applicationData(
      start: "2025-01-01T07:00:00.000Z",
      interval: MONTHLY,
      sdkType: [JS, ANDROID, IOS],
      groupBy: SDK_TYPE
    ) {
      resources {
        intervalStart,
        intervalEnd,
          usage {
            participantMinutes {
              from1To25Publishers
              from26To35Publishers
              from36PlusPublishers
          }
      }
    }
  }
}
}

Tenga en cuenta que al establecer el start a 0, buscará los resultados empezando por los registros más antiguos disponibles.

Obtención de datos de sesión (Advanced Insights)

Nota: Haga clic en aquí para obtener información sobre la retención de datos y la latencia.

En sessionData campo del application devuelve el objeto SessionData objeto. Este objeto incluye dos campos: sessions y sessionSummaries.

Información detallada de la sesión

En sessions devuelve un campo Sessions objeto. Introduzca los identificadores de sesión como sessionIds (una matriz de cadenas coincidentes). La dirección Sessions incluye un objeto resources que es una matriz de Session objetos. El sitio Session tiene las siguientes propiedades:

• mediaMode - El modo multimedia de la sesión. Se trata de "routed" para sesiones enrutadas a través del enrutador de medios de vídeo de Vonage o "relayed" para la transmisión directa entre pares.
• publisherMinutes - El número total de minutos transmitidos para todos los editores en la sesión. Tenga en cuenta que la inclusión de este campo ralentizará los resultados de la consulta.
• subscriberMinutes - Número total de minutos retransmitidos para todos los abonados de la sesión. Tenga en cuenta que la inclusión de este campo ralentizará los resultados de la consulta.
• participantMinutes - El número total de minutos separados por niveles de editor en todas las reuniones de la sesión.
• meetings - Una matriz de Meeting Una sesión de Vonage Video puede tener varios reuniones. Cuando el primer cliente se conecta a la sesión, comienza la primera reunión. La reunión finaliza cuando no hay conexiones en la sesión durante al menos 10 minutos. Cuando un cliente vuelve a conectarse, se inicia una nueva reunión. Cada objeto Reunión incluye las siguientes propiedades:
  • subscriberMinutes - El número total de minutos de abonado en la reunión.
  • publisherMinutes - Número total de minutos de publicación de la reunión.
  • participantMinutes - El número total de minutos separados por niveles de editor en la reunión.
  • connections - Una matriz de objetos Connection que define a cada cliente conectado a la sesión (durante la reunión). Las propiedades del objeto Connection incluyen información sobre el Client SDK de Vonage Video utilizado, el navegador utilizado (para clientes web), información sobre editores y suscriptores, y más.
  • publishers - Una matriz de objetos Publisher. Las propiedades del objeto Editor incluyen información sobre el flujo del editor, los suscriptores del flujo, las estadísticas del flujo, etc. (Las estadísticas del flujo se incluyen con el complemento Advanced Insights. Véase Obtener estadísticas de flujos.)
  • subscribers - Matriz de objetos Suscriptor, que proporciona detalles sobre cada suscriptor. Las propiedades del objeto Suscriptor incluyen información sobre el flujo de suscriptores, estadísticas de flujo y más. (Las estadísticas del flujo se incluyen con el complemento Advanced Insights. Véase Obtener estadísticas de flujos.)
  • createdAt y destroyedAt - Fechas de inicio y fin de la reunión.

Nota: Si todos los usuarios se desconectan de una reunión y se realiza una nueva conexión a la sesión en los 10 minutos siguientes, se creará una nueva reunión con el mismo ID de reunión que la primera. Sin embargo, si la nueva conexión se realiza después de 10 minutos, la nueva reunión obtendrá un ID de reunión único.

Ejemplo de consulta detallada de sesión

La siguiente consulta solicita algunos detalles del editor sobre dos sesiones de Vonage Video:

{
    application(applicationId: "23456ab-12ab-1234-23bc-123456789abc") {
      sessionData {
            sessions(sessionIds: [
                "1_MX4xMDB-fjE1Mzg4NzA0MjExNDd-VjRuSWhpn4",
                "2_MX4xMDB-fjE1Mzg4NzA0OTQzOTN-RFFxeXfcn4"
            ]) {
                resources {
                    sessionId
                    meetings {
                        totalCount
                        resources {
                            createdAt
                            publisherMinutes
                            destroyedAt
                            publishers {
                                resources {
                                    createdAt
                                    destroyedAt
                                    connectionId
                                    stream {
                                      streamId
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }    
}

Obtener estadísticas de flujos

Nota: Las estadísticas de los flujos están disponibles para Clientes de Advanced Insights sólo.

En resources del objeto MeetingPublishers es una matriz de objetos Publisher. Y el objeto Publisher incluye el objeto PublisherStreamStatsCollection. Este objeto es una colección de recursos, y su resources es una matriz de objetos PublisherStats. Cada PublisherStats incluye estadísticas de flujo para el editor tomadas periódicamente (cada 30 segundos) durante el transcurso del flujo del editor. Estas estadísticas incluyen datos sobre la latencia de audio y vídeo, la tasa de bits de audio y vídeo, la tasa de pérdida de paquetes de audio y vídeo, la resolución de vídeo, los códecs de audio y vídeo, y si el flujo incluía audio y vídeo en el momento de la instantánea de las estadísticas del flujo.

La siguiente consulta solicita las estadísticas periódicas de velocidad de bits de audio y video para editores en una sesión de Vonage Video:

{
  application(applicationId: "23456ab-12ab-1234-23bc-123456789abc") {
    sessionData {
      sessions(sessionIds: [
        "1_MX4xMDB-fjE1Mzg4NzA0MjExNDd-VjRuSWhpn4",
      ]) {
        resources {
          sessionId
          meetings {
            resources {
              createdAt
              publishers {
                resources {
                  createdAt
                  connectionId
                  stream {
                    streamId
                  }
                  streamStatsCollection {
                    resources {
                      createdAt
                      audioBitrateKbps
                      videoBitrateKbps
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Del mismo modo, el resources del objeto MeetingSubscribers es una matriz de objetos Subscriber, y cada uno de ellos incluye una colección de recursos SubscriberStreamStatsCollection, que incluye estadísticas de flujo similares para un suscriptor.

Información resumida de la sesión

Nota: El resumen de la sesión está disponible para Clientes de Advanced Insights sólo.

En sessionSummaries es una matriz de SessionSummary (uno por cada sesión que coincida con la consulta). El objeto SessionSummary incluye un resources que es una matriz de MeetingSummary objetos (uno por cada reunión de la sesión). El sitio MeetingSummary incluye información sobre el número de flujos, conexiones y abonados totales y concurrentes en la reunión.

Tanto el SessionSummary y MeetingSummary los objetos incluyen publisherMinutes, subscriberMinutesy participantMinutes propiedades. Informan del número total de minutos retransmitidos para todos los editores y abonados en la sesión o reunión. Incluido participantMinutes informa de las actas separadas por niveles de editor en la sesión o reunión. Tenga en cuenta que la inclusión de publisherMinutes, subscriberMinuteso participantMinutes en una consulta ralentizará los resultados.

La siguiente consulta solicita datos parciales SessionSummary resultados:

{
     application(applicationId: "23456ab-12ab-1234-23bc-123456789abc") {
         sessionData {
             sessionSummaries (
                 start: "2025-01-01T07:00:00.000Z",
             ) {
                 resources {
                     sessionId
                     meetings {
                         resources {
                             maxConcurrentStreams
                             maxConcurrentStreams
                             maxConcurrentSubscribers
                             totalStreams
                             totalConnections
                         }
                    }
                }
            }
        }
    }
}

Métricas de calidad SIP

La siguiente consulta sólo proporciona las estadísticas mínimas de calidad SIP:

project(projectId: 12345678) {
    sessionData {
      sessions(sessionIds: [
        "1_MX4xMDB-fjE1Mzg4NzA0MjExNDd-VjRuSWhpn4"
       ]) {
        resources {
          meetings {
            resources {
              connections {
                resources {
                  sipCalls(first: 1) {
                    resources {
                      sipCallStatsCollection {
                        totalCount
                        resources {
                          audioCodec
                          audioLatencyMs
                          videoCodec
                          videoLatencyMs
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }

Esta consulta proporciona información básica SIP sin estadísticas:

project(projectId: 12345678) {
    sessionData {
      sessions(sessionIds: [
        "1_MX4xMDB-fjE1Mzg4NzA0MjExNDd-VjRuSWhpn4"
       ]) {
        resources {
          meetings {
            resources {
              connections {
                resources {
                  sipCalls(first: 10) {
                    resources {
                      sipCallId
                      connectionId
                      conferenceId
                      createdAt
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }

Para recuperar las estadísticas completas de Calidad SIP, utilice la siguiente consulta:

 {
 project(projectId: 12345678) {
     sessionData {
       sessions(sessionIds: [
        "1_MX4xMDB-fjE1Mzg4NzA0MjExNDd-VjRuSWhpn4"
       ]) {
         resources {
           meetings {
             resources {
               connections {
                 resources {
                   sipCalls(first: 1) {
                     resources {
                       sipCallId
                       connectionId
                       conferenceId
                       createdAt
                       sipCallStatsCollection {
                         totalCount
                         resources {
                           audioCodec
                           audioLatencyMs
                           audioSentBitrateKbps
                           audioSentPacketLoss
                           videoCodec
                           videoLatencyMs
                           videoSentBitrateKbps
                           videoSentPacketLoss
                         }
                       }
                     }
                   }
                 }
               }
             }
           }
         }
       }
     }
   }

Realización de solicitudes POST a la API GraphQL de Video Insights

Todas las solicitudes GraphQL de Video Insights se realizan a https://tools.vonage.com/video/insights-api/graphql.

Fije el Content-Type encabezado a application/json.

Fije el Authorization encabezado a Bearer <JWT>donde se genera el JWT para tu aplicación de Vonage Video (utilizando su clave privada) como se describe en Autenticación de la Video API.

El cuerpo del POST contiene un objeto JSON con un único elemento query cuyo valor es la cadena GraphQL.

Ejemplo de solicitud cURL para obtener los minutos suscritos transmitidos:

Sustituir YOUR_VIDEO_JWT con un JWT válido generado para tu aplicación de video de Vonage (luego de habilitar las capacidades de video y firmar con la clave privada de la aplicación), APPLICATION_ID con el ID de esa aplicación (UUID), y START_DATE con un sello de tiempo ISO-8601 o un valor de época.

Objetos de respuesta

Los objetos de respuesta se adhieren al esquema GraphQL y tienen formato JSON, pero sólo incluyen los campos que especifique en sus solicitudes. La dirección curl dará como resultado un objeto de respuesta como el siguiente:

 {  
  "data":{  
    "application":{  
      "applicationData":{  
        "resources":[  
          {  
            "usage":{  
              "streamedSubscribedMinutes":3189
            }
          }
        ]
      }
    }
  }
}

La forma más fácil de ver una vista previa de lo que se puede esperar es añadiendo diferentes filtros, grupos y campos a la función Explorador Insights GraphiQLy observando la respuesta.

Paginación en las consultas

Tanto el applicationData() y sessionData() Las API aceptan opciones de paginación para todos los métodos que devuelven listas (arrays). Todos estos métodos implementan un ResourceCollection que contienen las siguientes propiedades opcionales:

• first (opcional) - El número de entradas que se devolverán por página. El límite es 10 para Reuniones y 1000 para el resto de colecciones de recursos. El número predeterminado de entradas devueltas es 10 para Reuniones y 50 para el resto de colecciones de recursos.

• endCursor (opcional) - El cursor de cadena utilizado para especificar la página actual (offset). Obtenga este valor de cursor de la pageInfo para cada lista devuelta. Si no se especifica una propiedad endCursor una consulta devolverá la primera página de resultados coincidentes (el inicio de la lista).

• En pageInfo (devuelto para cada lista) incluye las siguientes propiedades:

  • hasNextPage - Propiedad booleana que indica si hay más páginas disponibles.
  • endCursor - La cadena a pasar para obtener la página siguiente.

  Por ejemplo, la siguiente consulta devuelve información sobre la paginación junto con las 10 primeras coincidencias applicationData recursos:

{
  application(applicationId: "23456ab-12ab-1234-23bc-123456789abc") {
    applicationData(
      start: "2025-01-01T07:00:00.000Z",
      first: 10,
      interval: MONTHLY,

    ) {
      pageInfo {
        hasNextPage
        endCursor
      }
      resources {
          participantMinutes {
            from1To25Publishers
            from26To35Publishers
            from36PlusPublishers
        }
      }
    }
  }
}

La respuesta incluye información sobre la paginación:

{
  "data": {
    "application": {
      "applicationData": {
        "pageInfo": {
          "hasNextPage": true,
          "endCursor": "aW5zaWdodHMtcmVzb3VyY2U6MTA=="
        },
        "resources": [
          {
            "usage": {
               "participantMinutes": {
                  "from1To25Publishers": 22,
                  "from26To35Publishers": 20,
                  "from36PlusPublishers": 10,
            }
          },
                    ...

Utiliza el endCursor de esta respuesta ("aW5zaWdodHMtcmVzb3VyY2U6MTA==") como el endCursor entrada utilizada en la consulta para obtener la siguiente página de registros coincidentes:

{
  application(applicationId: "23456ab-12ab-1234-23bc-123456789abc") {
    applicationData(
      start: 0,
      first: 10,
      interval: MONTHLY,
      endCursor: "aW5zaWdodHMtcmVzb3VyY2U6MTA=="

    ) {
      pageInfo {
        hasNextPage
        endCursor
      }
      resources {
        usage {
          participantMinutes {
            from1To25Publishers
            from26To35Publishers
            from36PlusPublishers
        }
      }
    }
  }
}

Retención de datos y latencia

Información / Panel de información

Conservación de datos:

• Agregación diaria: 90 días
• Agregación mensual: 12 meses

Notas:

• Los datos agregados diarios se calculan sobre la base de 00:00 - 23:59 PST/PDT.
• El periodo de retención de agregación diaria para Insights API e Insights Dashboard se actualizó a 90 días (de 60 días) a partir del 12 de agosto de 2021. Los datos diarios agregados de las sesiones de vídeo posteriores a esta fecha estarán disponibles durante 90 días.

Latencia prevista: 36 - 48 horas

Información avanzada

Conservación de datos: 21 días

Nota: El periodo de conservación se basa en la hora de creación de una reunión dentro de la sesión.

Latencia prevista: 5 minutos

Códigos de error

Los errores se incluyen en la respuesta, en un formato errors como la siguiente:

"errors": [
  {
    "message": "You must provide a valid application ID.",
    "locations": [
      {
        "line": 2,
        "column": 3
      }
    ],
    "path": [
      "application"
    ],
    "errorCode": 1008
  }
]

La siguiente tabla enumera los códigos de error y sus descripciones. Consulte la message del error para más detalles.

Consultas adicionales

Puede buscar un ID de sesión sin incluir un ID de proyecto en una consulta:

{
  project(sessionIds: "2_MX4xMDB-fjE3MTMyMTMwNDQ1NDV-Z29CLzhyejNha1N2M2RaV255Sno1RTZNfn5-") {
    sessionData {
      sessions {
        resources {
          mediaMode
          sessionId
          meetings {
            totalCount
            pageInfo {
              hasNextPage
              endCursor
            }
            resources {
              meetingId
              createdAt
              destroyedAt
            }
          }
        }
      }
    }
  }
}

Puede utilizar la función not operador para projectData:

{
  project(projectId: 12345678) {
    projectData(
      start: "2024-04-10T11:37:06.147Z"
      interval: AUTO
      not: {
        sdkType:ANDROID
      }
    ) {
      resources {
        intervalStart
        intervalEnd
        sdkType
        sdkVersion
        browser
        usage {
          streamedPublishedMinutes
          streamedSubscribedMinutes
        }
      }
    }
  }
}

Puedes filtrar las conexiones por ubicación y navegador:

{
  project(sessionIds: "2_MX4xMDB-fjE3MTMyMTMwNDQ1NDV-Z29CLzhyejNha1N2M2RaV255Sno1RTZNfn5-") {
    sessionData {
      sessions {
        resources {
          meetings {
            resources {
              connections(country: "US") {
                totalCount
              }
            }
          }
        }
      } 
    }
  }
}

Puede establecer un audioCodec filtro (a PCMU, VP8, OPUS, TELEPHONEo OTHER), o establecer un videoCodec filtro (a VP8, H264, VP9, RTXo OTHER):

{
  project(sessionIds: "2_MX4xMDB-fjE3MTMyMTMwNDQ1NDV-Z29CLzhyejNha1N2M2RaV255Sno1RTZNfn5-") {
    sessionData {
      sessions {
        resources {
          sessionId
          meetings {
            resources {
              meetingId
              createdAt
              publishers {
                resources {
                  createdAt
                  connectionId
                  stream {
                    streamId
                  }
                  streamStatsCollection(filters: { videoCodec: VP8} ) {
                    resources {
                      createdAt
                      audioBitrateKbps
                      videoBitrateKbps
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Puede establecer un mediaMode filtrar a ROUTED o RELAYED.

{
  project(sessionIds: "2_MX4xMDB-fjE3MTMyMTMwNDQ1NDV-Z29CLzhyejNha1N2M2RaV255Sno1RTZNfn5-") {
    sessionData {
      sessionSummaries (
        start: "2024-02-25T20:02:32.345Z"
        filters: { mediaMode: ROUTED } ) {
        resources {
          sessionId
          mediaMode
          meetings  {
            totalCount
            pageInfo {
              hasNextPage
              endCursor
            }
            resources {
              meetingId
              createdAt
              destroyedAt
            }
          }
        }
      }
    }
  }
}