Insights-Dashboard & API
Die OpenTok Insights-API ist eine GraphQL-API. Mithilfe der Insights-API und des Insights-Dashboards können Sie Informationen zu Ihren OpenTok-Projekten und -Sitzungen abrufen.
Das Insights-Dashboard
Anmerkung: Bitte anklicken hier für Informationen über Datenspeicherung und Latenzzeiten.
Das „Insights Dashboard“-Widget liefert Daten auf Projektebene. Sie können es aufrufen, indem Sie sich bei Ihrem Vonage Video API-Konto und die Auswahl eines OpenTok-Projekts. Es enthält drei Registerkarten: „Nutzung“, „Qualität“ und „Fehler“ sowie Filter für den Datumsbereich, den Standort und die Endpunkte.
Auf der Registerkarte „Nutzung“ werden die verschiedenen Arten von Protokollen angezeigt, die im Rahmen des Projekts erstellt wurden. Sie können eine Karte mit den Orten einsehen, an denen Protokolle erstellt wurden, und nach Belieben mehrere Filter kombinieren.
Auf der Registerkarte „Qualität“ wird ein Histogramm der Videobitrate und der Latenz für die Streams innerhalb des Projekts angezeigt.
Auf der Registerkarte „Fehler“ werden die Fehlerquoten für Verbindungen, Herausgeber und Abonnenten angezeigt.
Die Daten auf den einzelnen Registerkarten werden anhand der oben getroffenen Auswahl gefiltert.
Insights API, Basis-URL und Authentifizierung
Die Insights API ist eine GraphQL-API mit dem Sie die Metadaten Ihrer Sitzungen auf Projekt- und Sitzungsebene einsehen können. GraphQL ist eine Alternative zum herkömmlichen REST-Ansatz für den Datenzugriff über HTTP. Es wurde 2012 von Facebook entwickelt und 2015 als Open Source veröffentlicht. Schauen Sie sich das an GraphQLs Anleitung für den Einstieg um mehr zu erfahren.
Die Basis-URL für die API lautet:
https://insights.opentok.com/graphql
Alle Anfragen erfolgen als HTTP-POST-Anfragen und werden mithilfe von X-OPENTOK-AUTH.
Erforschung des API-Schemas mit GraphiQL
Navigieren zu https://insights.opentok.com/ Wenn Sie Ihren Browser verwenden, gelangen Sie zur Insights-Instanz von GraphiQL, ein Tool, mit dem Sie das GraphQL-API-Schema erkunden können. Da das Tool API-Anfragen stellen kann, müssen Sie angemeldet sein, um es nutzen zu können.
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 zum Schema. Jedes Feld und jeder Objekttyp in der Dokumentation enthält eine Beschreibung. Klicken Sie sich durch die Dokumentation, um das Schema zu erkunden.
-
Auf der linken Seite der Seite befindet sich der Abfragebereich. In diesem Bereich können Sie Abfragen erstellen, die über die API ausgeführt werden sollen. Durch das Wechseln zwischen dem Dokumentationsbereich und dem Abfragebereich können Sie genau die Abfrage erstellen, die Sie benötigen, um nur die gewünschten Informationen zu erhalten. Da Sie angemeldet sind, wird die Authentifizierung für die Abfragen automatisch für Sie übernommen.
-
Unterhalb des Abfragefensters befindet sich das Fenster „Abfragevariablen“. Dies ist zwar nicht erforderlich, Sie können es jedoch nutzen, um Variablen für Ihre Abfrage festzulegen. Beispielsweise können Sie in diesem Fenster die folgenden Variablen definieren:
Kopieren{ "PROJECT_ID": 100, "START_TIME": "2019-01-01T08:00:00.000Z" }Verweisen Sie dann im Abfragebereich auf alle deklarierten Variablen:
Kopierenquery ($PROJECT_ID: Int!, $START_TIME: Date!) { project(projectId: $PROJECT_ID) { projectData( start: $START_TIME, interval: AUTO, sdkType: [JS, IOS, ANDROID], groupBy: [SDK_TYPE] ) { resources { sdkType intervalStart intervalEnd usage { streamedPublishedMinutes streamedSubscribedMinutes } } } } } -
Rechts neben dem Abfragebereich befindet sich der Antwortbereich. Durch Klicken auf die Schaltfläche „Ausführen“ im Tool wird die Abfrage im Abfragebereich ausgeführt, und im Antwortbereich werden die Ergebnisse angezeigt. Dies ist dieselbe Antwort, die Sie erhalten würden, wenn Sie die Abfrage programmgesteuert ausführen würden.
-
Klicken Sie schließlich auf die Schaltfläche Geschichte Schaltfläche oberhalb des Abfragefensters, um den Verlauf Ihrer letzten Abfragen anzuzeigen. Wenn Sie auf eines der angezeigten Elemente klicken, werden das Abfragefenster und das Fenster „Abfragevariablen“ mit diesen Daten gefüllt.
Anmerkung: Um die gewünschten Ergebnisse zu erzielen, achten Sie bitte darauf, Folgendes anzugeben: groupBy in Ihrer Abfrage.
Projektdaten abrufen
Anmerkungen:
- Bitte klicken Sie auf hier für Informationen über Datenspeicherung und Latenzzeiten.
- Insights unterstützt derzeit keine Verwendung mehrerer API-Schlüssel in derselben Abfrage. Bitte führen Sie für jedes Projekt eine separate Insights-Abfrage durch, um Informationen für mehrere Projekte bzw. API-Schlüssel abzurufen. Informationen zum programmgesteuerten Abruf von API-Schlüsseln und Geheimnissen auf Projektebene für einen Account finden Sie in unserer Dokumentation unter Informationen über Projekte einholen. Mit dieser Methode können Benutzer mit einem API-Schlüssel und Geheimcode auf Account-Ebene kann die Projektdetails-Objekt für ein einzelnes Projekt oder für alle Projekte des Accounts.
Die projectData Das Feld des Projekt-Objekts gibt den ProjectData Objekt,
das aggregierte Berichtsdaten auf Projektebene bereitstellt.
Sie müssen eine start Datum für die Abfrage. Dieser Wert kann eine Zeichenfolge im ISO-8601-Format
sein (z. B. "2019-10-15T23:43:34.023Z") oder einen Int-Wert,
der einen Epochen-Zeitstempel darstellt. Ganzzahlen mit bis zu 10 Stellen stehen für
Epochensekunden. Ganzzahlen mit mehr als 10 Stellen stehen für Epochenmillisekunden.
Die ProjectData Objekt enthält eine resources Eigenschaft, bei der es sich um ein
Array von Metric Objekte. Sie haben die Möglichkeit, Daten
nach SDK-Typ, SDK-Version, Land, Region, Browser oder Browserversion zu filtern und zu gruppieren.
Darüber hinaus haben Sie die Möglichkeit, die Interval an welcher Stelle Sie
die Daten segmentieren möchten (entweder DAILY, WEEKLY, oder MONTHLY). Beachten Sie, dass
wenn Sie die Interval, werden Ihnen nur Zeitintervalle angezeigt, für die Daten vorliegen.
Derzeit werden alle Daten unter diesem Objekt jede Nacht aktualisiert, sodass Sie keine
Änderungen in Echtzeit sehen werden.
Anmerkung: Die Filterung nach Region, SDK und Browser ist für Teilnehmer- und Archivierungsprotokolle nicht verfügbar.
Die Metric Das Objekt enthält Informationen zum Land, zur Region (US-Bundesstaat, falls
zutreffend), zum OpenTok-SDK-Typ und zur SDK-Version sowie zum Browser und zur Browserversion
(falls zutreffend) für die Ergebnisse. Das Metric Das Objekt enthält außerdem die folgenden
Eigenschaften:
-
usage— Informationen zu veröffentlichten Stream-Protokollen, abonnierten Stream-Protokollen, Archivnutzung, Übertragungsnutzung, SIP-Nutzung sowie zur Nutzung, aufgeschlüsselt nach Publisher-Stufen -
quality- Informationen zur Videoqualität -
errors— Die Fehlerquoten beim Herstellen von Verbindungen zu Sitzungen, beim Veröffentlichen und beim Abonnieren
Die folgende Abfrage fordert ProjectData-Ergebnisse an, die gestreamte veröffentlichte Minuten und gestreamte abonnierte Minuten für Kunden enthalten, die die OpenTok-SDKs für JavaScript, Android und iOS verwenden:
{
project(projectId: 12345678) {
projectData(
start: "2019-05-01T07:00:00.000Z",
interval: MONTHLY,
sdkType: [JS, ANDROID, IOS],
groupBy: SDK_TYPE
) {
resources {
intervalStart,
intervalEnd,
usage {
streamedPublishedMinutes,
streamedSubscribedMinutes
}
}
}
}
}
Beachten Sie, dass durch das Setzen des start Wenn Sie den Parameter auf 0 setzen, werden
die Ergebnisse ab den frühesten verfügbaren Datensätzen abgefragt.
Wichtig - bekanntes Problem: In einigen Tagesergebnissen vor dem 14. September 2023 sind die Angaben zum Browsernamen und zur Browserversion null oder leer. Ab dem 14. September 2023 sind die Werte enthalten.
Abrufen von Sitzungsdaten (Erweiterte Einblicke)
Anmerkung: Bitte anklicken hier für Informationen über Datenspeicherung und Latenzzeiten.
Das ist wichtig: Abfragen von Sitzungsdaten sind verfügbar für Advanced Insights-Kunden nur.
Die sessionData Feld des project Objekt gibt die SessionData Objekt.
Dieses Objekt enthält zwei Felder: sessions und sessionSummaries.
Detailinformationen zur Sitzung
Die sessions Feld gibt eine Sessions Objekt. Übergeben Sie die Sitzungs-IDs als
die sessionIds Argument (ein Array von übereinstimmenden Zeichenketten). Die Sessions Objekt
enthält ein resources Eigenschaft, die ein Array von Session Objekte.
Die Session Objekt hat die folgenden Eigenschaften:
-
mediaMode- Der Medienmodus für die Sitzung. Dieser ist"routed"für Sitzungen, die über den OpenTok Media Router geleitet werden, oder"relayed"für direktes Peer-to-Peer-Streaming. -
publisherMinutes— Die Gesamtzahl der gestreamten Minuten für alle Publisher in der Sitzung. Beachten Sie, dass die Einbeziehung dieses Feldes die Anzeige der Abfrageergebnisse verlangsamt. -
subscriberMinutes— Die Gesamtzahl der gestreamten Minuten für alle Abonnenten in der Sitzung. Beachten Sie, dass die Einbeziehung dieses Feldes die Anzeige der Abfrageergebnisse verlangsamt. -
participantMinutes— Die Gesamtzahl der Minuten, aufgeschlüsselt nach Herausgeber-Stufen, über alle Sitzungen der Tagung hinweg. -
meetings- Eine Reihe vonMeetingObjekte. Eine OpenTok-Sitzung kann mehrere Besprechungen umfassen. Sobald sich der erste Client mit der Sitzung verbindet, beginnt die erste Besprechung. Die Besprechung endet, wenn mindestens 10 Minuten lang keine Verbindungen in der Sitzung bestehen. Sobald sich ein Client erneut verbindet, beginnt eine neue Besprechung. Jedes „Meeting“-Objekt enthält die folgenden Eigenschaften:-
subscriberMinutes— Die Gesamtzahl der Teilnehmerminuten in der Besprechung. -
publisherMinutes— Die Gesamtzahl der Minuten, die die Herausgeber in der Sitzung verbracht haben. -
participantMinutes— Die Gesamtzahl der Minuten, aufgeschlüsselt nach den verschiedenen Herausgeber-Stufen innerhalb der Besprechung. -
connections— Ein Array von „Connection“-Objekten, das jeden mit der Sitzung verbundenen Client (während des Meetings) definiert. Zu den Eigenschaften des „Connection“-Objekts gehören Informationen zum verwendeten OpenTok-Client SDK, zum verwendeten Browser (bei Web-Clients), Informationen zu Publishern und Subscribern sowie weitere Angaben. -
publishers— Ein Array von Publisher-Objekten. Zu den Eigenschaften des Publisher-Objekts gehören Informationen zum Stream des Publishers, zu den Abonnenten des Streams, zu den Stream-Statistiken und vieles mehr. (Die Stream- Statistiken sind im Add-on „Advanced Insights“ enthalten. Siehe Abrufen von Stream-Statistiken.) -
subscribers— Ein Array von „Subscriber“-Objekten, das Details zu jedem Abonnenten enthält. Zu den Eigenschaften des „Subscriber“-Objekts gehören Informationen zum Stream des Abonnenten, Stream-Statistiken und vieles mehr. (Die Stream- Statistiken sind im Add-on „Advanced Insights“ enthalten. Siehe Abrufen von Stream-Statistiken.) -
createdAtunddestroyedAt— 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 fordert einige Publisher-Details zu zwei OpenTok-Sitzungen an:
{
project(projectId: 12345678) {
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 Die Eigenschaft des „MeetingPublishers“-Objekts ist ein Array von „Publisher“-Objekten.
Und das „Publisher“-Objekt enthält ein „PublisherStreamStatsCollection“-Objekt.
Dieses Objekt ist eine Ressourcensammlung, und seine resources Die Eigenschaft ist ein Array aus
„PublisherStats“-Objekten. Jedes „PublisherStats“-Objekt enthält Stream-Statistiken für den
Publisher, die während des Streaming-Vorgangs des Publishers in regelmäßigen Abständen (alle 30 Sekunden)
erfasst werden. Diese Statistiken umfassen Daten zur Audio- und Videolatenz, zur Audio- und Video-
Bitrate, zur Paketverlustrate bei Audio und Video, zur Videoauflösung, zu den Audio- und Video-Codecs
sowie dazu, ob der Stream zum Zeitpunkt der Erfassung der Stream-Statistiken Audio und Video enthielt.
Die folgende Abfrage ruft die periodischen Audio- und Video-Bitrate-Statistiken für Publisher in einer OpenTok-Sitzung ab:
{
project(projectId: 12345678) {
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 Eine Eigenschaft des „MeetingSubscribers“-Objekts ist ein Array
aus „Subscriber“-Objekten, und jedes dieser Objekte enthält eine „SubscriberStreamStatsCollection“-Ressourcensammlung,
die entsprechende Stream-Statistiken für einen Teilnehmer umfasst.
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 Sitzung der Tagung). Das MeetingSummary Das Objekt enthält
Informationen zur Gesamtzahl sowie zur Anzahl der gleichzeitig aktiven Streams, Verbindungen
und Teilnehmer der Besprechung.
Sowohl die SessionSummary Objekt und MeetingSummary Objekte umfassen publisherMinutes,
subscriberMinutesund participantMinutes Eigenschaften. Diese geben die Gesamtzahl der Minuten an,
die für alle Sender und Empfänger in der Sitzung oder dem Meeting gestreamt wurden. Darunter fallen participantMinutes
Zeigt Protokolle an, die nach den Herausgeber-Stufen der Sitzung oder des Treffens unterteilt sind. Beachten Sie, dass die Einbeziehung von
publisherMinutes, subscriberMinutes, oder participantMinutes in einer Abfrage verlangsamt die Ergebnisse.
Die folgende Abfrage fordert partielle SessionSummary Ergebnisse:
{
project(projectId: 12345678) {
sessionData {
sessionSummaries (
start: "2019-05-01T07:00:00.000Z",
) {
resources {
sessionId
meetings {
resources {
maxConcurrentStreams
maxConcurrentStreams
maxConcurrentSubscribers
totalStreams
totalConnections
}
}
}
}
}
}
}
SIP-Qualitätsmetriken
Die folgende Abfrage liefert nur die Mindeststatistiken zur SIP-Qualität:
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
}
}
}
}
}
}
}
}
}
}
}
}
Diese Abfrage liefert grundlegende SIP-Informationen ohne Statistiken:
project(projectId: 12345678) {
sessionData {
sessions(sessionIds: [
"1_MX4xMDB-fjE1Mzg4NzA0MjExNDd-VjRuSWhpn4"
]) {
resources {
meetings {
resources {
connections {
resources {
sipCalls(first: 10) {
resources {
sipCallId
connectionId
conferenceId
createdAt
}
}
}
}
}
}
}
}
}
}
Um eine vollständige SIP-Qualitätsstatistik abzurufen, verwenden Sie die folgende Abfrage:
{
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
}
}
}
}
}
}
}
}
}
}
}
}
Antwort-Objekte
Antwortobjekte entsprechen dem GraphQL-Schema und liegen im JSON-Format vor, enthalten jedoch
nur die Felder, die Sie in Ihren Anfragen angeben. Die curl
Das obige Beispiel führt zu einem Antwortobjekt, das wie folgt aussieht:
{
"data":{
"project":{
"projectData":{
"resources":[
{
"usage":{
"streamedSubscribedMinutes":3189
}
}
]
}
}
}
}
Am einfachsten können Sie sich einen Überblick darüber verschaffen, was Sie erwartet, indem Sie verschiedene Filter, Gruppen und Felder zur Einblicke GraphiQL Explorer, und die Reaktion zu beobachten.
Paginierung in Abfragen verwenden
Sowohl die projectData() und sessionData() APIs unterstützen 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 Obergrenze liegt bei 10 für Besprechungen und bei 1000 für alle anderen Ressourcensammlungen. Standardmäßig werden 10 Einträge für Besprechungen und 50 für alle anderen Ressourcensammlungen zurückgegeben. -
endCursor(optional) — Der String-Cursor, der zur Angabe der aktuellen Seite (Offset) verwendet wird. Rufen Sie diesen Cursorwert aus derpageInfoEigenschaft für jede zurückgegebene Liste. Wenn Sie keineendCursorWert, gibt eine Abfrage die erste passende Ergebnisseite zurück (den Anfang der Liste).
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 liefert beispielsweise Paginierungsinformationen sowie die ersten 10
treffenden ProjectData Ressourcen:
{
project(projectId: 12345678) {
projectData(
start: "2024-05-01T07:00:00.000Z",
first: 10,
interval: MONTHLY,
) {
pageInfo {
hasNextPage
endCursor
}
resources {
usage {
streamedPublishedMinutes
}
}
}
}
}
Die Antwort enthält Informationen zur Paginierung:
{
"data": {
"project": {
"projectData": {
"pageInfo": {
"hasNextPage": true,
"endCursor": "aW5zaWdodHMtcmVzb3VyY2U6MTA=="
},
"resources": [
{
"usage": {
"streamedPublishedMinutes": 56554.83333333332
}
},
...
Verwenden Sie die endCursor Wert aus dieser Antwort ("aW5zaWdodHMtcmVzb3VyY2U6MTA==")
als das endCursor Eingabe, die in der Abfrage verwendet wird, um die nächste Seite der
treffenden Datensätze abzurufen:
{
project(projectId: 12345678) {
projectData(
start: 0,
first: 10,
interval: MONTHLY,
endCursor: "aW5zaWdodHMtcmVzb3VyY2U6MTA=="
) {
pageInfo {
hasNextPage
endCursor
}
resources {
usage {
streamedPublishedMinutes,
streamedSubscribedMinutes
}
}
}
}
}
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
Anmerkung: Eine einzelne Sitzung kann mehrere Besprechungen haben. Eine neue Besprechung wird festgelegt, wenn die Sitzung 10 Minuten lang nicht genutzt wurde. Bitte beachten Sie unsere Dokumentation über Sitzungen vs. Meetings für weitere Informationen.
Fehlercodes
Fehler sind in der Antwort enthalten, in einer errors Array, wie das folgende:
"errors": [
{
"message": "You must provide a valid project ID.",
"locations": [
{
"line": 2,
"column": 3
}
],
"path": [
"project"
],
"errorCode": 1008
}
]
In der folgenden Tabelle sind die Fehlercodes und deren Beschreibungen aufgeführt. Siehe die
message Eigenschaft des Fehlers für weitere Details.
| Fehlercode | Fehlerbeschreibung |
|---|---|
| 1000 | Es wurde ein ungültiger API-Schlüssel angegeben. |
| 1001 | Es wurde keine gültige Authentifizierung angegeben. |
| 1002 | Ungültiger Datumsbereich. |
| 1003 | Ungültiger Parameter. Es ist nur ein Datumsintervall erlaubt. |
| 1004 | Ungültige Parameter. |
| 1005 | Ungültiger Parameter. |
| 1006 | Ungültiger Parameter. Der Wert muss eine ganze Zahl sein. |
| 1007 | Ungültiger Parameter zur Angabe einer OpenTok-SDK-Versionsnummer. Das erforderliche Format lautet 0.0.0. |
| 1008 | Sie müssen eine gültige Projekt-ID angeben. |
| 1009 | Ungültiger Parameter. |
| 1010 | Ungültiger Parameter übergeben. Der Parameter kann nur einen Wert annehmen. |
| 1011 | Ungültiges Token. |
| 1012 | Interner Serverfehler. |
| 1013 | Es fehlt ein obligatorischer Parameter. |
| 1014 | Die angegebene Abfrage erfordert die Erweiterte Einblicke Add-on. |
| 1015 | Die angegebene Projekt-ID wurde nicht gefunden. |
| 1016 | Die Sitzung ist abgelaufen. |
| 1017 | Die angegebene Sitzung wurde nicht gefunden. |
| 1018 | Sie müssen mindestens eine Sitzungs-ID in das Eingabefeld eingeben. |
| 1019 | Das Token stimmt nicht mit dem API-Schlüssel überein. |
| 1020 | Das Token kann nicht validiert werden. |
| 1021 | Sie sind nicht berechtigt, Daten aus diesem Projekt einzusehen. |
| 1022 | Typenfehler. Siehe Einzelheiten in der message String. |
POST-Anfragen an die OpenTok-GraphQL-API senden
Alle OpenTok-GraphQL-Anfragen werden an https://insights.opentok.com/graphql.
Setzen Sie die content-type zu application/json.
Für alle Anfragen ist eine Authentifizierung mittels eines X-OPENTOK-AUTH Header. Setzen Sie diesen
Header auf ein JWT-Token mit project als die ist und die OpenTok-Projekt-ID
als iss. Signieren Sie das Token mit dem geheimen Schlüssel des OpenTok-Projekts.
Siehe Authentifizierung.
Der POST-Body enthält ein JSON-Objekt
mit einem Schlüssel und einem Wert. Der Schlüssel lautet query, und der Wert
ist die JSON-ähnliche GraphQL-Zeichenkette (wie beispielsweise diese), die Sie mit dem
GraphiQL-Tool erstellen.
Die folgenden curl Der Befehl führt eine GraphQL-Abfrage durch, um die gestreamten, abonnierten
Minuten abzurufen:
Ersetzen Sie die Werte für die YOUR_OT_JWT und YOUR_OT_PROJECT_API_KEY Variablen.
Um diese zu erhalten, siehe die REST-API-Authentifizierung
Dokumentation und melden Sie sich bei Ihrem Vonage Video API-Konto.
Das obige Beispiel führt zu einem Antwortobjekt, das wie folgt aussieht:
{
"data":{
"project":{
"projectData":{
"resources":[
{
"usage":{
"streamedSubscribedMinutes":3189
}
}
]
}
}
}
}
Berechnung der Teilnehmerminuten
Was ist die genaueste Methode zur Berechnung der Arbeitsminuten der Teilnehmer für einen bestimmten Zeitraum im Rahmen der Abrechnung?
Um die genaue Anzahl der Minuten zu ermitteln, die in einem bestimmten Zeitraum generiert wurden, verwenden Sie „Projektdaten“. Wenn Sie in der Abfrage Sitzungszusammenfassungen zur Angabe eines Zeitraums verwenden, umfassen die Ergebnisse alle Sitzungen, die innerhalb dieses Zeitraums erstellt wurden. Wird eine Sitzung wiederverwendet, umfassen die Ergebnisse alle Sitzungen, die mindestens eine innerhalb des angegebenen Zeitraums erstellte Besprechung enthalten, wobei die Gesamtzahl der Minuten für die gesamte Sitzung und nicht nur für diesen Zeitraum angezeigt wird.
Das heißt: Bei Verwendung einer Abfrage zur Sitzungszusammenfassung beziehen sich die Minuten im Falle einer Wiederverwendung einer Sitzung innerhalb des angegebenen Zeitraums nicht nur auf diesen spezifischen Zeitraum, sondern auf die gesamte Sitzung, was auch Ergebnisse umfassen kann, die außerhalb des Zeitraums liegen.
Bei der Verwendung der Projektdatenabfrage umfassen die Ergebnisse Tagesdaten von 00:00 Uhr PST bis 00:00 Uhr PST des folgenden Tages. Sie sollten berücksichtigen, dass die Abfrage um 00:00 Uhr PST beginnen sollte; andernfalls liefert sie immer einen Tag mehr Daten als erwartet.
Betrachten wir zum Beispiel diese beiden Abfragen zu Projektdaten:
projectData(
start: "2023-12-30T08:00:00.00Z",
end: "2023-12-31T08:00.00.00Z"
interval: AUTO
)
projectData(
start: "2023-12-30T08:00:00.00Z",
end: "2023-12-31T03:00.00.00Z"
interval: AUTO
)
Für diese beiden Anfragen umfassen die Ergebnisse Daten nur für einen Tag in den Ergebnissen.
In diesem Fall verschiebt die Zeitzonenanpassung „2023-12-30T08:00:00.00Z“ effektiv auf den Beginn des 30. Dezembers in PST (Mitternacht PST). Da die Endzeit in PST Mitternacht des 31. ist, umfassen die Ergebnisse nur einen Tag.
Betrachten Sie jedoch einmal diese Abfrage zu Projektdaten:
projectData(
start: "2023-30-30T07:00:00.00Z",
end: "2023-01-31T08:00.00.00Z"
interval: AUTO
)
Die Abfrage liefert Daten vom 30. und 31. Dezember 2023.
Der Zeitstempel „2023-12-30T07:00:00.00Z“ ist in UTC angegeben; in PST ergibt sich daraus „2023-12-29T11:00:00.00PST“, was dem 29. Dezember entspricht. Aufgrund der Zeitverschiebung zur PST umfasst die Anfrage, wenn sie Daten vom „2023-12-30T07:00:00.00Z“ (UTC) enthält, effektiv den Zeitraum vom 30. bis zum 31. Dezember und schließt somit beide Tage im Ergebnis ein.
Die Ergebnisse werden also Daten für den 30. und 31. Dezember 2023 enthalten.
{
project(projectId: XXXX) {
projectData(
start: "2022-11-28T15:57:07.529Z"
interval: AUTO
) {
resources {
intervalStart
intervalEnd
sdkType
usage {
participantMinutes {
from1To2Publishers
from3To6Publishers
from7To8Publishers
from1To4Publishers
from5To8Publishers
from1To8Publishers
from1To10Publishers
from9To10Publishers
from11To35Publishers
from11To20Publishers
from11To35Publishers
from36PlusPublishers
from21To35Publishers
from36To40Publishers
from41PlusPublishers
from1To25Publishers
from3To25Publishers
from26To35Publishers
}
streamedPublishedMinutes
}
}
}
}
}
Aus diesen Gründen ist es besser, die Besprechungsebene heranzuziehen, um ein genaueres Ergebnis zu erhalten:
{
project(projectId: 47521921) {
sessionData {
sessionSummaries(start: "2019-05-01T07:00:00.000Z") {
resources {
sessionId
meetings {
resources {
maxConcurrentStreams
maxConcurrentStreams
maxConcurrentSubscribers
totalStreams
totalConnections
participantMinutes {
from1To2Publishers
from3To6Publishers
from7To8Publishers
from1To4Publishers
from5To8Publishers
from1To8Publishers
from1To10Publishers
from9To10Publishers
from11To35Publishers
from11To20Publishers
from11To35Publishers
from36PlusPublishers
from21To35Publishers
from36To40Publishers
from41PlusPublishers
from1To25Publishers
from3To25Publishers
from26To35Publishers
}
}
}
}
}
}
}
}
Zusätzliche Abfragen
Sie können nach einer Sitzungs-ID suchen, ohne eine Projekt-ID in eine Abfrage aufzunehmen:
{
project(sessionIds: "2_MX4xMDB-fjE3MTMyMTMwNDQ1NDV-Z29CLzhyejNha1N2M2RaV255Sno1RTZNfn5-") {
sessionData {
sessions {
resources {
mediaMode
sessionId
meetings {
totalCount
pageInfo {
hasNextPage
endCursor
}
resources {
meetingId
createdAt
destroyedAt
}
}
}
}
}
}
}
Sie können die not Betreiber für 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
}
}
}
}
}
Sie können Verbindungen nach Standort und Browser filtern:
{
project(sessionIds: "2_MX4xMDB-fjE3MTMyMTMwNDQ1NDV-Z29CLzhyejNha1N2M2RaV255Sno1RTZNfn5-") {
sessionData {
sessions {
resources {
meetings {
resources {
connections(country: "US") {
totalCount
}
}
}
}
}
}
}
}
Sie können eine audioCodec Filter (zum PCMU, VP8, OPUS, TELEPHONE, oder OTHER), oder setzen Sie eine videoCodec Filter (zum VP8, H264, VP9, RTX, oder 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
}
}
}
}
}
}
}
}
}
}
}
Sie können eine mediaMode filtern bis ROUTED oder 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
}
}
}
}
}
}
}
Beispiel-App und weitere Beispielabfragen
Die Beispiel für ein Insights-Dashboard Das Projekt auf GitHub ist eine Node-Anwendung, die die OpenTok Insights-API nutzt, um Informationen zu OpenTok-Projekten grafisch darzustellen. Es enthält außerdem eine Reihe von Beispielabfragen für GraphQL.