Compartilhar:
){kind=small}
Zining é um ex-gerente de produto da Vonage especializado em ferramentas para desenvolvedores
Introdução ao Advanced Insights
Tempo de leitura: 8 minutos
Então, você quer obter mais informações sobre o desempenho do seu aplicativo de vídeo. Talvez queira acompanhar o uso do aplicativo para saber quantos minutos seus usuários estão passando por sessão. Ou talvez esteja procurando analisar dados de qualidade para entender melhor a experiência de vídeo dos seus clientes. Você já ouviu falar do Advanced Insights, mas não sabe por onde começar? Bem, você está no lugar certo!
Ainda não tem o Advanced Insights? Entre em contato conosco e vamos te ajudar a começar!
Vamos mostrar como começar rapidamente a consultar as informações da sua sessão de Video usando o Advanced Insights e o GraphQL. Para o nosso tutorial, usaremos a Ferramenta Inspector como exemplo e explicaremos como você pode obter os dados necessários para criar seu próprio painel personalizado, semelhante ao Inspector.
Para os fins deste guia, vamos nos concentrar principalmente na obtenção de dados de taxa de bits do editor para criar um gráfico de qualidade para uma sessão específica, semelhante ao componente “Métricas de Qualidade” ou “Detalhes do Editor” na ferramenta de diagnóstico da Video API, o Inspector.
Ao final deste tutorial, você saberá como fazer consultas no Advanced Insights para obter todos os dados necessários para criar um gráfico de taxa de bits do editor em um painel personalizado.
Quer pular direto para o final? Você pode encontrar todo o código-fonte deste tutorial no GitHub
Este tutorial pressupõe que você seja um usuário da Video API com um Account que contenha dados de uso. Se você ainda não tem um Account ou ainda não começou a desenvolver com a Video API da Vonage, siga estes tutoriais rápidos e fáceis para começar!
O Advanced Insights utiliza o GraphQL para realizar consultas e acessar seus dados da Video API do Vonage. Não se preocupe se você não estiver familiarizado com o GraphQL, é super fácil começar! Temos até mesmo um ambiente de desenvolvimento prático disponível para você testar suas consultas GraphQL do Advanced Insights, chamado Insights GraphiQL Explorer (observe o “i” em GraphiQL). Ele pode ser acessado diretamente do seu painel do Insights.
Antes de acessar seus dados de Video com o Advanced Insights, precisamos primeiro entender um pouco sobre como o GraphQL funciona.
Em geral, quando você faz uma consulta GraphQL, ela é validada em relação a um esquema GraphQL e recebe uma resposta no formato JSON. No nosso caso, ela será validada em relação ao nosso esquema do Advanced Insights.
Um esquema é um conjunto de tipos de objetos GraphQL que descreve quais dados você pode consultar na API. A documentação sobre o nosso esquema do Insights pode ser encontrada no lado direito do Explorador GraphiQL do Insights.
Um objeto GraphQL é definido por um tipo e pelos campos associados a esse tipo.
Digamos que você queira saber o nome de um determinado herói com o seguinte esquema GraphQL (de Introdução ao GraphQL).
type Query {
me: User
}type User {
id: ID
name: String
}Esta consulta hipotética:
{
me {
name
}
}produziria o seguinte JSON:
{
“me”: {
“name”: “Luke Skywalker”
}
}
Agora, vamos acessar alguns dos seus dados de Video usando o Advanced Insights e o GraphQL. Para nossa primeira consulta, nosso objetivo é obter uma lista de IDs de sessão.
Primeiro, vamos definir o ID do nosso projeto, que seria a chave de API do seu projeto.
{
project(projectId: Your API Key Here) {
...
}
}Agora, como estamos procurando nossos IDs de sessão, precisamos usar sessionData.
{
project(projectId: Your API Key Here) {
sessionData{
...
}
}
}Se quisermos ver nossas opções dentro sessionData, podemos usar nosso fiel Schema Explorer no Insights GraphiQL Explorer. Ao pesquisar por sessionData nos dá os seguintes resultados:
Isso nos indica que, dentro de sessionData, devemos especificar um sessionSummaries campo que exija, no mínimo, um start argumento, conforme indicado pelo ! no final do start tipo.
Vamos especificar uma data de início em nossa consulta.
Observação: O Advanced Insights tem um período de retenção de dados de 21 dias. Você receberá uma mensagem de erro se especificar uma data anterior ao período de retenção. Uma lista completa de erros pode ser encontrada aqui.
{
project(projectId: Your API Key Here){
sessionData{
sessionSummaries(start: Your timestamp here){
...
}
}
}
}Como queremos uma lista de IDs de sessões, devemos especificar isso nos recursos dentro de sessionSummaries. Para visualizar os recursos disponíveis no Esquema, acesse a sessionData página “Esquema” (basta pesquisar por sessionData), selecione o tipo SessionSummaries! (o tipo está em amarelo) e, em seguida, selecione [SessionSummary]! tipo em “Campos”.
Observação: Os colchetes em torno de
SessionSummarysignificam que isso retornará uma lista
{
project(projectId: Your API Key Here){
sessionData{
sessionSummaries(start: Your timestamp here){
resources{
sessionId
}
}
}
}
}Agora você tem uma consulta completa. Copie e cole-a no GraphiQL Explorer do Insights (certifique-se de estar conectado ao seu Account). Lembre-se de preencher o projectID campo com sua chave de API e especificar uma hora de início!
Depois de executar essa consulta, você deverá obter um resultado semelhante a este.
{
"data": {
"project": {
"sessionData": {
"sessionSummaries": {
"resources": [
{
"sessionId": "Your Session ID Here"
},
{
"sessionId": "Your Session ID Here"
}
]
}
}
}
}
}Conforme mostrado nos resultados, devemos obter uma lista dos nossos IDs de sessão no formato JSON.
Pelo esquema, podemos ver que mediaMode há outro campo disponível em SessionSummary. Adicionando isso à nossa consulta:
{
project(projectId: Your API Key Here){
sessionData{
sessionSummaries(start: Your timestamp here){
resources{
sessionId,
mediaMode
}
}
}
}
}Devoluções:
{
"data": {
"project": {
"sessionData": {
"sessionSummaries": {
"resources": [
{
"sessionId": "Your Session ID Here",
“mediaMode”: “routed”
},
{
"sessionId": "Your Session ID Here",
“mediaMode”: “routed”
}
]
}
}
}
}
}Bastou adicionar mais um campo à nossa consulta para descobrirmos se uma sessão foi roteada ou retransmitida , proporcionando a você uma camada adicional de informações.
Agora que você já sabe como fazer uma consulta simples em GraphQL e acessar os dados do seu projeto de Video, vamos começar a criar nossa consulta para acessar as informações sobre a taxa de bits do Video.
Primeiro, precisamos determinar quais dados são necessários para criar um gráfico de taxa de bits do editor. Vamos dar uma olhada no gráfico em nossa ferramenta Inspector.
Para acessar esse gráfico no Inspector, tivemos que inserir primeiro o ID da sessão que nos interessa. Isso significa que precisaríamos, sem dúvida, ter o ID da sessão em nossa consulta. Também estamos procurando a taxa de bits do publisher , então provavelmente vamos querer especificar isso também. A qualidade é separada por fluxos individuais (cada cor de linha no gráfico do Inspector representa um fluxo diferente), então precisaríamos de uma maneira de separar a taxa de bits por fluxo. Por último, mas mais importante, sabemos que precisaremos acessar algum tipo de dados de taxa de bits. No Advanced Insights, as informações de taxa de bits são armazenadas em Estatísticas de Fluxo.
Agora já temos uma ideia geral de quais campos precisamos. Sabendo disso, vamos começar a construir nossa consulta GraphQL!
Logo de cara, precisamos especificar o ID do nosso projeto (também conhecido como chave de API). Vamos usar novamente sessionData , pois estamos consultando dados no nível da sessão. Como sabemos qual é a sessão que nos interessa, podemos usar o sessions campo. Pelo esquema, sabemos que esse campo exige um array de IDs de sessão. Como estamos interessados em apenas uma sessão, basta inserir um único ID de sessão (se você inserir mais de um ID de sessão, a consulta retornará os dados especificados para todas as sessões inseridas).
Nossa consulta deve ficar assim:
{
project(projectId: Your API Key Here){
sessionData{
sessions(sessionIds: ["Your Session ID Here"]){
...
}
}
}
}No Advanced Insights, nossos fluxos são agrupados por reuniões. Isso significa que, para acessar os dados dos nossos fluxos, precisaríamos especificar as reuniões em nossa consulta. Analisando os recursos disponíveis para sessions no esquema (é preciso clicar no tipo amarelo Session ), podemos ver meetings como um campo disponível. Ao analisar mais detalhadamente os recursos para meetings, percebemos que publishers é um campo dentro de “reuniões”. Perfeito! Estamos procurando dados do editor, então vamos incluir publishers em nossa consulta também.
{
project(projectId: Your API Key Here){
sessionData{
sessions(sessionIds: ["Your Session ID Here"]){
resources{
meetings{
resources{
publishers{
...
}
}
}
}
}
}
}
}Sabemos que estamos tentando obter informações no nível do fluxo, então vamos explorar o publishers campo. Pelo esquema (está percebendo um padrão aqui?), podemos ver que publishers existe um campo chamado streamStatsCollection. Isso soa familiar? Isso mesmo! Nossos dados de taxa de bits de Video estão salvos em “Stream Statistics”! Ao examinar os recursos do tipo PublisherStreamStatsCollection, encontramos diversos campos relacionados à qualidade que podemos acessar para nossa transmissão de Video. Para os fins deste guia, estamos interessados apenas na taxa de bits do Video; portanto, vamos adicionar o campo videoBitrateKbps à nossa consulta. Para criar um gráfico de taxa de bits, também precisaríamos ter um horário associado à nossa leitura de taxa de bits. Então, vamos adicionar o createdAt campo já que estamos nisso.
A consulta deve ficar assim agora:
{
project(projectId: Your API Key Here){
sessionData{
sessions(sessionIds: ["Your Session ID Here"]){
resources{
meetings{
resources{
publishers{
resources{
streamStatsCollection{
resources{
videoBitrateKbps,
createdAt
}
}
}
}
}
}
}
}
}
}
}Essa consulta já é suficiente para obtermos a taxa de bits do Video do editor por stream. Para deixar mais claro, provavelmente gostaríamos de atribuir um nome à qualidade do nosso stream. Para isso, voltamos aos recursos disponíveis para streamStatsCollection e adicionamos streamID que está em “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
}
}
}
}
}
}
}
}
}
}
}Ao executar essa consulta no GraphiQL Explorer do Insights, o resultado deve ser algo parecido com isto:
{
"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"
}]
}
}]
}
}]
}
}]
}
}
}
}
}O resultado do exemplo acima é simplificado. Você pode ver vários fluxos com uma lista mais longa de videoBitrateKbps campos caso haja vários editores para essa reunião e fluxos mais longos.
Agora temos uma consulta completa que nos fornece todos os dados necessários para recriar nosso componente de gráfico de taxa de bits do editor! Você já está pronto para usar essa consulta GraphQL para criar um painel interativo igual ao do Inspector!
Para você começar, temos um aplicativo de exemplo que permite que você pesquise um ID de sessão e obtenha um gráfico mostrando as informações de taxa de bits do editor para essa sessão. Para este exemplo, criamos o painel usando Apollo e React. (psst, também temos uma post no blog que explica passo a passo como fazer consultas GraphQL usando o Apollo.)
Agora que você já sabe como criar uma consulta no Advanced Insights e como usar o Schema Explorer para obter os campos necessários, veja a seguir algumas outras consultas úteis que vão ajudá-lo a aproveitar ao máximo o 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
}
}
}
}
}
}
}
}
}
}
}Agora você está pronto para criar suas próprias consultas personalizadas e começar a aprender mais sobre como seus clientes interagem com seu aplicativo de Video! Não deixe de conferir nosso outro aplicativo de painel de controle de exemplo , que combina dados no nível do projeto, do Insights, e dados no nível da sessão, do Advanced Insights, em um único painel para visualizar os dados do seu aplicativo de Video. A documentação para desenvolvedores sobre o Insights e o Advanced Insights pode ser encontrada aqui.