Compartir:
){kind=small}
Zining es un antiguo Director de Producto de Vonage centrado en herramientas para desarrolladores.
Introducción a Advanced Insights
Tiempo de lectura: 8 minutos
Así que desea obtener más información sobre el rendimiento de su aplicación de vídeo. Tal vez desee hacer un seguimiento del uso de su aplicación de vídeo para ver cuántos minutos pasan sus usuarios por sesión. O tal vez desee analizar información de calidad para comprender mejor la experiencia de vídeo de sus clientes. ¿Ha oído hablar de Advanced Insights, pero no sabe por dónde empezar? Pues está en el lugar adecuado.
¿Aún no dispone de Advanced Insights? Póngase en contacto con nosotros y le ayudaremos a empezar.
Le mostraremos cómo empezar rápidamente a consultar la información de su sesión de Video utilizando Advanced Insights y GraphQL. Para nuestro tutorial, utilizaremos la herramienta Inspector como ejemplo y veremos cómo puedes obtener los datos que necesitas para crear tu propio panel de control personalizado similar a Inspector.
Para los fines de esta guía, nos centraremos principalmente en la obtención de datos de tasa de bits del editor para construir un gráfico de calidad para una sesión específica similar al componente Métricas de calidad o Detalles del editor en la herramienta de diagnóstico de la Video API, Inspector.
Al final de este tutorial, usted sabrá cómo hacer consultas Advanced Insights para obtener todos los datos que necesita para construir un gráfico de tasa de bits editor en un panel personalizado.
¿Quieres saltar hasta el final? Puedes encontrar todo el código fuente de este tutorial en GitHub
Este tutorial asume que eres un usuario de la Video API con una Account que tiene datos de uso. Si aún no tienes una Account o no has comenzado a construir con la Video API de Vonage, sigue estos tutoriales rápidos y fáciles ¡para comenzar!
Advanced Insights se basa en GraphQL para realizar consultas y acceder a los datos de tu Video API de Vonage. No te preocupes si no estás familiarizado con GraphQL, ¡es muy fácil comenzar! Incluso tenemos un práctico entorno de desarrollo disponible para probar tus consultas GraphQL de Advanced Insights llamado Explorador Insights GraphiQL (fíjese en la "i" de GraphiQL). Se puede acceder a él directamente desde el panel de control de Insights.
Antes de acceder a sus datos de Video con Advanced Insights, primero tenemos que entender un poco cómo funciona GraphQL.
En general, cuando realizas una consulta GraphQL, se validará contra un esquema GraphQL y recibirá una respuesta de tipo JSON. En nuestro caso, se validará con nuestro esquema Advanced Insights.
Un esquema es un conjunto de tipos de objetos graphQL que describen los datos que se pueden consultar en la API. La documentación sobre nuestro esquema Insights se encuentra en la parte derecha del Explorador de Insights GraphiQL.
Un objeto GraphQL se define por un tipo y los campos asociados en el tipo.
Supongamos que desea conocer el nombre de un determinado héroe con el siguiente esquema GraphQL (de Introducción a GraphQL).
type Query {
me: User
}type User {
id: ID
name: String
}Esta hipotética consulta:
{
me {
name
}
}produciría el siguiente JSON:
{
“me”: {
“name”: “Luke Skywalker”
}
}
Ahora vamos a acceder a algunos de sus datos de Video utilizando Advanced Insights y GraphQL. Para nuestra primera consulta, nuestro objetivo es obtener una lista de ID de sesión.
En primer lugar, vamos a especificar nuestro id de proyecto, que sería la clave API de su proyecto.
{
project(projectId: Your API Key Here) {
...
}
}Ahora que estamos buscando nuestros IDs de sesión, necesitamos usar sessionData.
{
project(projectId: Your API Key Here) {
sessionData{
...
}
}
}Si queremos ver nuestras opciones dentro de sessionDatapodemos usar nuestro fiel Explorador de Esquemas dentro de nuestro Insights GraphiQL Explorer. La búsqueda de sessionData nos da los siguientes resultados:
Esto nos dice que dentro de sessionDatadebemos especificar un campo sessionSummaries que requiera al menos un argumento start como indica el símbolo ! al final del tipo start tipo.
Especifiquemos una fecha de inicio en nuestra consulta.
Nota: Advanced Insights tiene un periodo de retención de datos de 21 días. Recibirá un error si se especifica una fecha anterior al periodo de retención. Encontrará una lista completa de errores aquí.
{
project(projectId: Your API Key Here){
sessionData{
sessionSummaries(start: Your timestamp here){
...
}
}
}
}Como queremos una lista de identificadores de sesión, deberíamos especificarlo en los recursos dentro de sessionSummaries. Para ver los recursos disponibles en el esquema, vaya a la página sessionData Esquema (busque simplemente sessionData), seleccione el tipo SessionSummaries! (el tipo está en amarillo), luego seleccione [SessionSummary]! tipo en "Campos".
Nota: Los corchetes alrededor de
SessionSummarysignifica que devolverá una lista
{
project(projectId: Your API Key Here){
sessionData{
sessionSummaries(start: Your timestamp here){
resources{
sessionId
}
}
}
}
}Ahora tiene una consulta completa. Copie y pegue esto en su Insights GraphiQL Explorer (Asegúrese de haber iniciado sesión en su Account). Recuerde rellenar el campo projectID con su clave API y especificar una hora de inicio.
Una vez que ejecutes esta consulta, deberías obtener algo como esto.
{
"data": {
"project": {
"sessionData": {
"sessionSummaries": {
"resources": [
{
"sessionId": "Your Session ID Here"
},
{
"sessionId": "Your Session ID Here"
}
]
}
}
}
}
}Como se muestra en los resultados, deberíamos obtener una lista de nuestros ID de sesión en formato JSON.
En el esquema podemos ver que mediaMode es otro campo disponible en SessionSummary. Añadiendo esto a nuestra consulta:
{
project(projectId: Your API Key Here){
sessionData{
sessionSummaries(start: Your timestamp here){
resources{
sessionId,
mediaMode
}
}
}
}
}Devoluciones:
{
"data": {
"project": {
"sessionData": {
"sessionSummaries": {
"resources": [
{
"sessionId": "Your Session ID Here",
“mediaMode”: “routed”
},
{
"sessionId": "Your Session ID Here",
“mediaMode”: “routed”
}
]
}
}
}
}
}Simplemente añadiendo un campo más a nuestra consulta, pudimos saber si una sesión fue enrutada o retransmitida lo que supone un nivel adicional de información.
Ahora que ya sabes cómo hacer una consulta GraphQL simple y acceder a los datos de tu proyecto de vídeo, vamos a empezar a construir nuestra consulta para acceder a la información de tu bitrate de vídeo.
En primer lugar, tenemos que averiguar qué datos necesitamos para construir un gráfico de la tasa de bits del editor. Veamos primero el gráfico en nuestra herramienta Inspector.
Para acceder a este gráfico en el Inspector, primero tenemos que introducir el ID de la sesión que nos interesa. Esto significa que definitivamente necesitaríamos tener el ID de sesión en nuestra consulta. También buscamos tasa de bits del editor así que probablemente también querremos especificarlo. La calidad está separada por flujos individuales (cada línea de color en el gráfico del Inspector representa un flujo diferente), por lo que necesitaríamos tener una forma de separar la tasa de bits por flujo. Por último, pero lo más importante, sabemos que tendríamos que acceder a alguna forma de datos de bitrate. En Advanced Insights, la información de bitrate se almacena en Estadísticas de flujo.
Ahora tenemos una idea general de qué campos necesitamos. Sabiendo esto, ¡comencemos a construir nuestra consulta GraphQL!
De entrada, tenemos que especificar nuestro identificador de proyecto (también conocido como clave API). Utilizaremos de nuevo sessionData porque estamos consultando datos a nivel de sesión. Dado que conocemos la sesión que nos interesa, podemos utilizar el campo sessions campo Por el esquema, sabemos que este campo requiere un array de IDs de sesión. Sólo estamos interesados en una única sesión, por lo que podemos introducir un único ID de sesión (si introduce más de un ID de sesión, la consulta devolverá los datos especificados para todas las sesiones introducidas).
Nuestra consulta debería tener este aspecto:
{
project(projectId: Your API Key Here){
sessionData{
sessions(sessionIds: ["Your Session ID Here"]){
...
}
}
}
}En Advanced Insights, nuestros flujos se agrupan por reuniones. Esto significa que para acceder a los datos de nuestros flujos, tendríamos que especificar las reuniones en nuestra consulta. Observando los recursos disponibles para sessions en el esquema (debe hacer clic en el tipo amarillo Session amarillo), podemos ver meetings como campo disponible. Profundizando en los recursos para meetingsvemos que publishers es un campo bajo reuniones. Perfecto. Estamos buscando datos de editores, así que incluyamos publishers en nuestra consulta.
{
project(projectId: Your API Key Here){
sessionData{
sessions(sessionIds: ["Your Session ID Here"]){
resources{
meetings{
resources{
publishers{
...
}
}
}
}
}
}
}
}Sabemos que estamos tratando de llegar a la información a nivel de flujo, así que vamos a explorar el publishers campo. En el esquema (¿ves un patrón?), podemos ver que publishers tiene un campo llamado streamStatsCollection. ¿Le suena familiar? Pues sí. Nuestros datos de tasa de bits de Video se guardan en Stream Statistics. Buscando en los recursos bajo el tipo PublisherStreamStatsCollectionobtenemos un montón de campos relacionados con la calidad a los que podemos acceder para nuestro flujo de vídeo. Para los propósitos de esta guía, sólo estamos interesados en nuestra tasa de bits de vídeo, así que vamos a añadir el campo videoBitrateKbps a nuestra consulta. Para construir un gráfico de bitrate, también necesitaríamos tener un tiempo asociado con nuestra lectura de bitrate. Así que vamos a añadir el campo createdAt de paso.
La consulta debería tener ahora este aspecto:
{
project(projectId: Your API Key Here){
sessionData{
sessions(sessionIds: ["Your Session ID Here"]){
resources{
meetings{
resources{
publishers{
resources{
streamStatsCollection{
resources{
videoBitrateKbps,
createdAt
}
}
}
}
}
}
}
}
}
}
}Esta consulta es suficiente para obtener la tasa de bits de vídeo de nuestro editor por flujo. Para que quede más claro, probablemente queramos dar un nombre a la calidad de nuestro flujo. Para ello, volvemos a los recursos disponibles para streamStatsCollection y añadimos streamID que está debajo de stream.
{
project(projectId: Your API Key Here){
sessionData{
sessions(sessionIds: ["Your Session ID Here"]){
resources{
meetings{
resources{
publishers{
resources{
stream{
streamId
}
streamStatsCollection{
resources{
videoBitrateKbps,
createdAt
}
}
}
}
}
}
}
}
}
}
}La ejecución de esta consulta en Insights GraphiQL Explorer debería devolver algo como esto:
{
"data": {
"project": {
"sessionData": {
"sessions": {
"resources": [{
"meetings": {
"resources": [{
"publishers": {
"resources": [{
"stream": {
"streamId": "e70fef65-f107-428b-9c03-02351812654f"
},
"streamStatsCollection": {
"resources": [{
"videoBitrateKbps": 6.61,
"createdAt": "2020-03-22T12:24:05.407Z"
},{
"videoBitrateKbps": 7.95,
"createdAt": "2020-03-22T12:24:13.194Z"
},{
"videoBitrateKbps": 8.17,
"createdAt": "2020-03-22T12:24:14.438Z"
},{
"videoBitrateKbps": 7.6,
"createdAt": "2020-03-22T12:24:28.729Z"
}]
}
}]
}
}]
}
}]
}
}
}
}
}El resultado de este ejemplo está simplificado. Podría ver múltiples flujos con una lista más larga de videoBitrateKbps campos si tuviera varios editores para esa reunión y flujos más largos.
Ya tenemos una consulta completa que nos proporciona todos los datos que necesitamos para recrear nuestro componente de gráfico de tasa de bits del editor. Ya puedes utilizar esta consulta GraphQL para crear un panel interactivo como el del Inspector.
Para empezar, tenemos una aplicación de ejemplo que te permite buscar un ID de sesión y obtener un gráfico que muestra la información de la tasa de bits del editor para esa sesión. Para este ejemplo, hemos construido el panel de control utilizando Apollo y React. (psst también tenemos un entrada de blog que te guía a través de consultas GraphQL usando Apollo.
Ahora que ya sabe cómo realizar una consulta de Advanced Insights y cómo utilizar el explorador de esquemas para obtener los campos que necesita, aquí tiene otras consultas útiles que le ayudarán a sacar el máximo partido de Advanced Insights.
{
project(projectId: Your API Key Here){
sessionData{
sessions(sessionIds: ["Your Session ID Here"]){
resources{
meetings{
resources{
publisherMinutes,
subscriberMinutes
}
}
}
}
}
}
}
{
project(projectId: Your API Key Here){
sessionData{
sessions(sessionIds: ["Your Session ID Here"]){
resources{
meetings{
resources{
subscribers{
resources{
streamStatsCollection{
resources{
videoPacketLoss,
videoLatencyMs
}
}
}
}
}
}
}
}
}
}
}Ya está listo para crear sus propias consultas personalizadas y empezar a conocer mejor la experiencia de sus clientes con su aplicación de vídeo. No deje de consultar nuestro otro ejemplo de aplicación de panel de control que combina datos a nivel de proyecto de Insights y datos a nivel de sesión de Advanced Insights en un único panel para visualizar los datos de su aplicación de vídeo. Puede encontrar documentación para desarrolladores sobre Insights y Advanced Insights aquí.