Überblick: Zielgruppen-API

API-Referenz

Siehe auch die API-Referenz.

Basis-URL

Die Basis-URL für die Audience API lautet:

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

Account-Pfad

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-Dienst 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 benötigen Berechtigungen für Zielgruppen-/Lesevorgänge:

Sie können Client-Anmeldeinformationen direkt vom Brightcove OAuth-Dienst abrufen, indem Sie 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}

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.

Fehlerbehandlung

Tritt ein Fehler auf, antwortet die API mit einem der folgenden Statuscodes und einem entsprechenden Fehlercode im Antworttext:

Unten sehen Sie ein Beispiel für einen Antworttext für einen Fehler:

[
	{
	"error_code": "UNAUTHORIZED_ERROR",
	"message": "Permission denied"
	}
]

Parameter

Es gibt mehrere Parameter, die Sie zu Anfragen 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 der filtern where Parameter. Die Syntax für Filter lautet:

where=field1==value1;field2==value2

Zum Beispiel:

where=video_id==123456789;video_name==test

Kommas werden als logisches ODERs und Semikolons als logisches UNDs behandelt. Zum Beispiel, where=video_id==1234,5678;video_name=test wird interpretiert als "wo video_id = 1234 ODER 5678, AND video_name = test".

Auswählen von Feldern, die zurückgegeben werden sollen

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

Zum Beispiel:

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 angegeben werden in from und to Parameter und werden auf das Datum angewendet, an dem das Ansichtsereignis zuletzt aktualisiert wurde (das Feld "updated_at"). Datumsbereiche können in den folgenden Formaten angegeben werden:

• Der Textwert now was die aktuelle Uhrzeit darstellt
• Epochenzeitwerte in Millisekunden, wie z 1377047323000
• Datumsangaben im internationalen Datumsformat ISO 8601: YYYY-MM-DD Format, wie z 2013-09-12. Für in diesem Format ausgedrückte Daten:
  • Jeder angegebene Datumsbereich wird in UTC interpretiert
  • Die Uhrzeit für das angegebene Datum wird als Mitternacht ( 00:00:00) am angegebenen Datum interpretiert
• Relative Daten: Sie können eines der beiden ausdrücken to und from Werte relativ zum anderen in d (Tage), h (Std), m (Minuten), oder s (Sek.). 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=2015-12-31
  • from=-10m&to=now

Paging-Ergebnisse

Die limit ist die Anzahl der zurückzugebenden Elemente (Standard: 25; Maximum: 200). offset ist die Anzahl der zu überspringenden Elemente (Standard: 0). Sie können limit und offset zusammen verwenden, um eine App zu erstellen, die die Ergebnisse durchsucht. 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 gesamten erforderlichen Iterationen wie folgt abrufen:

// response is the JSON-parsed response from the first request
var totalRequests = Math.ceil(response.count / response.limit)

Abrufen von Ansichtsereignissen

Führen Sie zum Abrufen von Ansichtsereignissen in einem Konto Folgendes aus: GET Anfrage 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}"

{
"count": 27,
"limit": 25,
"offset": 0,
"result": [
		{
				"created_at": "2016-04-25T18:30:21.651Z",
				"page_url": "https://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": "https://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 Beispielanfrage in cURL mit den Parametern:

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:

Abrufen von Leads

Führen Sie zum Abrufen von Ansichtsereignissen in einem Konto Folgendes aus: GET Anfrage an die view_events Ressource:

https://audience.api.brightcove.com/v1/accounts/{account_id}/leads

{
"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": "https://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": "https://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 Beispielanfrage in cURL mit den Parametern:

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: