Video Insights Dashboard und API

Die Vonage Video Insights API ist eine GraphQL-API. Sie können das Video Insights Dashboard & API verwenden, um Informationen über Ihre Vonage Video-Anwendungen und -Sitzungen zu erhalten.

Video Insights Dashboard

Anmerkung: Bitte anklicken hier für Informationen über Datenspeicherung und Latenzzeiten.

Das Insights Dashboard liefert Daten auf der Ebene der Applications. Sie können dorthin navigieren, indem Sie sich bei Ihrem Vonage Video API-KontoGehen Sie zum Abschnitt Video Analytics und wählen Sie dann eine bestimmte Vonage Video-Anwendung aus.

Insights API, Basis-URL und Authentifizierung

Die Insights API ist eine GraphQL-API die es Ihnen ermöglicht, die Metadaten Ihrer Sitzungen auf der Ebene der Applikationen und Sitzungen zu untersuchen. GraphQL ist eine Alternative zum typischen REST-Ansatz für den Zugriff auf Daten über HTTP. Es wurde 2012 von Facebook entwickelt und 2015 als Open Source zur Verfügung gestellt. Ausprobieren GraphQLs Anleitung für den Einstieg um mehr zu erfahren.

Die Basis-URL für die API lautet:

Alle Anfragen werden gestellt als HTTP POST.

Erforschung des API-Schemas mit GraphiQL

Navigieren zu https://tools.vonage.com/video/insights-api/ in Ihrem Browser führt Sie zu der Insights-Instanz von GraphiQLein Tool, mit dem Sie das GraphQL-API-Schema erkunden können. Da das Tool API-Anfragen stellen kann, müssen Sie eingeloggt sein, um es zu nutzen.

Dieses Werkzeug verfügt über fünf Fensterscheiben:

• In der oberen rechten Ecke des Werkzeugs sehen Sie ein Dokumente Schaltfläche. Wenn Sie darauf klicken, öffnet sich ein Fenster mit der Dokumentation des Schemas. Jedes Feld und jeder Objekttyp in der Dokumentation enthält eine Beschreibung. Klicken Sie diese an, um das Schema zu erkunden.
• Auf der linken Seite der Seite befindet sich die Abfrage Bereich. In diesem Bereich können Sie Abfragen erstellen, die Sie mit der API ausführen. Das Hin- und Herwechseln zwischen dem Dokumente und das Fenster Abfrage können Sie genau die Abfrage erstellen, die Sie benötigen, und zwar nur für die Informationen, die Sie benötigen. Da Sie eingeloggt sind, wird die Authentifizierung für die Abfrage für Sie übernommen.
• Unterhalb des Abfrage ist der Bereich Abfrage-Variablen Fenster. Auch wenn dies nicht erforderlich ist, können Sie hier Variablen für Ihre Abfrage angeben. Sie können zum Beispiel die folgenden Variablen in diesem Bereich definieren:

Verweisen Sie dann im Abfragebereich auf alle deklarierten Variablen:

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
            }
          }
        }
      }
    }
  }

• Rechts neben dem Abfrage ist der Bereich Antwort Fensterbereich. Wenn Sie im Werkzeug auf die Schaltfläche Ausführen klicken, wird die Abfrage im Fenster Abfrage und das Fenster Antwort werden die Ergebnisse angezeigt. Dies ist die gleiche Antwort, die Sie erhalten würden, wenn Sie die Abfrage programmgesteuert durchführen würden.
• Klicken Sie schließlich auf die Schaltfläche Geschichte oberhalb des Abfragefensters, um den Verlauf Ihrer letzten Abfragen anzuzeigen. Wenn Sie auf eines der angezeigten Elemente klicken, wird das Feld Abfrage und das Fenster Abfrage-Variablen Fenster mit diesen Daten.

Beschaffung von Applikationsdaten

Die applicationData Feld des Anwendungsobjekts gibt die ApplicationData Objekt, das aggregierte Berichtsdaten auf der Ebene der Anwendung liefert.

Sie müssen eine start Datum für die Abfrage. Dieser Wert kann eine Zeichenkette im ISO-8601-Format sein (z. B. "2025-01-15T23:43:34.023Z") oder ein Int-Wert, der einen Epochenzeitstempel darstellt. Ganzzahlen mit 10 oder weniger Ziffern stehen für Epochensekunden. Ganzzahlen mit mehr als 10 Ziffern stehen für Epochen-Millisekunden.

Die ApplicationData Objekt enthält eine resources Eigenschaft, die ein Array von Metric Objekte. Sie haben die Möglichkeit, Daten nach SDK-Typ, SDK-Version, Land, Region, Browser oder Browser-Version zu filtern und zu gruppieren. Außerdem haben Sie die Möglichkeit, die Interval in dem Sie die Daten segmentieren wollen (entweder DAILY, WEEKLY, oder MONTHLY). Beachten Sie, dass, wenn Sie die Option Intervalwerden nur Zeitintervalle angezeigt, für die Daten vorliegen.

Hinweis: Insights-Daten auf Applikationsebene sind in der Regel innerhalb von 36 bis 48 Stunden verfügbar.

Anmerkung: Die Filterung nach Region, SDK und Browser ist für Teilnehmer- und Archivierungsprotokolle nicht verfügbar.

Die Metric Objekt enthält Informationen über das Land, die Region (ggf. US-Bundesstaat), den Typ und die Version des Vonage Video SDK sowie den Browser und die Browserversion (falls zutreffend) für die Ergebnisse. Die Metric Objekt umfasst auch die folgenden Eigenschaften:

• usage - Informationen zu veröffentlichten Stream-Minuten, abonnierten Stream-Minuten, Archivnutzung, Broadcast-Nutzung, SIP-Nutzung und Nutzung getrennt nach Publisher-Ebenen
• quality - Informationen zur Videoqualität
• errors - Die Fehlerquoten für die Verbindung zu Sitzungen, die Veröffentlichung und das Abonnieren

Die folgende Abfrage fordert ApplicationData-Ergebnisse an, die Teilnehmerprotokolle für Clients enthalten, die die Vonage Video JavaScript-, Android- und iOS-SDKs verwenden:

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

Beachten Sie, dass durch das Setzen des start auf 0 setzen, werden die Ergebnisse beginnend mit den frühesten verfügbaren Datensätzen abgefragt.

Abrufen von Sitzungsdaten (Erweiterte Einblicke)

Anmerkung: Bitte anklicken hier für Informationen über Datenspeicherung und Latenzzeiten.

Die sessionData Feld des application Objekt gibt die SessionData Objekt. Dieses Objekt umfasst zwei Felder: sessions und sessionSummaries.

Detailinformationen zur Sitzung

Die sessions Feld gibt eine Sessions Objekt. Geben Sie die Sitzungs-IDs als sessionIds Argument (ein Array von übereinstimmenden Zeichenketten). Die Sessions Objekt enthält eine resources Eigenschaft, die ein Array von Session Objekte. Die Website Session Objekt hat die folgenden Eigenschaften:

• mediaMode - Der Medienmodus für die Sitzung. Dieser ist "routed" für Sitzungen, die über den Vonage Video Media Router geleitet werden, oder "relayed" für direktes Peer-to-Peer-Streaming.
• publisherMinutes - Die Gesamtzahl der gestreamten Minuten für alle Verleger in der Sitzung. Beachten Sie, dass die Einbeziehung dieses Feldes die Abfrageergebnisse verlangsamen wird.
• subscriberMinutes - Die Gesamtzahl der gestreamten Minuten für alle Abonnenten in der Sitzung. Beachten Sie, dass die Einbeziehung dieses Feldes die Abfrageergebnisse verlangsamen wird.
• participantMinutes - Die Gesamtzahl der Minuten, getrennt nach Verleger-Ebenen, für alle Sitzungen der Sitzung.
• meetings - Eine Reihe von Meeting Objekte. Eine Vonage Video-Sitzung kann aus mehreren Treffen. Wenn der erste Client eine Verbindung zur Sitzung herstellt, beginnt die erste Besprechung. Die Besprechung endet, wenn mindestens 10 Minuten lang keine Verbindungen in der Sitzung bestehen. Wenn ein Client erneut eine Verbindung herstellt, beginnt eine neue Besprechung. Jedes Besprechungsobjekt umfasst die folgenden Eigenschaften:
  • subscriberMinutes - Die Gesamtzahl der Teilnehmerminuten in der Besprechung.
  • publisherMinutes - Die Gesamtzahl der Verleger-Minuten in der Besprechung.
  • participantMinutes - Die Gesamtzahl der Minuten in der Besprechung, getrennt nach Verleger-Ebenen.
  • connections - Ein Array von Verbindungsobjekten, die jeden Client definieren, der mit der Sitzung (während des Meetings) verbunden ist. Zu den Eigenschaften des Verbindungsobjekts gehören Informationen über das verwendete Vonage Video Client SDK, den verwendeten Browser (für Web-Clients), Informationen über Publisher und Subscriber und mehr.
  • publishers - Ein Array von Publisher-Objekten. Die Eigenschaften des Publisher-Objekts enthalten Informationen über den Stream des Publishers, die Abonnenten des Streams, Stream-Statistiken und mehr. (Die Stream-Statistiken sind im Add-on Advanced Insights enthalten. Siehe Abrufen von Stream-Statistiken.)
  • subscribers - Array von Subscriber-Objekten, die Details über jeden Abonnenten enthalten. Zu den Eigenschaften des Subscriber-Objekts gehören Informationen über den Stream des Abonnenten, Stream-Statistiken und mehr. (Die Stream-Statistiken sind im Add-on Advanced Insights enthalten. Siehe Abrufen von Stream-Statistiken.)
  • createdAt und destroyedAt - Zeitstempel für den Beginn und das Ende der Besprechung.

Anmerkung: Wenn alle Benutzer von einer Besprechung getrennt werden und innerhalb der 10 Minuten eine neue Verbindung zur Sitzung hergestellt wird, wird eine neue Besprechung mit derselben Besprechungs-ID wie die erste Besprechung erstellt. Wenn die neue Verbindung jedoch nach 10 Minuten hergestellt wird, erhält die neue Besprechung eine eindeutige Besprechungs-ID.

Beispiel für die Abfrage von Sitzungsdetails

Die folgende Abfrage fragt einige Publisher-Details zu zwei Vonage Video-Sitzungen ab:

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

Abrufen von Stream-Statistiken

Anmerkung: Stream-Statistiken sind verfügbar für Advanced Insights-Kunden nur.

Die resources Eigenschaft des MeetingPublishers-Objekts ist ein Array von Publisher-Objekten. Und das Publisher-Objekt enthält das PublisherStreamStatsCollection-Objekt. Dieses Objekt ist eine Ressourcensammlung, und seine resources Eigenschaft ist ein Array von PublisherStats-Objekten. Jedes PublisherStats-Objekt enthält Stream-Statistiken für den Publisher, die in regelmäßigen Abständen (alle 30 Sekunden) während des Streaming-Vorgangs des Publishers erfasst werden. Diese Statistiken enthalten Daten über die Audio- und Videolatenz, die Audio- und Videobitrate, die Audio- und Videopaketverlustrate, die Videoauflösung, die Audio- und Videocodecs und darüber, ob der Stream zum Zeitpunkt des Streamstatistik-Snapshots Audio und Video enthielt.

Die folgende Abfrage fragt die periodischen Audio- und Video-Bitratenstatistiken für Publisher in einer Vonage Video-Sitzung ab:

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

Ähnlich verhält es sich mit der resources des MeetingSubscribers-Objekts ist ein Array von Subscriber-Objekten, und jedes dieser Objekte enthält eine SubscriberStreamStatsCollection-Ressourcensammlung, die ähnliche Stream-Statistiken für einen Teilnehmer enthält.

Informationen zur Sitzungszusammenfassung

Anmerkung: Die Sitzungszusammenfassung ist verfügbar für Advanced Insights-Kunden nur.

Die sessionSummaries Feld ist ein Array aus SessionSummary Objekte (eines für jede Sitzung, die der Abfrage entspricht). Das SessionSummary-Objekt enthält ein resources Eigenschaft, die ein Array von MeetingSummary Objekte (eines für jede Besprechung in der Sitzung). Die MeetingSummary Objekt enthält Informationen über die Anzahl der gesamten und gleichzeitigen Streams, Verbindungen und Teilnehmer des Meetings.

Sowohl die SessionSummary Objekt und MeetingSummary Objekte umfassen publisherMinutes, subscriberMinutesund participantMinutes Eigenschaften. Diese melden die Gesamtzahl der gestreamten Minuten für alle Verleger und Abonnenten in der Sitzung oder Besprechung. Einschließlich participantMinutes berichtet über Protokolle, die nach Verleger-Ebenen in der Sitzung oder Besprechung getrennt sind. Beachten Sie, dass die Aufnahme von publisherMinutes, subscriberMinutes, oder participantMinutes in einer Abfrage verlangsamt die Ergebnisse.

Die folgende Abfrage fordert partielle SessionSummary Ergebnisse:

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

POST-Anfragen an die Video Insights GraphQL API stellen

Alle Video Insights GraphQL-Anfragen werden an https://tools.vonage.com/video/insights-api/graphql.

Setzen Sie die Content-Type Kopfzeile zu application/json.

Setzen Sie die Authorization Kopfzeile zu Bearer <JWT>wobei das JWT für Ihre Vonage Video-Anwendung (unter Verwendung ihres privaten Schlüssels) wie in der folgenden Tabelle beschrieben generiert wird Video API-Authentifizierung.

Der POST-Body enthält ein JSON-Objekt mit einer einzelnen query Schlüssel, dessen Wert der GraphQL-String ist.

Beispiel einer cURL-Anfrage, um gestreamte abonnierte Minuten zu erhalten:

Ersetzen Sie YOUR_VIDEO_JWT mit einem gültigen JWT, das für Ihre Vonage Video-Anwendung generiert wurde (nach Aktivierung der Videofunktionen und Signierung mit dem privaten Schlüssel der Anwendung), APPLICATION_ID mit der ID dieser Anwendung (UUID) und START_DATE mit einem ISO-8601-Zeitstempel oder Epochenwert.

Antwort-Objekte

Antwortobjekte halten sich an das GraphQL-Schema und sind JSON-formatiert, enthalten aber nur Felder, die Sie in Ihren Anfragen angeben. Die curl Das obige Beispiel ergibt ein Antwortobjekt wie das folgende:

Die einfachste Möglichkeit, eine Vorschau auf das zu sehen, was Sie erwartet, ist das Hinzufügen verschiedener Filter, Gruppen und Felder zur Einblicke GraphiQL Explorerund beobachten Sie die Reaktion.

Paginierung in Abfragen verwenden

Sowohl die applicationData() und sessionData() APIs akzeptieren Paginierungsoptionen für alle Methoden, die Listen (Arrays) zurückgeben. Alle diese Methoden implementieren eine ResourceCollection Schnittstelle, die die folgenden optionalen Eigenschaften enthält:

• first (optional) - Die Anzahl der Einträge, die pro Seite zurückgegeben werden sollen. Die Höchstzahl beträgt 10 für Besprechungen und 1000 für alle anderen Ressourcensammlungen. Die Standardanzahl der zurückgegebenen Einträge beträgt 10 für Meetings und 50 für alle anderen Ressourcensammlungen.

• endCursor (optional) - Der String-Cursor, der zur Angabe der aktuellen Seite (Offset) verwendet wird. Diesen Cursorwert erhalten Sie von der pageInfo Eigenschaft für jede zurückgegebene Liste. Wenn Sie keine endCursor Wert, gibt eine Abfrage die erste übereinstimmende Ergebnisseite (den Anfang der Liste) zurück.

• Die pageInfo Objekt (das für jede Liste zurückgegeben wird) enthält die folgenden Eigenschaften:

  • hasNextPage - Boolesche Eigenschaft, die angibt, ob weitere Seiten verfügbar sind.
  • endCursor - Die Zeichenkette, die übergeben wird, um die nächste Seite zu erhalten.

  Die folgende Abfrage gibt zum Beispiel Informationen zur Paginierung zusammen mit den ersten 10 Übereinstimmungen zurück applicationData Ressourcen:

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

Die Antwort enthält Informationen zur Paginierung:

Verwenden Sie die endCursor Wert aus dieser Antwort ("aW5zaWdodHMtcmVzb3VyY2U6MTA==") als die endCursor Eingabe, die in der Abfrage verwendet wird, um die nächste Seite mit passenden Datensätzen zu erhalten:

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

Datenspeicherung und Latenzzeit

Einblicke / Einblicke Dashboard

Vorratsdatenspeicherung:

• Tägliche Aggregation: 90 Tage
• Monatliche Aggregation: 12 Monate

Anmerkungen:

• Die täglichen Aggregationsdaten werden auf der Grundlage von 00:00 - 23:59 PST/PDT berechnet.
• Die Aufbewahrungsfrist für die tägliche Aggregation für die Insights API und das Insights Dashboard wurde ab dem 12. August 2021 auf 90 Tage (von 60 Tagen) aktualisiert. Täglich aggregierte Daten für Videositzungen nach diesem Datum werden für 90 Tage verfügbar sein.

Erwartete Latenzzeit: 36 - 48 Stunden

Erweiterte Einblicke

Vorratsdatenspeicherung: 21 Tage

Anmerkung: Die Aufbewahrungsfrist richtet sich nach dem Erstellungszeitpunkt einer Besprechung innerhalb der Sitzung.

Erwartete Latenzzeit: 5 Minuten

Fehlercodes

Fehler sind in der Antwort enthalten, in einer errors Array, wie das folgende:

In der folgenden Tabelle sind die Fehlercodes und Beschreibungen aufgeführt. Siehe die message Eigenschaft des Fehlers für weitere Details.

Aktualisierungen

9. August 2024

Die folgenden Aktualisierungen werden der Insights-API hinzugefügt

Sie können Sitzungs-IDs suchen, ohne eine Anwendungs-ID in eine Abfrage aufzunehmen:

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

Neu not Betreiber für applicationData. Die not Filter können Sie bestimmte Daten aus Ihren Abfrageergebnissen ausschließen:

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

Neue Standort- und Browserdatenfilter für connections. Filter connections von country:

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

Neue Audiocodec- und Videocodec-Datenfilter. Sie können jetzt einen audioCodec Filter (zum PCMU, VP8, OPUS, TELEPHONE, oder OTHER), oder setzen Sie eine videoCodec Filter (zum VP8, H264, VP9, RTX, oder OTHER):

{
  application(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
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Neu mediaMode Filter für at sessionSummaries. Sie können nun eine mediaMode filtern bis ROUTED oder RELAYED:

{
  application(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
            }
          }
        }
      }
    }
  }
}