Überblick: Zielgruppen-API
API-Referenz
Siehe auch die API-Referenz.
Basis-URL
Die Basis-URL für die Zielgruppen-API lautet:
https://audience.api.brightcove.com/v1
Kontopfad
In allen Fällen werden Anfragen für ein bestimmtes Video Cloud-Konto gestellt. Sie müssen der Basis-URL immer den Begriff "Konten" gefolgt von Ihrer Konto-ID hinzufügen:
https://audience.api.brightcove.com/v1/accounts/{account_id}
Authentifizierung
Die Zielgruppen-API verwendet die Brightcove OAuth-Service Anrufe zu authentifizieren.
Sie müssen zuerst die Client-Anmeldeinformationen abrufen (a client_id
und client_secret
). Dies ist eine einmalige Operation, die mit dem ausgeführt werden kann Benutzeroberfläche für OAuth-Anmeldeinformationen. Sie benötigen Berechtigungen für Audience / Read-Vorgänge:

Sie können Client-Anmeldeinformationen direkt vom Brightcove OAuth-Dienst mithilfe von abrufen cURL oder Postbote.
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}
Das access_token
läuft nach fünf Minuten ab, daher müssen Sie für jede Anforderung eine erhalten oder überprüfen, ob Ihr Token noch gültig ist. Sehen Zugriffstoken erhalten Hier finden Sie eine ausführliche Erläuterung zum Abrufen von Zugriffstoken, einschließlich Codebeispielen.
Fehlerbehandlung
Wenn ein Fehler auftritt, antwortet die API mit einem der folgenden Statuscodes und einem entsprechenden Fehlercode im Antworttext:
Statuscode | Fehlercode | Beschreibung |
---|---|---|
400 | BAD_REQUEST_ERROR | Abfrageparameter sind ungültig |
401 | UNAUTHORIZED_ERROR | Das Zugriffstoken fehlt entweder, ist abgelaufen oder ungültig |
404 | RESSOURCE NICHT GEFUNDEN | Die URL existiert nicht |
429 | REQUEST_THROTTLED_ERROR | Der Benutzer hat die Richtlinie zur Ratenbegrenzung überschritten |
500 | INTERNER FEHLER | Ein interner Fehler ist aufgetreten |
504 | GATEWAY_TIMEOUT_ERROR | Der Server hat eine Zeitüberschreitung bei der Erfüllung Ihrer Anfrage |
Unten finden Sie ein Beispiel für einen Antworttext für einen Fehler:
[
{
"error_code": "UNAUTHORIZED_ERROR",
"message": "Permission denied"
}
]
Parameter
Es gibt verschiedene Parameter, die Sie zu Anforderungen hinzufügen können, um die abgerufenen Daten einzuschränken und zu filtern. Diese gelten für alle in den folgenden Abschnitten beschriebenen Anforderungstypen.
Ergebnisse filtern
Sie können die Ergebnisse mit dem filtern where
Parameter. Die Syntax für Filter lautet:
where=field1==value1;field2==value2
Beispielsweise:
where=video_id==123456789;video_name==test
Kommas werden als logische ODERs und Semikolons als logische UNDs behandelt. Beispielsweise, where=video_id==1234,5678;video_name=test
wird interpretiert als "wobei video_id = 1234 ODER 5678, AND video_name = test".
Auswählen der zurückzugebenden Felder
In der Anforderung kann eine Liste von Feldern angegeben werden, um die Ergebnisse auf diese Teilmenge von Feldern zu beschränken. Die Syntax für Felder lautet:
fields=field1,field4
Beispielsweise:
fields=video_id,video_name
Die Felder, nach denen Sie filtern und sortieren können, werden in den folgenden Abschnitten für jeden Anforderungstyp detailliert beschrieben.
Datumsbereiche
Datumsbereiche können in angegeben werden from
und to
Parameter und werden auf das Datum angewendet, an dem das Ansichtsereignis zuletzt aktualisiert wurde (das Feld update_at). Datumsbereiche können in folgenden Formaten angegeben werden:
- Der Textwert
now
welches die aktuelle Zeit darstellt - Epochenzeitwerte in Millisekunden, z
1377047323000
- Daten im internationalen Datumsformat nach ISO 8601:
YYYY-MM-DD
Format, wie z2013-09-12
. Für Daten in diesem Format:- Jeder angegebene Datumsbereich wird in UTC interpretiert
- Die Uhrzeit für das Datum geben wird am angegebenen Datum als Mitternacht (
00:00:00
) interpretiert
- Relative Daten: Sie können eines der beiden ausdrücken
to
undfrom
Werte relativ zum anderen ind
(Tage),h
(Std),m
(Minuten) oders
(sek). Beispielsweise:from=2015-01-01&to=31d
from=-48h&to=now
from=-2d&to=now
(gibt die gleichen Ergebnisse wie im vorherigen Beispiel)from=-365d&to=2015-12-31
from=-10m&to=now
Paging-Ergebnisse
Das limit
ist die Anzahl der zurückzugebenden Elemente (Standard: 25; Maximum: 100). offset
ist die Anzahl der zu überspringenden Elemente (Standard: 0). Sie können verwenden limit
und offset
zusammen, um eine App zu erstellen, die durch die Ergebnisse blättert. Jeder enthält die limit
, und offset
count.
, die Sie verwenden können, um festzulegen die Iteration über die Gesamtergebnisse nach oben. In JavaScript können Sie beispielsweise die insgesamt erforderlichen Iterationen wie folgt abrufen:
// response is the JSON-parsed response from the first request
var totalRequests = Math.ceil(response.count / response.limit)
Ansichtsereignisse abrufen
Führen Sie a aus, um Ansichtsereignisse in einem Konto abzurufen GET
Anforderung an die Ressource view_events:
https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events
Hier ist eine Beispielanfrage in cURL
curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events?where=video_id==123&from=-5d&to=now&sort=-created_at \
-H "Authorization: Bearer {token}"
Die Antwort sieht folgendermaßen aus:
{
"count": 27,
"limit": 25,
"offset": 0,
"result": [
{
"created_at": "2016-04-25T18:30:21.651Z",
"page_url": "http://players.brightcove.net/1486906377/V1s6NOwRx_default/index.html?videoId=4842718056001",
"player_id": "V1s6NOwRx",
"time_watched": 2,
"updated_at": "2016-04-25T18:30:21.651Z",
"video_id": "4842718056001",
"video_name": "Horses Heading to the Track",
"watched": 19
},
{
"created_at": "2016-04-25T18:31:55.071Z",
"page_url": "http://players.brightcove.net/1486906377/BkgFuzyhg_default/index.html?videoId=4842718056001",
"player_id": "BkgFuzyhg",
"time_watched": 15,
"updated_at": "2016-04-25T18:32:00.879Z",
"video_id": "4842718056001",
"video_name": "Horses Heading to the Track",
"watched": 99
}, ...
}
]
Felder zum Filtern und Auswählen
All die Parameter kann mit verwendet werden view_event
Anfragen.
Hier ist eine Beispielanforderung in cURL unter Verwendung der Parameter:
curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events?where=video_id==123&from=-5d&to=now&sort=-created_at \
-H "Authorization: Bearer {token}"
Die folgenden Felder werden unterstützt für view_event
Anfragen beim Filtern mit a where
Klausel oder bei der Auswahl während a fields
Klausel:
Feld | Beschreibung |
---|---|
video_id | Brightcove-Video-ID |
video_name | Brightcove-Videoname |
tracking_id | Benutzerdefinierte Tracking-ID |
external_id | Die Marketo, Eloqua oder benutzerdefinierte GUID |
player_id | Die ID des Brightcove-Players, der das Ansichtsereignis erstellt hat |
page_url | Die URL der Seite, auf der das Ansichtsereignis erstellt wurde |
schaute | Prozent sahen zu |
time_watched | Sekunden des Videos gesehen |
hergestellt in | Erstellungsdatum |
aktualisiert am | Datum der letzten Aktualisierung |
is_synced | Ein Boolescher Wert, der angibt, ob das Ansichtsereignis synchronisiert wurde oder nicht |
Ereignis_1 | Benutzerdefinierte Ereignisse |
event_2 | |
event_3 | |
metric_1 | Benutzerdefinierte Metriken |
metric_2 | |
metric_3 |
Leads abrufen
Führen Sie a aus, um Ansichtsereignisse in einem Konto abzurufen GET
Anfrage an die view_events
Ressource:
https://audience.api.brightcove.com/v1/accounts/{account_id}/leads
Beispielantwort:
{
"count": 2,
"limit": 25,
"offset": 0,
"result": [
{
"created_at": "2016-06-30T12:57:11.283Z",
"email_address": "bbailey@brightcove.com",
"first_name": "Bob",
"last_name": "Bailey",
"page_url": "http://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
"player_id": "Hk4TBqzL",
"video_id": "4997275041001"
},
{
"created_at": "2016-06-30T12:57:33.301Z",
"email_address": "rcrooks@brightcove.com",
"first_name": "Robert",
"last_name": "Crooks",
"page_url": "http://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
"player_id": "Hk4TBqzL",
"video_id": "4997275041001"
}
]
}
Felder zum Filtern und Auswählen
All die Parameter kann mit verwendet werden leads
Anfragen.
Hier ist eine Beispielanforderung in cURL unter Verwendung der Parameter:
curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/leads?where=video_id==123&from=-5d&to=now&sort=-created_at \
-H "Authorization: Bearer {token}"
Die folgenden Felder werden unterstützt für leads
Anfragen beim Filtern mit a where
Klausel oder bei der Auswahl während a fields
Klausel:
Feld | Beschreibung |
---|---|
video_id | Brightcove-Video-ID |
external_id | Die Marketo, Eloqua oder benutzerdefinierte GUID |
player_id | Die ID des Brightcove-Players, der das Ansichtsereignis erstellt hat |
page_url | Die URL der Seite, auf der das Ansichtsereignis erstellt wurde |
hergestellt in | Erstellungsdatum |
email_address | Die E-Mail-Adresse des Leads |
Vorname | Der Vorname des Leads, falls angegeben |
Nachname | Der Nachname des Leads, falls angegeben |
business_phone | Die Telefonnummer des Leads, falls angegeben |
Land | Das Land der Führung, falls angegeben |
firmaname | Die Firma des Leads, falls vorhanden |
Industrie | Die Branche, zu der die Führung gehört, wenn sie bereitgestellt wird |