Überblick: Analytics API v1

Einführung

Analytics API Mit dem können Sie direkt Analysedaten für Ihre Video Cloud-Konten abrufen. Sie können die integrierten Analytics-Berichte auch im Analytics-Modul von Video Cloud Studio anzeigen. Der programmgesteuerte Zugriff auf die Daten bietet Ihnen zusätzliche Flexibilität.

Siehe auch die API-Referenz.

Typische Verwendungs

Hier sind einige typische Verwendungszwecke der API:

• Erstellen von benutzerdefinierten Diagrammen und Anzeigen
• Gemeinsam mit mehreren APIs arbeiten - zum Beispiel Videodaten mit den CMS API FOR Videos mit den meisten Ansichten der Vorwoche
• Kombinieren Sie Ihre Videoanalysedaten mit anderen Website-Analysedaten
• Für einige Beispiellösungen siehe
  • Analytics für Playlisten
  • Analytics nach Land und Tag

Basis-URL

Die Basis-URL für den Analytics API lautet:

  <code class="language-http translate="nein“ > https://analytics.api.brightcove.com/v1

Header

Authentifizierung (erforderlich)

Der Analytics API verwendet den Brightcove OAuth Service zur Authentifizierung von Anrufen.

Sie müssen zuerst Client-Anmeldeinformationen (a client_id und client_secret abrufen. Dies ist ein einmaliger Vorgang, der mit der Benutzeroberfläche von OAuth Credentialsdurchgeführt werden kann. Sie können Client-Anmeldeinformationen direkt vom Brightcove OAuth-Dienst mithilfe von abrufen CURL , Postman , oder Insomnia.

Sie benötigen sowohl die Berechtigung Analytics Read als auch Video Read für Client-Anmeld

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 ein access_token, das mit dem client_id und erhalten wird client_secret und in einem Authorization-Header mit Ihrer API-Anfrage übergeben wird:

  Authorization: Bearer {access_token}

Der access_token läuft nach fünf Minuten ab, Sie müssen also für jede Anfrage einen erhalten oder prüfen, ob Ihr Token noch gültig ist. Unter Zugriffstoken erhalten finden Sie eine detaillierte Erklärung, wie Sie Zugriffstoken erhalten, einschließlich Codebeispiele.

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.

Zwischenspeicherung

Aus Performance-Gründen werden API-Antworten für etwa 5 Minuten zwischengespeichert, wobei die genaue Zeitspanne basierend auf mehreren Faktoren variieren kann. Für jede Analytics API Abfrage können Sie Informationen über den Cache aus den AntwortheAdern abrufen:

Die Cache-Control gibt Ihnen die maximale Zeit an, für die die Ergebnisse in Sekunden zwischengespeichert werden (im obigen Beispiel 24 Sekunden). Das Last-Modified und Expires In den Headern wird angegeben, 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 von Analysedaten von entscheidender Bedeutung ist, sollten Sie wissen, dass je länger eine Abfrage läuft, desto länger wird sie zwischengespeichert, und Berichte, dass nur Echtzeitdaten (nicht abgestimmt) abgerufen werden, solange diejenigen, die versöhnte Daten abrufen (nur oder zusätzlich zu Echtzeitdaten). Finden Sie eine vollständige Erklärung der Echtzeit- und abgeskundeten Daten , wenn Sie möchten. Die Kurzversion besteht darin, dass die auf zwei Analytics API Datenmengen beruht:

• Echtzeit- oder stündliche nicht abgesunkene Daten, die sofort zur Verfügung gestellt und 32 Tage lang gespeichert werden
• abgestimmt Daten, die dauerhaft gespeichert werden; Echtzeitdaten werden abgestimmt, um die Genauigkeit zu verbessern, und alle 24 Stunden im abgeskundeten Daten-Repository gespeichert

Sie können die Ergebnisse mithilfe des abgeglichenen Parameters auf abgegebene oder Echtzeitdaten beschränken.

So minimieren Sie das Caching:

• Verwenden Sie den reconciled=false Parameter, um Ergebnisse auf Echtzeitdaten zu beschränken
• Verwenden Sie einen kleinen Datumsbereich und stellen Sie sicher, dass der gesamte Bereich innerhalb der letzten 32 Tage liegt

Timeouts

Analytics-API-Anfragen Timeout nach 8 Minuten, wenn sie nicht abgeschlossen sind. Wenn Sie Timeouts von weniger als 8 Minuten sehen, liegt die Ursache in einem clientseitigen Limit.

Maximale Gegenstände, die Sie zurückgeben

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 beispielsweise über einen großen Zeitraum Berichte über die date Dimension anfordern, ist dies möglich. Wenn Sie das Limit für Millionen Artikel erreichen, müssen Sie die Anfrage ändern, um die Anzahl der zurückgegebenen Artikel zu reduzieren. Im Allgemeinen ist der einfachste Weg, dies zu tun, die Reduzierung des Datenbereichs (unter Verwendung von from und to später diskutierte Parameter).

Gleichzeitige Anfragen

Ein einzelnes Konto ist auf eine Anfrage gleichzeitig beschränkt. Mehrere gleichzeitige Anfragen werden in Reihe ausgeführt.

Beispiel:

1. Starten Sie eine API-Anfrage „A“.
2. Startet die API-Anfrage „B“ für dasselbe Konto.
3. Die Anfrage „B“ wird erst abgeschlossen, wenn „A“ abgeschlossen ist.
4. Wenn die Anfrage „A“ zu lange dauert, erhält die Anfrage „A“ die Fehlermeldung „Ihre Anfrage steht aus; versuchen Sie es erneut“.
5. Wenn die Anforderung „A“ zu lange dauert, kann dies dazu führen, dass Anforderung „B“ denselben Fehler erhält. Beachten Sie, dass die Anfrage „B“ einen Fehler erhält, wenn die Zeit für die Fertigstellung von A + B größer ist als unser Timeout-Wert.

Wenn Sie mehrere gleichzeitige Anfragen stellen, werden diese nacheinander in der erhaltenen Reihenfolge bearbeitet.

Anfragen, die mit einem „ausstehenden Fehler“ zurückkehren, werden schließlich abgeschlossen und in unserem Cache gespeichert. Dies bedeutet, dass zukünftige Anfragen für dieselben Daten fast sofort zurückgegeben werden, jedoch nur, wenn die Anfrage vor Ablauf des fünfminütigen Cache gestellt wird.

Ihre Systeme sollten den ausstehenden Fehler behandeln, indem Sie 2-4 Minuten warten und dieselbe Anfrage erneut stellen.

Best-Practices

Arten von Anfragen

Der Analytics API akzeptiert drei Anfragetypen

Daten (auch Report genannt)

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}

Bindungsbericht

Detaillierte Interaktionsdaten, die für Zeiträume der letzten 32 Tage verfügbar sind. Weitere Einzelheiten finden Sie im Abschnitt „Engagement“ .

Endpunkt für Videoinformationen

Eine bestimmte Anzahl von Analysedaten, die mit minimaler Latenz bereitgestellt werden. Weitere Informationen finden Sie unter Endpoint für Videodaten .

Wo Filter und Datumsbereiche auf Berichte angewendet werden können. Berichtsanfragen können zusätzliche Parameter enthalten, die in diesem Dokument aufgeführtsind.

Dimensionen und Felder

Detaillierte Informationen zu Dimensionen und Feldern finden sich jetzt in einem separaten Dokument: Überblick über Dimensionen, Felder und Parameter.

Parameter

Detaillierte Informationen zu Parametern finden Sie jetzt in einem separaten Dokument: Überblick über Dimensionen, Felder und Parameter.

Bindungsberichte

Detaillierte Interaktionsberichte, die Ansichten für jeden 100. Teil von Videos (oder die Durchschnittswerte für alle Videos für ein Konto oder einen Spieler) zeigen, sind für Zeiträume der letzten 32 Tage verfügbar. (Anfragen für Datumsbereiche außerhalb der letzten 32 Tage geben einen Fehler zurück.)

Konto-Interaktion

Um Durchschnittswerte für das Engagement für angezeigten Videos zu erhalten, verwenden Sie den Endpoint:

  
      https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id
  

Spieler-Engagement

Verwenden Sie den Endpunkt, um Durchschnittswerte für alle in einem Player angezeigten Videos zu erhalten:

  
      https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/players/:player_id
  

Videobindung

Um Interaktionsdaten für ein bestimmtes Video zu erhalten, verwenden Sie den Endpoint:

  
      https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/videos/:video_id
  

Live-Analytik

Der Analytics API bietet zwei Endpunkte zum Abrufen von Analysen für Brightcove Live-Streams, entweder nach einer Zeitreihe oder nach Ereignis. Einzelheiten finden Analytics API Reference Sie im.