Überblick: Analytics API v1

Einführung

Das Analytics API ermöglicht Ihnen, Analysedaten für Ihr System zu erhalten Video Cloud Konten direkt. Sie können die integrierten Analyseberichte auch im Analytics-Modul von anzeigen Video Cloud Studio. Der programmgesteuerte Zugriff auf die Daten gibt Ihnen zusätzliche Flexibilität.

Siehe auch die API-Referenz.

Typische Anwendungen

Hier sind einige typische Anwendungen der API:

• Erstellen von benutzerdefinierten Diagrammen und Anzeigen
• Arbeiten Sie mit mehreren APIs zusammen, um beispielsweise Videodaten mit der CMS API für Videos mit den meisten Ansichten der letzten Woche
• Kombinieren Sie Ihre Videoanalysedaten mit anderen Site Analytics-Daten
• Für einige Beispiellösungen, siehe
  • Analytics für Wiedergabelisten
  • Analysen nach Land und Tag

Basis-URL

Die Basis-URL für die Analytics API ist:

  https://analytics.api.brightcove.com/v1

Headers

Authentifizierung erforderlich)

Das Analytics API verwendet die Brightcove OAuth-Dienst um Anrufe zu authentifizieren.

Sie müssen zuerst die Client-Anmeldeinformationen abrufen (a client_id und client_secret). Dies ist eine einmalige Operation, die unter Verwendung der OAuth Anmeldeinformationen UI. Sie können Client-Anmeldeinformationen direkt vom Brightcove OAuth-Dienst mithilfe von abrufen Locke, Postman, oder Insomnia.

Sie benötigen sowohl Analytics Read- als auch Video Read-Berechtigungen für Client-Anmeldeinformationen:

Wenn Sie Ihre Anmeldeinformationen direkt über das erstellen OAuth APIsind die erforderlichen Berechtigungen:

  [
    "video-cloud/analytics/read"
    "video-cloud/video/read"
  ]

Sie werden auch ein brauchen access_token, die mit dem erhalten wird client_id und client_secret und in einem Autorisierungsheader mit Ihrer API-Anfrage übergeben:

  Authorization: Bearer {access_token}

Das access_token nach fünf Minuten abläuft, müssen Sie für jede Anfrage einen anfordern oder sicherstellen, dass Ihr Token noch gültig ist. Sehen Zugriffstoken erhalten Für eine detaillierte Erklärung, wie Sie Zugriffsmarken erhalten, einschließlich Code-Beispiele.

Accept-Encoding: gzip (optional)

Wenn Sie diesen Header übergeben, wird die Antwort in komprimierter Form zurückgegeben. Dies kann die Leistung für große Berichte verbessern.

Caching

Aus Leistungsgründen werden API-Antworten für ungefähr 5-Minuten zwischengespeichert, obwohl die genaue Zeitspanne aufgrund verschiedener Faktoren variieren kann. Für jeden Analytics API Abfrage können Sie Informationen über den Cache aus den Antwortheadern abrufen:

Das 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 Überschriften 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 je länger eine Abfrage ausgeführt wird, desto länger zwischengespeichert wird und Berichte nur Echtzeitdaten (nicht abgestimmte stündliche Daten) abrufen wird nicht zwischengespeichert, solange die Daten abgeglichen werden (nur oder zusätzlich zu Echtzeitdaten). Finde einen vollständige Erklärung von Echtzeit- und abgeglichenen Daten wenn du möchtest; Die kurze Version ist, dass die Analytics API stützt sich auf zwei Datenbereiche:

• Echtzeit oder stündlich nicht abgestimmte Daten, die sofort zur Verfügung gestellt und für 32-Tage gespeichert werden
• abgeglichene Daten, die permanent gespeichert werden; Echtzeitdaten werden abgeglichen, um die Genauigkeit zu verbessern, und sie werden in den 24-Stunden im abgeglichenen Datenrepository gespeichert

Sie können die Ergebnisse auf abgeglichene oder Echtzeitdaten beschränken, indem Sie versöhnt Parameters.

So minimieren Sie das Zwischenspeichern:

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

Timeouts

Analytics API fordert eine Zeitüberschreitung nach 8 Minuten an, wenn diese nicht abgeschlossen ist. Wenn bei weniger als 8 Minuten Zeitüberschreitungen auftreten, liegt dies an einer clientseitigen Beschränkung.

Maximale Anzahl von Artikeln, die Sie zurückgeben können

Es können maximal eine Million Artikel zurückgegeben werden. In den meisten Fällen ist es unwahrscheinlich, dass Sie das Limit erreichen, aber wenn Sie Berichte über das Internet anfordern date Dimensionierung über einen großen Zeitraum ist es zum Beispiel möglich. Wenn Sie das Millionenlimit erreichen, müssen Sie die Anforderung ändern, um die Anzahl der zurückgegebenen Elemente zu reduzieren. Im Allgemeinen besteht die einfachste Möglichkeit darin, den Datenbereich zu reduzieren (mithilfe von from und to später beschriebene Parameter).

Gleichzeitige Anfragen

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

Beispielsweise:

1. Starten Sie eine API-Anfrage "A".
2. Starten Sie die API-Anfrage "B" für dasselbe Konto.
3. Anfrage "B" wird nicht abgeschlossen, bis "A" abgeschlossen ist.
4. Wenn die Anfrage "A" zu lange dauert, wird die Anfrage "A" mit der Fehlermeldung "Ihre Anfrage ist ausstehend; versuchen Sie es erneut" angezeigt.
5. Wenn die Anforderung "A" zu lange dauert, kann die Anforderung "B" den gleichen Fehler erhalten. Beachten Sie, dass die Anforderung "B" einen Fehler erhält, wenn die Zeit bis zum Abschluss von A + B größer als unser Zeitüberschreitungswert ist.

Wenn Sie mehrere gleichzeitige Anfragen erstellen, werden diese einzeln nacheinander in der Reihenfolge verarbeitet, in der sie eingehen.

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

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

Best Practices

Anfragetypen

Das Analytics API akzeptiert drei Anfragetypen

Daten (auch als Bericht bezeichnet)

Ein Bericht über einen oder mehrere Größe. Der Endpunkt für eine Berichtsanforderung ist:

  https://analytics.api.brightcove.com/v1/data?accounts={account_id(s)}&dimensions={dimensions}

EngageBericht

Detaillierte Interaktionsdaten, die für Zeiträume innerhalb der letzten 32-Tage verfügbar sind Sehen der Eingriffsabschnitt für weitere Informationen kontaktieren.

Video-Informationsendpunkt

Ein bestimmtes Teil der Analysedaten wird mit minimaler Latenz geliefert. Sehen Videodaten Endpunkt .

Wo Filter und Datumsbereiche kann auf Berichte angewendet werden. Für Berichtsanforderungen können zusätzliche Parameter angegeben werden 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 finden Sie jetzt in einem separaten Dokument: Übersicht über Dimensionen, Felder und Parameter.

EngageBerichte

Detaillierte Engagement-Berichte mit Ansichten für jeden 100. Teil von Videos (oder den Durchschnittswerten aller Videos für ein Konto oder player) sind für Zeiträume innerhalb der letzten 32 Tage verfügbar. (Anfragen nach Datumsbereichen außerhalb der letzten 32 Tage geben einen Fehler zurück.)

Kundenbindung

Verwenden Sie den Endpunkt, um Durchschnittswerte für die Interaktion mit angezeigten Videos zu erhalten:

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

Player Engagement

So erhalten Sie Durchschnittswerte für alle in a playerVerwenden 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 zu erhalten:

  
      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 Referenz für weitere Einzelheiten.