Présentation : API d'audience

Référence de l'API

Voir également la référence de l'API.

URL de base

L'URL de base de l'API Audience est :

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

Chemin du compte

Dans tous les cas, des demandes seront faites pour un compte Video Cloud spécifique. Vous devrez toujours ajouter le terme « comptes » suivi de votre ID de compte à l'URL de base :

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

Authentification

L'API Audience utilise le service OAuth Brightcove pour authentifier les appels.

Vous devrez d'abord obtenir les informations d'identification client (a client_id et client_secret). Il s'agit d'une opération unique qui peut être effectuée à l'aide de l' interface utilisateur des informations d'identification OAuth. Vous aurez besoin d'autorisations pour les opérations Audience/Lire :

Vous pouvez obtenir les informations d'identification du client directement à partir du service Brightcove OAuth en utilisant boucle ou Facteur.

Vous aurez également besoin d'un access_token, qui est obtenu en utilisant le client_id et client_secret et transmis dans un en-tête Autorisation avec votre requête API :

Authorization: Bearer {access_token}

Le access_token expire après cinq minutes, vous devez donc en obtenir un pour chaque requête, ou vérifier pour vous assurer que votre jeton est toujours valide. Voir Obtenir des jetons d'accès pour une explication détaillée de la façon d'obtenir des jetons d'accès, y compris des exemples de code.

Traitement des erreurs

Si une erreur se produit, l'API répondra avec l'un des codes d'état suivants et un code d'erreur correspondant dans le corps de la réponse :

Voici un exemple de corps de réponse pour une erreur :

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

Paramètres

Il existe plusieurs paramètres que vous pouvez ajouter aux requêtes pour limiter et filtrer les données récupérées. Ceux-ci s'appliquent à tous les types de demandes décrits dans les sections qui suivent.

Filtrage des résultats

Vous pouvez filtrer les résultats à l'aide du where paramètre. La syntaxe des filtres est la suivante :

where=field1==value1;field2==value2

Par exemple :

where=video_id==123456789;video_name==test

Les virgules sont traitées comme des RO logiques et des points-virgules comme des PAD logiques. Par exemple, where=video_id==1234,5678;video_name=test est interprété comme « où video_id = 1234 OR 5678, AND video_name = test ».

Sélection des champs à renvoyer

Une liste de champs peut être spécifiée dans la demande afin de limiter les résultats à ce sous-ensemble de champs. La syntaxe des champs est la suivante :

fields=field1,field4

Par exemple :

fields=video_id,video_name

Les champs que vous pouvez filtrer et trier sont détaillés pour chaque type de demande dans les sections suivantes.

Plages de dates

Les plages de dates peuvent être spécifiées dans from et to les paramètres et sont appliquées à la date de la dernière mise à jour de l'événement view (champ updated_at). Les plages de dates peuvent être indiquées dans les formats suivants :

• La valeur de texte now qui représente l'heure actuelle
• Les valeurs temporelles de l'époque en millisecondes, telles que 1377047323000
• Dates exprimées dans la norme ISO 8601 format international de date : YYYY-MM-DD format, tel que 2013-09-12. Pour les dates exprimées dans ce format :
  • Toute plage de dates spécifiée sera interprétée en UTC
  • L'heure de la date donnée sera interprétée comme minuit ( 00:00:00) à la date spécifiée
• Dates relatives: vous pouvez exprimer l'un ou l'autre des to et from valeurs par rapport à l'autre dans d (journées), h (heures), m (minutes), ou s (seconde). Par exemple :
  • from=2015-01-01&to=31d
  • from=-48h&to=now
  • from=-2d&to=now ( donnera les mêmes résultats que l'exemple précédent)
  • from=-365d&to=2015-12-31
  • from=-10m&to=now

Résultats de pagination

limit Le nombre d'articles à retourner (par défaut : 25 ; maximum : 100). offset est le nombre d'éléments à ignorer (par défaut : 0). Vous pouvez utiliser limit et offset ensemble pour créer une application qui page à travers les résultats. Chacun inclut le limit, offset, et count., que vous pouvez utiliser pour configurer l'itération sur les résultats totaux. Par exemple, en JavaScript, vous pouvez obtenir les itérations totales requises comme ceci :

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

Récupération des événements de vue

Pour récupérer des événements de vue dans un compte, effectuez une GET demande à la ressource view_events :

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

Voici un exemple de demande dans 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}"

La réponse ressemblera à ceci :

{
    "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
        }, ...
    }
]

Champs de filtrage et de sélection

Tous les paramètres peuvent être utilisés avec des view_event requêtes.

Voici un exemple de requête dans cURL en utilisant les paramètres :

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}"

Les champs suivants sont pris en charge pour les view_event requêtes lors du filtrage avec une where clause ou lors de la sélection pendant une fields clause :

Récupération des pistes

Pour récupérer des événements de vue dans un compte, effectuez une GET demande à la view_events ressource :

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

Exemple de réponse :

{
    "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"
        }
    ]
}

Champs de filtrage et de sélection

Tous les paramètres peuvent être utilisés avec des leads requêtes.

Voici un exemple de requête dans cURL en utilisant les paramètres :

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}"

Les champs suivants sont pris en charge pour les leads requêtes lors du filtrage avec une where clause ou lors de la sélection pendant une fields clause :