Überblick: Dimensionen, Felder und Parameter

Abmessungen und Felder

Dimensionen sind die primären Daten-Buckets für Analysen. Um vollständige Anleitungen zu den einzelnen Dimensionen anzuzeigen, klicken Sie auf den Dimensionsnamen in der Liste unten.

Wählen Sie unten die Dimension(en) aus, um die Felder anzuzeigen, die dafür zurückgegeben werden können. Sie können auch auf klicken Eine Anfrage stellen Schaltfläche, um eine Musteranfrage zu stellen und die Ergebnisse anzuzeigen. Wenn Sie mehrere inkompatible Dimensionen auswählen, wird eine entsprechende Meldung angezeigt.

Eingang

Wählen Sie Dimension(en) aus, um einen Bericht zu erstellen:

Felder zur Rückgabe:

(verwendet ein Brightcove-Beispielkonto)

Ausgabe

Früheste `from` Datum für diese Dimensionskombination:

Beispiel-API-Anfrage:

Antwortdaten

  Response will appear here...

Hinweise

Standardmäßig, video_view ist das einzige zurückgegebene Feld - andere Felder werden nur zurückgegeben, wenn sie im Wert des angegeben sind fields Parameter.
Wenn Sie ein zurückzugebendes Feld angeben, das für die Dimension oder Dimensionskombination nicht unterstützt wird, UNSUPPORTED_FIELD_COMBINATION_ERROR Fehler wird zurückgegeben.
Die bytes_delivered Das Feld enthält alle Daten, die von Video Cloud an Clients geliefert werden, einschließlich Videodaten, Bilder, Textspuren und andere Assets sowie den Player-Code selbst. Einige dieser Daten stammen aus CDNs und sind möglicherweise bis zu 3 Tage lang nicht verfügbar.
Zusätzlich zu den angezeigten Feldern für die video Dimension, Sie können auch zurückkehren video.custom_fields.{field_name}

Beispielanfrage

Ein typischer Anwendungsfall, um einen Bericht zu mehreren Dimensionen zu erhalten: Sie möchten eine Aufschlüsselung der Videoaufrufe zwischen Desktop- und Mobilgeräten und möchten außerdem wissen, wie viele der Mobilgeräteaufrufe auf iOS- bzw. Android-Geräten erfolgten und wie viele der Desktops Ansichten waren auf Macs im Vergleich zu Windows-Rechnern. Derzeit gibt es im Studio Analytics-Modul keinen Standardbericht, der diese Informationen enthält. Sie können ihn jedoch über diesen Bericht abrufen Analytics API Anruf:

  https://analytics.api.brightcove.com/v1/data?accounts=57838016001&dimensions=video,device_type,device_os&from=2014-01-01&to=2014-04-01&fields=video_view

(In diesem Fall bitten wir um Videoaufrufe für den Zeitraum vom 1. Januar bis 1. April 2014.)

Beispiel mit cURL

Wenn Sie die API mit cURL ausprobieren möchten, hier ein paar Hinweise:

Sie müssen zuerst eine Zugangstoken
Da die URL für die Anfrage immer URL-Parameter enthält, müssen Sie sie in Anführungszeichen (einfach oder doppelt) setzen.

Probe

Hier ist ein cURL-Beispielbefehl:

  curl -s --header "Authorization: Bearer $ACCESS_TOKEN" \
  "https://analytics.api.brightcove.com/v1/data?accounts={account_id}&dimensions=video&from=2017-04-04&limit=100"

Wenn Sie ersetzen $ACCESS_TOKEN mit einem gültigen Zugriffstoken und {account_id} mit Ihrer Konto-ID sollte diese Anfrage funktionieren. Beachten Sie, dass Sie verwenden können diese Beispiel-App um ein Zugriffstoken zu generieren.

Unterstützte Dimensionskombinationen

Zur schnellen Orientierung zeigt die folgende Tabelle Bemaßungskombinationen, die unterstützt werden oder nicht. Beachten Sie, dass es einige Fälle gibt, in denen mehr als zwei Dimensionen verwendet werden können. Sie können diese herausfinden, indem Sie die Abmessungen und Felder Werkzeug oben.

Unterstützte Dimensionskombinationen
	`Konto`	`browser_typ`	`stadt`	`Land`	`Datum`	`Datum_Stunde`	`Zieldomäne`	`Zielpfad`	device_os	`Gerätehersteller`	`device_type`	`live_stream`	`Spieler`	referrer_domain	`Region`	`suchbegriffe`	`soziale_plattform`	`Quelltyp`	`Video`
`account`	n / A
`browser_type`		n / A
`city`			n / A
`country`				n / A
`date`					n / A
`date_hour`						n / A
`destination_domain`							n / A
`destination_path`								n / A
`device_os`									n / A
`device_manufacturer`										n / A
`device_type`											n / A
`live_stream`												n / A
`player`													n / A
`referrer_domain`														n / A
`region`															n / A
`search_terms`																n / A
`social_platform`																	n / A
`source_type`																		n / A
`video`																			n / A

URL-Parameter

Analytics-API-Berichte unterstützen die folgenden URL-Parameter.

URL-Parameter
Parameter	Beschreibung	Erforderlich	Werte	Standardwert
`account`	Die Konten, über die Sie berichten möchten	Ja	eine oder mehrere Konto-IDs als durch Kommas getrennte Liste	keiner
`dimensions`	Die Dimension(en), über die berichtet werden soll	Ja	eine oder mehrere Dimensionen als kommagetrennte Liste (einige Kombinationen sind nicht gültig - verwenden Sie das interaktive Tool hier, um festzustellen, ob eine Kombination gültig ist)	keiner
`where`	Wird verwendet, um Filter für Berichte anzugeben	nein	{Dimension}=={Wert} - eine oder mehrere als durch Semikolon getrennte Liste. Der Wert ist ein oder mehrere Werte für die primäre Metrik der betreffenden Dimension. Zum Beispiel: `video==video_id`, `country=country-code`, oder `viewer=viewer_id`(im letzten Fall variiert die Form der viewer_id, je nachdem, ob Sie selbst eine Art von Viewer_ID erfassen und senden, oder abhängig von dem vom Analysesystem generierten Wert).	keiner
`limit`	Anzahl der zurückzugebenden Artikel	nein	positive ganze Zahl	10
`offset`	Anzahl der zu überspringenden Elemente	nein	positive ganze Zahl	0
`sort`	Feld zum Sortieren von Elementen	nein	jedes Feld, das von der Anfrage zurückgegeben wird	video_view
`fields`	Felder zum Zurückgeben	nein	variiert je nach Dimension, über die Sie berichten	Video, Videoansicht
`format`	Format, um Ergebnisse in zurückzugeben	nein	json (Standard) \| csv \| xlxs	json
`reconciled`	Falls vorhanden, werden die Ergebnisse auf historische oder Echtzeitdaten beschränkt. Analysedaten stammen aus mehreren Quellen: Einige werden vom Player gesendet, andere werden von CDNs und dem Video Cloud-System gesammelt. Um Analysen so schnell wie möglich bereitzustellen, beginnen wir mit der Bereitstellung von "Echtzeit"-Daten, sobald diese verfügbar sind, und passen die Analysen später an, wenn Daten aus allen Quellen gesammelt und verarbeitet wurden. Die vollständig verarbeiteten Daten werden als abgestimmte	nein	wahr \| falsch	wahr
`from`	Der Anfang des Datumsbereichs für die Anfrage	nein	Einer der folgenden: Ein ISO 8601-Datum (JJJJ-MM-TT) Epochenzeit in Millisekunden (Beispiel: 1659641316719 [= Donnerstag, 4. August 2022, 19:28:36 .719 Uhr GMT]). Siehe den Epoch-Zeitkonverter. Eine Zeichenfolge: `from=alltime` +/- relative Daten in Tagen (d), Wochen (w) oder Monaten (m) — Beispiel: `from=-6m&to=%2B2w`(der Zeitraum von vor 6 Monaten bis 2 Wochen danach — beachten Sie, dass das Pluszeichen URI-kodiert sein muss als `%2B`) Für Engagement-Endpunkte sind nur Daten innerhalb der letzten 32 Tage zulässig oder wenn reconciled=false.	-30d
`to`	Das Ende des Zeitraums für die Anfrage	nein	Einer der folgenden: Ein ISO 8601-Datum (JJJJ-MM-TT) Epochenzeit in Millisekunden (Beispiel: 1659641316719 [= Donnerstag, 4. August 2022, 19:28:36 .719 Uhr GMT]). Siehe den Epoch-Zeitkonverter. Eine Zeichenfolge: `to=now` +/- relative Daten in Tagen (d), Wochen (w) oder Monaten (m) — Beispiel: `from=-6m&to=%2B2w`(der Zeitraum von vor 6 Monaten bis 2 Wochen danach — beachten Sie, dass das Pluszeichen URI-kodiert sein muss als `%2B`) Für Engagement-Endpunkte sind nur Daten innerhalb der letzten 32 Tage zulässig oder wenn reconciled=false.	jetzt

Konten

Die Video Cloud-Konten, für die Sie einen Bericht erstellen möchten, werden mit dem accounts Parameter. Zum Beispiel:

  https://analytics.api.brightcove.com/v1/data?accounts={account1_id,account2_id}

Wo Filter

Die allgemeine Syntax für Filter lautet:

where=dimension1==value1;dimension2==value2

Zum Beispiel:

https://analytics.api.brightcove.com/v1?accounts=account_id(s)&dimensions=device_type&where=video==video_id;device_type==tablet

Kommas werden als logisches ODERs und Semikolons als logisches UNDs behandelt. Zum Beispiel, where=video==1234,5678;player==9876 wird interpretiert als "wo Video = 1234 ODER 5678 UND Spieler = 9876"

Leerzeichen und Sonderzeichen

Zeichenfolgenwerte sollten URI-codiert sein. Sie können Sonderzeichen auch mit einem "" maskieren:

where=search_terms==boston,%20ma

Sie können jede Dimension als Filter verwenden. aber nur wenn diese Dimension auch in der enthalten ist dimensions Sie fordern.

Filtern nach Videoeigenschaften

Mit dem Spezial where=video.q=={property}:{value} Filter können Sie Ihren Bericht basierend auf einer Vielzahl von Eigenschaften auf eine bestimmte Gruppe von Videos beschränken, darunter:

Tags
reference_id
benutzerdefinierte Felder ^[1]
{a_specific_custom_field}
hergestellt in

Hinweise

^[1] Die grundlegende Syntax lautet where=video.q==custom_fields:value (entspricht dem Wert in einem benutzerdefinierten Feld) oder where=video.q==myfield:value (Entspricht dem Wert im jeweiligen benutzerdefinierten Feld myfield). Wenn Sie in bestimmten benutzerdefinierten Feldern suchen, beachten Sie, dass Sie nach dem internen Namen suchen müssen, nicht nach dem Anzeigenamen:

Eine kurze Überprüfung, ob Sie den richtigen Namen verwenden: Der interne Name lautet nur Kleinbuchstaben und keine Leerzeichen enthalten.

Beispiele

Hier sind einige Beispiele where Filter für die Suche nach Tags und benutzerdefinierten Feldern:

Einzel-Tag

where=video.q==tags:foo

Mehrere Tags:

where=video.q==tags:foo,bar

Benutzerdefinierte Felder

where=video.q==custom_fields:foo

Tags und benutzerdefinierte Felder

where=video.q==tags:foo,bar+custom_fields:fish

Notiere dass der video.q Suchfunktion beinhaltet AND , OR Und NOT Logik wie folgt:

EIN + (Plus-)Zeichen vor dem Suchbegriff bedeutet Ergebnisse muss diesen Begriff einschließen.
EIN - (Minus-)Zeichen vor dem Suchbegriff bedeutet Ergebnisse darf nicht diesen Begriff einschließen.
Wenn kein Plus- oder Minuszeichen vorhanden ist, können die Ergebnisse diesen Begriff enthalten oder nicht.

Die folgenden Beispiele veranschaulichen die Verwendung dieser Logik.

Beispiele für die Suche
`where` Filtern	Ergebnisse
`where=video.q==tags:red%20tags:blue%tags:green`	Videos mit den Tags `red` `blue` ODER ODER `green` werden zurückgegeben
`where=video.q==+tags:red%20tags:blue%tags:green`	zurückgegebene Videos MÜSSEN das Tag haben `red` UND kann die Tags haben `blue` ODER `green`
`where=video.q==+tags:red%20tags:blue%-tags:green`	zurückgegebene Videos MÜSSEN das Tag HABEN `red` UND dürfen das Tag haben `blue`, dürfen aber NICHT das Tag haben `green`

Notiz: %20 in den obigen Beispielen ist ein URI-codiertes Leerzeichen. Abhängig von dem Client, den Sie für die Anfrage verwenden, müssen Sie möglicherweise auch die + unterschreiben als %2B.

Eine vollständige Erläuterung dieser Abfragesyntax finden Sie unter Verwenden der CMS-API: Nach Videos suchen.

Zusammenfassung der Filter und zulässigen Werte

Die folgende Tabelle zeigt zulässige Werte für jede als Filter verwendete Dimension:

Dimensionsfilter	Zulässige Werte

Datumsbereiche

Datumsbereiche, angegeben in from und to Parameter für alle Arten von Berichten, können in verschiedenen Formaten angegeben werden:

Textwerte:
- to=now(verfügbar und der Standardwert für alle Anfragen)
Epochenzeitwerte in Millisekunden, wie z 1377047323000
Datumsangaben im internationalen Datumsformat ISO 8601: YYYY-MM-DDFormat, wie z 2013-09-12. Für in diesem Format ausgedrückte Daten:
- Jeder angegebene Datumsbereich wird interpretiert in der für das Konto festgelegten Zeitzone
- Die Uhrzeit für das angegebene Datum wird als Mitternacht ( 00:00:00) an dem Datum interpretiert, das in der für das Konto festgelegten Zeitzone angegeben ist.
Relative Daten: Sie können eines der beiden ausdrücken to und from Werte relativ zum anderen in d (Tage) oder h (Stunden). Zum Beispiel:
- from=2015-01-01&to=31d
- from=-48h&to=now
- from=-2d&to=now(wird die gleichen Ergebnisse wie im vorherigen Beispiel liefern)
- from=-365d&to=2014-12-31
Beachten Sie, dass negative Zahlen (-2d) als "vor" (der andere Wert) interpretiert werden und positive Zahlen (48h) als "von" (der andere Wert) behandelt werden.

Um einen Bericht zu einer Dimension wie "Video" für einen einzelnen Tag zu erstellen, legen Sie die Werte von bis und von auf dieses Datum fest:

...&dimensions=video&from=2013-11-01&to=2013-11-01

Limit und Offset

Die limit ist die Anzahl der zurückzugebenden Elemente (Standard: 10). Um alle Artikel zurückzugeben, verwenden Sie limit=all. offset ist die Anzahl der Elemente, die übersprungen werden sollen (Standard: 0). Sie können limit und offset zusammen verwenden, um eine App zu erstellen, die die Ergebnisse durchsucht.

Abgeglichene Daten

Die reconciled Parameter ist ein boolescher Wert. Wenn sie auf gesetzt ist true, werden die Ergebnisse auf abgeglichene Daten beschränkt. Falls false, werden die Ergebnisse auf Echtzeitdaten (stündlich, nicht abgeglichen) beschränkt.

Echtzeitdaten sind nur für die letzten 32 Tage verfügbar. Wenn Sie einstellen reconciled=false und der from Datum, das älter als 32 Tage ist, gibt die API keine Daten zurück, da zu diesem Zeitpunkt keine nicht abgeglichenen Daten vorhanden sind.

Geografische Berichte

Dimensionen für geografische Analysen

country- Als ISO-3611-1-Ländercode. zB: 'UNS'
region- Als ISO-3611-2-Regionalcode. zB: 'WIR-WAR'
city- Stadtname. z.B: Seattle

Hinweis: Für unbekannte Länder oder Regionen gibt die API "ZZ" als Code zurück (gemäß ISO-3611-alpha2).

Felder und Sortierung

Verwenden Sie die fields -Parameter, um die Felder anzugeben, die zurückgegeben werden sollen. Standardmäßig video_view wird zurückgegeben und das Feld, das der Dimension entspricht, über die Sie berichten (z. B. destination_domain) , wird zurückgegeben. Sehen Abmessungen und Felder für mehr Details.

Verwenden Sie die sort Parameter, um anzugeben, welches Metrikfeld zum Sortieren der zurückgegebenen Elemente verwendet wird; zum Beispiel: sort=video_view. Sie können die Sortierreihenfolge umkehren, indem Sie das Sortierfeld negieren: sort= -video_view.

Die verfügbaren Felder zum Zurückgeben oder Sortieren hängen von der Metriken für die Dimension(en) zurückgegeben, für die Sie Berichte erstellen. Diese Parameter werden streng überprüft, und Ihre Anfrage gibt einen Fehler zurück, wenn die fields oder sort Parameter zeigt auf ein Feld, das für die Anforderung nicht gültig ist. Sie können jedoch nach jedem Feld sortieren, das Sie zurückgeben.

Für Berichte mit Videodimensionen gehören zu den gültigen Sortierwerten die Video-Metadatenfelder: video.name video.reference_id, und video.tags.

video_name gegen video.name

video_name ist der in den Analysedaten aufgezeichnete Videoname
video.name ist der Videoname in den Videometadaten

In den meisten Fällen sind die beiden Werte identisch, es gibt jedoch Fälle, in denen dies nicht der Fall ist:

In einigen Fällen wird möglicherweise ein Wert für angezeigt video.name, aber nicht für. In video_namediesem Fall wurde der Videoname aus irgendeinem Grund nicht an den Analytics-Datensammler gesendet
In einigen Fällen können die Werte abweichen - in diesem Fall wurde das Video irgendwann umbenannt: video.name ist der aktuelle Name des Videos in Ihrer Video Cloud-Medienbibliothek; video_name ist der Name des Videos des Videos zu dem Zeitpunkt, als die Daten an den Analytics-Datensammler gesendet wurden (wenn Sie einen Zeitraum abfragen, in dem sich der Name geändert hat, ist der von der API zurückgegebene Wert der Name, der mit der Mehrheit der Aufrufe verknüpft ist während der Phase).

Berechnete Felder

Sie können Ihren API-Anfragen mithilfe der folgenden Syntax berechnete Felder hinzufügen:

fields=calulated_field_name:expression

Sie können berechnete Felder verwenden, um Ihre eigenen benutzerdefinierten Felder aus vorhandenen Metriken zu erstellen oder ein vorhandenes Feld umzubenennen.

Der Name für das berechnete Feld kann eine beliebige URI-kompatible Zeichenfolge sein. Der Ausdruck kann reguläre Feldnamen und die folgenden arithmetischen Operatoren enthalten:

+ (zusätzlich)
- (Subtraktion)
* (Multiplikation)
/ (Abteilung)
^ (Exponent)
() (Klammern)

Beispiele

fields=avg_seconds_viewed:video_seconds_viewed/video_view,video.name

fields=avg_incomplete_ads:(ad_mode_begin-ad_mode_complete)/video_view,video.name

fields=Video%20Views:video_view,video.name

Musteranfrage

https://analytics.api.brightcove.com/v1/data?accounts=1752604059001&dimensions=video&fields=avg_seconds_viewed:video_seconds_viewed/video_view,video_seconds_viewed,video.name&sort=-video_view&limit=4

Musterantwort (auf die obige Anfrage)

{
  "item_count": 110,
  "items": [
    {
      "avg_seconds_viewed": 2152.2519913106444,
      "video.name": "Flamingos",
      "video_seconds_viewed": 2972260,
      "video": "4825279519001",
      "video_view": 1381
    },
    {
      "avg_seconds_viewed": 14.016225448334756,
      "video.name": "Tiger",
      "video_seconds_viewed": 16413,
      "video": "4093643993001",
      "video_view": 1171
    },
    {
      "avg_seconds_viewed": 12.06,
      "video.name": "Zebra",
      "video_seconds_viewed": 9045,
      "video": "3851389913001",
      "video_view": 750
    },
    {
      "avg_seconds_viewed": 23.343065693430656,
      "video.name": "Sea-SeaTurtle",
      "video_seconds_viewed": 15990,
      "video": "1754276205001",
      "video_view": 685
    }
  ],
  "summary": {
    "avg_seconds_viewed": 274.27374399301004,
    "video_seconds_viewed": 3139063,
    "video_view": 11445
  }
}

Überblick: Dimensionen, Felder und Parameter

Abmessungen und Felder

Wählen Sie Dimension(en) aus, um einen Bericht zu erstellen:

Felder zur Rückgabe:Wählen Sie AlleAlle abwählen

Früheste from Datum für diese Dimensionskombination:

Beispiel-API-Anfrage:

Antwortdaten

Hinweise

Beispielanfrage

Beispiel mit cURL

Probe

Unterstützte Dimensionskombinationen

URL-Parameter

Konten

Wo Filter

Leerzeichen und Sonderzeichen

Filtern nach Videoeigenschaften

Hinweise

Beispiele

Einzel-Tag

Mehrere Tags:

Benutzerdefinierte Felder

Tags und benutzerdefinierte Felder

Zusammenfassung der Filter und zulässigen Werte

Datumsbereiche

Limit und Offset

Abgeglichene Daten

Geografische Berichte

Dimensionen für geografische Analysen

Felder und Sortierung

Berechnete Felder

Beispiele

Musteranfrage

Musterantwort (auf die obige Anfrage)

Felder zur Rückgabe:

Früheste `from` Datum für diese Dimensionskombination: