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

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 z 2013-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 und from Werte relativ zum anderen in d (Tage), h (Std), m (Minuten) oder s (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:

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: