Übersicht: 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

Konto-Pfad

In allen Fällen werden Anfragen für ein bestimmtes Video Cloud-Konto gestellt. Sie müssen immer den Begriff „Konten“ gefolgt von Ihrer Konto-ID zur Basis-URL hinzufügen:

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

Authentifizierung

Die Audience 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 benötigen Berechtigungen für Audience/Read-Vorgänge:

Sie können Client-Anmeldeinformationen direkt vom Brightcove OAuth Service mit cURL oder Postmanabrufen.

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.

Fehlerbehandlung

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

Im Folgenden finden Sie einen Beispielantworttext für einen Fehler:

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

Parameter

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

where=field1==value1;field2==value2

Beispiel:

where=video_id==123456789;video_name==test

Kommas werden als logische ORs und Semikolons als logische ANDs behandelt. Zum Beispiel where=video_id==1234,5678;video_name=test wird als „wo video_id = 1234 ODER 5678 UND video_name = test“ interpretiert.

Auswählen von zurückzugebenden Feldern

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

Beispiel:

fields=video_id,video_name

Die Felder, nach denen Sie filtern und sortieren können, werden für jeden Anforderungstyp in den folgenden Abschnitten detailliert beschrieben.

Datum-Bereiche

Datumsbereiche können in from und to Parameter angegeben werden und werden auf das Datum angewendet, an dem das View-Ereignis zuletzt aktualisiert wurde (das updated_at-Feld). Datumsbereiche können in den folgenden Formaten angegeben werden:

• Der Textwert now , der die aktuelle Uhrzeit darstellt
• Epoch-Zeitwerte in Millisekunden, wie 1377047323000
• Daten, die im internationalen Standarddatumsformat nach ISO 8601 ausgedrückt werden: YYYY-MM-DD Format, wie 2013-09-12z. Für Daten, die in diesem Format ausgedrückt werden:
  • Jeder angegebene Datumsbereich wird in UTC interpretiert
  • Die Zeit für das angegebene Datum wird am angegebenen Datum als midnight ( 00:00:00) 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). Beispiel:
  • from=2015-01-01&to=31d
  • from=-48h&to=now
  • from=-2d&to=now ( wird die gleichen Ergebnisse wie im vorherigen Beispiel geben)
  • from=-365d&to=2015-12-31
  • from=-10m&to=now

Paging-Ergebnisse

Die limit ist die Anzahl der Artikel, die zurückgegeben werden sollen (Standard: 25; Maximum: 100). 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 durchstößt. Jedes enthält die limit , offset , und count. , mit dem Sie die Iteration über die Gesamtergebnisse einrichten können. In JavaScript könnten 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)

Abrufen von View-Ereignissen

Um View-Ereignisse in einem Konto abzurufen, führen Sie eine GET Anfrage an die Ressource view_events aus:

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

Hier ist 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 wird so aussehen:

{
    "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 für Filterung und Auswahl

Alle Parameter können mit view_event Anfragen verwendet werden.

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 für view_event Anfragen beim Filtern mit einer where Klausel oder bei der Auswahl während einer fields Klausel unterstützt:

Abrufen von Leads

Um Ansichtsereignisse in einem Konto abzurufen, führen Sie eine GET Anfrage an die view_events Ressource durch:

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

Beispiel Antwort:

{
    "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 für Filterung und Auswahl

Alle Parameter können mit leads Anfragen verwendet werden.

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 für leads Anfragen beim Filtern mit einer where Klausel oder bei der Auswahl während einer fields Klausel unterstützt: