Einleitung
Das Analytics API Mit dieser Option können Sie Analysedaten für Ihre Video Cloud-Konten direkt abrufen. Sie können die integrierten Analyseberichte auch im Analysemodul von Video Cloud Studio anzeigen. Der programmgesteuerte Zugriff auf die Daten bietet Ihnen zusätzliche Flexibilität.
Siehe auch die API-Referenz.
Typische Anwendungen
Hier sind einige typische Verwendungen der API:
- Erstellen von benutzerdefinierten Diagrammen und Anzeigen
- Zusammen mit mehreren APIs arbeiten - zum Beispiel Videodaten mit dem abrufen CMS API für Videos mit den meisten Ansichten der letzten Woche
- Kombinieren Ihrer Videoanalysedaten mit anderen Websiteanalysedaten
- Einige Beispiellösungen finden Sie unter
Basis-URL
Die Basis-URL für die Analytics API ist:
<code class="language-http translate="No">https://analytics.api.brightcove.com/v1
Header
Authentifizierung erforderlich)
Das Analytics API verwendet die Brightcove OAuth-Service Anrufe zu authentifizieren.
Sie müssen zuerst die Kundenanmeldeinformationen abrufen (a client_id und client_secret). Dies ist ein einmaliger Vorgang, der mit dem Benutzeroberfläche für OAuth-Anmeldeinformationen. Sie können Clientanmeldeinformationen direkt vom Brightcove-OAuth-Dienst abrufen, indem Sie verwenden CURL , Postman , oder Insomnia.
Sie benötigen sowohl Analytics-Lese- als auch Video-Leseberechtigungen für Client-Anmeldeinformationen:
Wenn Sie Ihre Anmeldeinformationen direkt über die OAuth-API erstellen, sind die erforderlichen Berechtigungen:
[
"video-cloud/analytics/read"
"video-cloud/video/read"
]
Sie benötigen auch eine access_token, die mit dem client_id und erhalten wird client_secret und übergab einen Autorisierungsheader mit Ihrer API-Anfrage:
Authorization: Bearer {access_token}
Die access_token läuft nach fünf Minuten ab. Sie müssen also für jede Anfrage einen anfordern oder überprüfen, ob Ihr Token noch gültig ist. Sehen Zugriffstoken erhalten für eine detaillierte Erläuterung zum Abrufen von Zugriffstoken, einschließlich Codebeispielen.
Accept-Encoding: gzip (optional)
Wenn Sie diesen Header übergeben, wird die Antwort in komprimierter Form zurückgegeben. Dies kann die Leistung bei großen Berichten verbessern.
Zwischenspeichern
Aus Leistungsgründen werden API-Antworten für ungefähr 5 Minuten zwischengespeichert, obwohl die genaue Dauer von mehreren Faktoren abhängig sein kann. Für jeden Analytics API Abfrage, können Sie Informationen über den Cache aus den Antwortheadern erhalten:
Die Cache-Control gibt an, wie lange die Ergebnisse maximal in Sekunden zwischengespeichert werden (im obigen Beispiel 24 Sekunden). Die Last-Modified und Expires Header sagen Ihnen, wann der aktuelle Cache erstellt wurde und wann er abläuft.
In den meisten Fällen ist dies wahrscheinlich kein Problem, aber wenn die Aktualität der Analysedaten von entscheidender Bedeutung ist, sollten Sie wissen, dass eine Abfrage umso länger zwischengespeichert wird, je länger sie ausgeführt wird, und Berichte, die nur Echtzeitdaten (nicht abgeglichene stündliche Daten) abrufen werden nicht zwischengespeichert, solange die Daten abgeglichene Daten abrufen (nur oder zusätzlich zu Echtzeitdaten). Finde einen vollständige Erklärung von Echtzeit- und abgestimmten Daten wenn du möchtest; die kurze version ist, dass die Analytics API stützt sich auf zwei Datenbereiche:
- Echtzeit- oder stündliche, nicht abgeglichene Daten, die sofort verfügbar sind und 32 Tage lang gespeichert werden
- abgeglichene Daten, die dauerhaft gespeichert werden; Echtzeitdaten werden zur Verbesserung der Genauigkeit abgeglichen und alle 24 Stunden im abgeglichenen Daten-Repository gespeichert
Sie können die Ergebnisse auf abgeglichene oder Echtzeitdaten beschränken, indem Sie die versöhnt Parameter.
So minimieren Sie das Caching:
- Verwenden Sie die
reconciled=falseParameter zur Begrenzung der Ergebnisse auf Echtzeitdaten - Verwenden Sie einen kleinen Datumsbereich und stellen Sie sicher, dass der gesamte Zeitraum innerhalb der letzten 32 Tage liegt
Auszeiten
Timeout für Analytics-API-Anforderungen nach 8 Minuten, wenn sie nicht abgeschlossen sind. Wenn Sie Zeitüberschreitungen von weniger als 8 Minuten sehen, liegt die Ursache in einem clientseitigen Limit.
Maximale Anzahl von Artikeln, die Sie zurückgeben können
Die maximale Anzahl von Artikeln, die zurückgegeben werden können, beträgt eine Million. In den meisten Fällen ist es unwahrscheinlich, dass Sie das Limit erreichen, aber wenn Sie Berichte über die date Dimension über einen großen Zeitraum zum Beispiel möglich. Wenn Sie das Limit von Millionen Artikeln erreichen, müssen Sie die Anfrage ändern, um die Anzahl der zurückgegebenen Artikel zu reduzieren. Im Allgemeinen besteht die einfachste Möglichkeit darin, den Datenbereich zu reduzieren (mit from und to Parameter, die später besprochen werden).
Gleichzeitige Anfragen
Ein einzelnes Konto ist auf jeweils eine Anfrage beschränkt. Mehrere gleichzeitige Anforderungen werden nacheinander ausgeführt.
Zum Beispiel:
- Starten Sie eine API-Anfrage "A".
- API-Anfrage "B" für dasselbe Konto starten.
- Anforderung "B" wird erst abgeschlossen, wenn "A" abgeschlossen ist.
- Wenn die Anfrage "A" zu lange dauert, erhält die Anfrage "A" die Fehlermeldung "Ihre Anfrage ist ausstehend; versuchen Sie es erneut".
- Wenn Anforderung "A" zu lange dauert, kann dies dazu führen, dass Anforderung "B" denselben Fehler erhält. Beachten Sie, dass die Anforderung "B" einen Fehler erhält, wenn die Zeit zum Abschließen von A + B größer als unser Zeitüberschreitungswert ist.
Wenn Sie mehrere gleichzeitige Anfragen stellen, werden diese nacheinander in der eingegangenen Reihenfolge bearbeitet.
Anfragen, die mit einem "ausstehenden Fehler" zurückkehren, werden schließlich abgeschlossen und in unserem Cache gespeichert. Das bedeutet, dass zukünftige Anfragen für dieselben Daten fast sofort zurückgegeben werden, jedoch nur, wenn die Anfrage gestellt wird, bevor der Fünf-Minuten-Cache abläuft.
Ihre Systeme sollten den anstehenden Fehler behandeln, indem sie 2-4 Minuten warten und dieselbe Anfrage erneut stellen.
Empfohlene Vorgehensweise
Anfragearten
Das Analytics API akzeptiert drei Anforderungstypen
- Daten (auch als Bericht bezeichnet)
- Ein Bericht über einen oder mehrere dimensions. Der Endpunkt für eine Berichtsanforderung ist:
https://analytics.api.brightcove.com/v1/data?accounts={account_id(s)}&dimensions={dimensions} - Engagement-Bericht
- Detaillierte Engagement-Daten, die für Zeiträume innerhalb der letzten 32 Tage verfügbar sind. Sehen der Verlobungsabschnitt für mehr Details.
- Endpunkt für Videoinformationen
- Ein bestimmtes Stück Analysedaten, das mit minimaler Latenz bereitgestellt wird. Sehen Videodaten-Endpunkt für mehr Informationen.
Wo Filter und Datumsbereiche kann auf Berichte angewendet werden. Berichtsanforderungen können zusätzliche Parameter enthalten, die in detailliert sind dieses Dokument.
Abmessungen und Felder
Detaillierte Informationen zu Dimensionen und Feldern finden Sie jetzt in einem separaten Dokument: Übersicht über Dimensionen, Felder und Parameter.
Parameter
Detaillierte Informationen zu Parametern sind jetzt in einem separaten Dokument enthalten: Übersicht über Dimensionen, Felder und Parameter.
Engagementberichte
Detaillierte Interaktionsberichte, die die Aufrufe für jeden 100. Teil der Videos (oder die Durchschnittswerte aller Videos für ein Konto oder einen Spieler) zeigen, sind für Zeiträume innerhalb der letzten 32 Tage verfügbar. (Anfragen für Datumsbereiche außerhalb der letzten 32 Tage geben einen Fehler zurück.)
Kontointeraktion
Verwenden Sie den Endpunkt, um Durchschnittswerte für das Engagement bei angesehenen Videos zu erhalten:
https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id
Spieler-Engagement
Um Durchschnittswerte für alle in einem Player angesehenen Videos zu erhalten, verwenden Sie den Endpunkt:
https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/players/:player_id
Video-Engagement
Verwenden Sie den Endpunkt, um Interaktionsdaten für ein bestimmtes Video abzurufen:
https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/videos/:video_id
Live-Analyse
Das Analytics API Bietet zwei Endpunkte zum Abrufen von Analysen für Brightcove Live-Streams, entweder nach Zeitreihen oder nach Ereignissen. Siehe die Analytics API Reference für Details.