Premiers pas avec Advanced Insights

Commencez à accéder à vos données Video au niveau de la session avec GraphQL et Advanced Insights.

Vous souhaitez obtenir davantage d'informations sur les performances de votre application vidéo. Vous souhaitez peut-être suivre l'utilisation de votre application Video pour savoir combien de minutes vos utilisateurs passent par session. Ou peut-être cherchez-vous à analyser des informations de qualité pour mieux comprendre l'expérience vidéo de vos clients. Vous avez entendu parler d'Advanced Insights, mais vous ne savez pas par où commencer ? Vous êtes au bon endroit !

Vous ne disposez pas encore d'Advanced Insights ? Contactez nous et nous vous aiderons à démarrer !

Nous allons vous montrer comment commencer rapidement à interroger vos informations de session vidéo à l'aide d'Advanced Insights et de GraphQL. Pour notre tutoriel, nous utiliserons l'outil Inspecteur comme exemple et nous verrons comment vous pouvez obtenir les données dont vous avez besoin pour créer votre propre tableau de bord personnalisé de type Inspecteur.

Dans le cadre de ce guide, nous nous concentrerons principalement sur l'obtention des données de débit de l'éditeur afin de créer un graphique de qualité pour une session spécifique, similaire au composant Quality Metrics ou Publisher Details de l'outil de diagnostic de l'API Video, Inspector.

À la fin de ce tutoriel, vous saurez comment effectuer des requêtes Advanced Insights pour obtenir toutes les données dont vous avez besoin pour créer un graphique du débit binaire de l'éditeur sur un tableau de bord personnalisé.

Vous voulez sauter à la fin ? Vous pouvez trouver tout le code source de ce tutoriel sur GitHub

Conditions préalables

Ce tutoriel suppose que vous êtes un utilisateur de Video API disposant d'un compte avec des données d'utilisation. Si vous n'avez pas encore de compte ou si vous n'avez pas encore commencé à construire avec l'API Video de Vonage, suivez ces tutoriels rapides et faciles pour commencer !

Pour commencer

Advanced Insights s'appuie sur GraphQL pour effectuer des requêtes afin d'accéder aux données de votre Video API de Vonage. Ne vous inquiétez pas si vous n'êtes pas familier avec GraphQL, il est très facile de commencer ! Nous disposons même d'un environnement de développement pratique pour tester les requêtes GraphQL d'Advanced Insights, appelé Insights GraphiQL Explorer (remarquez le "i" de GraphiQL). Vous pouvez y accéder directement depuis votre tableau de bord Insights.

GraphQL

Avant d'accéder à vos données Video avec Advanced Insights, il faut d'abord comprendre un peu le fonctionnement de GraphQL.

En général, lorsque vous effectuez une requête GraphQL, celle-ci est validée par rapport à un schéma GraphQL et reçoit une réponse de type JSON. Dans notre cas, elle sera validée par rapport à notre schéma Advanced Insights.

Un schéma est un ensemble de types d'objets graphQL qui décrivent les données que vous pouvez rechercher dans l'API. La documentation sur notre schéma Insights est disponible sur le côté droit de l'explorateur GraphiQL d Insights GraphiQL Explorer.

Un objet GraphQL est défini par un type et les champs associés à ce type.

Supposons que vous souhaitiez connaître le nom d'un certain héros avec le schéma GraphQL suivant (tiré de Introduction à GraphQL).

type Query {
	  me: User
    }

type User {
      id: ID
      name: String
    }

Cette question hypothétique :

{
      me {
        name
      }
    }

produirait le JSON suivant :

{
      “me”: {
        “name”: “Luke Skywalker”
      }
    }

Perspectives avancées et GraphQL

Accédons maintenant à certaines de vos données Video à l'aide d'Advanced Insights et de GraphQL. Pour notre première requête, notre objectif est d'obtenir une liste d'identifiants de session.

Tout d'abord, indiquons l'identifiant de notre projet, qui sera la clé API de votre projet.

{
      project(projectId: Your API Key Here) {
        ...
      }
    }

Puisque nous recherchons nos identifiants de session, nous devons utiliser sessionData.

{
      project(projectId: Your API Key Here) {
    	sessionData{
          ...
    	}
      }
    }

Si nous voulons voir nos options au sein de sessionDatanous pouvons utiliser notre fidèle explorateur de schémas dans notre explorateur Insights GraphiQL. En recherchant sessionData nous donne les résultats suivants :

Cela nous indique qu'à l'intérieur de sessionDatanous devrions spécifier un champ sessionSummaries qui nécessite au moins un argument start comme indiqué par le ! à la fin du type start à la fin du type .

Spécifions une date de début dans notre requête.

Note : Advanced Insights a une période de rétention des données de 21 jours. Vous recevrez un message d'erreur si une date antérieure à la période de conservation est spécifiée. Une liste complète des erreurs est disponible ici.

{
      project(projectId: Your API Key Here){
        sessionData{
          sessionSummaries(start: Your timestamp here){  
            ...
          }
        }
      }
    }

Puisque nous voulons une liste d'identifiants de sessions, nous devrions le spécifier dans les ressources à l'intérieur de sessionSummaries. Pour consulter les ressources disponibles dans le schéma, rendez-vous sur la page sessionData Schema (recherchez simplement sessionData), sélectionnez le type SessionSummaries! (le type est en jaune), puis sélectionnez [SessionSummary]! sous "Champs".

Note : Les crochets autour de SessionSummary signifie que cette méthode renverra une liste

{
      project(projectId: Your API Key Here){
        sessionData{
          sessionSummaries(start: Your timestamp here){
            resources{
              sessionId
            }
          }
        }
      }
    }

Vous avez maintenant une requête complète. Copiez et collez-la dans votre Insights GraphiQL Explorer (assurez-vous d'être connecté à votre Account). N'oubliez pas de remplir le champ projectID avec votre clé API et de spécifier une heure de début !

Une fois que vous aurez exécuté cette requête, vous devriez obtenir quelque chose comme ceci.

{
	  "data": {
		"project": {
		  "sessionData": {
			"sessionSummaries": {
			  "resources": [
				{
				  "sessionId": "Your Session ID Here"
				},
				{
				  "sessionId": "Your Session ID Here"
				}
			  ]
			}
		  }
		}
	  }
    }

Comme le montrent les résultats, nous devrions obtenir une liste de nos identifiants de session au format JSON.

Ajouter des informations supplémentaires à votre requête (facultatif)

D'après le schéma, nous pouvons voir que mediaMode est un autre champ disponible sous SessionSummary. Nous l'ajoutons à notre requête :

{
      project(projectId: Your API Key Here){
        sessionData{
          sessionSummaries(start: Your timestamp here){
            resources{
              sessionId,
              mediaMode
            }
          }
        }
      }
    }

Retours :

{
	  "data": {
		"project": {
		  "sessionData": {
			"sessionSummaries": {
			  "resources": [
				{
				  "sessionId": "Your Session ID Here",
				  “mediaMode”: “routed”
				},
				{
				  "sessionId": "Your Session ID Here",
				  “mediaMode”: “routed”
				}
			  ]
			}
		  }
		}
	  }
    }

En ajoutant simplement un champ supplémentaire à notre requête, nous avons pu savoir si une session était acheminée ou relayée ce qui nous a permis d'obtenir une couche supplémentaire d'informations.

Obtenir des mesures de qualité avec Advanced Insights

Création de la requête GraphQL

Maintenant que vous savez comment créer une requête GraphQL simple et accéder aux données de votre projet Video, commençons à construire notre requête pour accéder aux informations sur le débit de votre vidéo.

Tout d'abord, nous devons déterminer les données dont nous avons besoin pour créer un diagramme de débit de l'éditeur. Jetons d'abord un coup d'œil au graphique dans notre outil Inspecteur.

Pour accéder à ce graphique dans l'inspecteur, nous devons d'abord saisir l'identifiant de la session qui nous intéresse. Cela signifie que nous devons absolument disposer de l ID de la session dans notre requête. Nous recherchons également le débit binaire de l'éditeur nous devrons donc probablement le spécifier également. La qualité est séparée par flux individuels (chaque couleur de ligne sur le graphique de l'inspecteur représente un flux différent), nous aurions donc besoin d'un moyen de séparer le débit par flux. Enfin, mais surtout, nous savons que nous devrons accéder à une forme quelconque de données de débit. Dans Advanced Insights, les informations sur le débit binaire sont stockées sous Statistiques de flux.

Nous avons maintenant une idée générale des champs dont nous avons besoin. Sachant cela, commençons à construire notre requête GraphQL !

D'emblée, nous devons spécifier l'identifiant de notre projet (clé API). Nous utiliserons à nouveau sessionData car nous interrogeons des données au niveau de la session. Puisque nous connaissons la session qui nous intéresse, nous pouvons utiliser le champ sessions . D'après le schéma, nous savons que ce champ nécessite un tableau d'identifiants de session. Comme nous ne nous intéressons qu'à une seule session, nous pouvons nous contenter d'entrer un seul identifiant de session (si vous entrez plusieurs identifiants de session, la requête renverra les données spécifiées pour toutes les sessions qui ont été entrées).

Notre requête devrait ressembler à ceci :

{
      project(projectId: Your API Key Here){
        sessionData{
          sessions(sessionIds: ["Your Session ID Here"]){
            ...
          }
        }
      }
    }

Dans Advanced Insights, nos flux sont regroupés par réunions. Cela signifie que pour accéder aux données de nos flux, nous devons spécifier les réunions dans notre requête. En regardant les ressources disponibles pour sessions dans le schéma (vous devez cliquer sur le type jaune Session jaune), nous pouvons voir que meetings comme champ disponible. En creusant davantage dans les ressources pour meetingsnous voyons que publishers est un champ sous réunions. C'est parfait ! Nous recherchons des données sur les éditeurs. publishers dans notre requête.

{
      project(projectId: Your API Key Here){
        sessionData{
          sessions(sessionIds: ["Your Session ID Here"]){
            resources{
              meetings{
	            resources{
                  publishers{
                    ...
                  }
                }
              }
            }
          }
        }
      }
    }

Nous savons que nous essayons d'obtenir des informations au niveau du flux, alors explorons le champ publishers (champ de données). D'après le schéma (vous voyez une tendance ici ?), nous pouvons voir que publishers possède un champ appelé streamStatsCollection. Cela vous semble-t-il familier ? C'est bien cela ! Nos données sur le débit vidéo sont enregistrées sous Stream Statistics ! En examinant les ressources sous le type PublisherStreamStatsCollectionnous obtenons un grand nombre de champs différents liés à la qualité auxquels nous pouvons accéder pour notre flux vidéo. Pour les besoins de ce guide, nous ne nous intéressons qu'au débit binaire de la vidéo. videoBitrateKbps à notre requête. Pour créer un diagramme de débit, nous devons également associer une heure à notre lecture du débit. Ajoutons donc le champ createdAt tant que nous y sommes.

La requête doit maintenant ressembler à ceci :

{
      project(projectId: Your API Key Here){
        sessionData{
          sessions(sessionIds: ["Your Session ID Here"]){
            resources{
              meetings{
    			resources{
                  publishers{
                    resources{
                      streamStatsCollection{
                        resources{
                          videoBitrateKbps,
                          createdAt
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }

Cette requête suffit pour obtenir le débit vidéo de notre éditeur par flux. Pour plus de clarté, nous voudrions probablement donner un nom à la qualité de notre flux. Pour ce faire, nous retournons aux ressources disponibles pour streamStatsCollection et ajoutons streamID qui se trouve sous 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
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }

L'exécution de cette requête dans l'explorateur Insights GraphiQL devrait donner un résultat similaire :

{
      "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"
    				        }]
    			          }
                        }]
    			      }
    			   }]
    		     }
    		  }]
    		}
          }
        }
      }
    }

L'exemple ci-dessus est simplifié. Vous pourriez voir plusieurs flux avec une liste de champs plus longue si vous aviez plusieurs éditeurs pour cette réunion et des flux plus longs. videoBitrateKbps si vous aviez plusieurs éditeurs pour cette réunion et des flux plus longs.

Nous avons maintenant une requête complète qui nous donne toutes les données dont nous avons besoin pour recréer notre composant graphique de débit de l'éditeur ! Vous êtes maintenant prêt à utiliser cette requête GraphQL pour construire un tableau de bord interactif comme l'inspecteur !

Pour vous aider à démarrer, nous avons mis à votre disposition un exemple d'application qui vous permet de rechercher un identifiant de session et d'obtenir un tableau montrant les informations sur le débit de l'éditeur pour cette session. Pour cet exemple, nous avons construit le tableau de bord en utilisant Apollo et React. (psst nous avons aussi un article de blog qui vous guide dans la création de requêtes GraphQL à l'aide d'Apollo.

Requêtes bonus

Maintenant que vous savez comment créer une requête Advanced Insights et comment utiliser l'Explorateur de schéma pour obtenir les champs dont vous avez besoin, voici quelques autres requêtes utiles pour vous aider à tirer le meilleur parti d'Advanced Insights.

Obtenir le procès-verbal total de l'éditeur et de l'abonné

{
      project(projectId: Your API Key Here){
        sessionData{
          sessions(sessionIds: ["Your Session ID Here"]){
            resources{
              meetings{
                resources{
    		      publisherMinutes,
                  subscriberMinutes
                }
              }
            }
          }
        }
      }
    }

Perte de paquets et latence de la vidéo de l'abonné

{
      project(projectId: Your API Key Here){
        sessionData{
          sessions(sessionIds: ["Your Session ID Here"]){
            resources{
              meetings{
                resources{
                  subscribers{
                    resources{
                      streamStatsCollection{
                        resources{
                          videoPacketLoss,
                          videoLatencyMs
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }

Vous êtes maintenant prêt à créer vos propres requêtes personnalisées et à en apprendre davantage sur la façon dont vos clients utilisent votre application vidéo ! N'oubliez pas de consulter notre autre exemple de tableau de bord qui combine les données au niveau du projet provenant d'Insights et les données au niveau de la session provenant d'Advanced Insights en un seul tableau de bord pour visualiser les données de votre application vidéo. La documentation destinée aux développeurs sur Insights et Advanced Insights est disponible ici.