Aperçu: API d'audience

Référence API

Voir aussi le Référence 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 Nuage vidéo Compte. Vous devrez toujours ajouter le terme « comptes » suivi de votre identifiant de compte à l'URL de base :

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

Authentification

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

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

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 d'autorisation avec votre requête API :

Authorization: Bearer {access_token}

Les access_token expire après cinq minutes, vous devez donc en obtenir un pour chaque demande, ou vérifier que votre token 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.

La gestion 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

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

Filtrage des résultats

Vous pouvez filtrer les résultats en utilisant le where paramètre. La syntaxe des filtres est :

where=field1==value1;field2==value2

Par exemple :

where=video_id==123456789;video_name==test

Les virgules sont traitées comme des OU logiques et les points-virgules comme des ET logiques. Par exemple, where=video_id==1234,5678;video_name=test est interprété comme "où video_id = 1234 OU 5678, AND video_name = test".

Sélection des champs à retourner

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

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 qui suivent.

Plages de dates

Les plages de dates peuvent être spécifiées dans from et to paramètres et sont appliqués à la date à laquelle l'événement de vue a été mis à jour pour la dernière fois (le champ updated_at). Les plages de dates peuvent être indiquées dans les formats suivants :

• La valeur du texte now qui représente l'heure actuelle
• Valeurs de temps d'époque en millisecondes, telles que 1377047323000
• Dates exprimées au format de date international standard ISO 8601 : 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'une ou l'autre des to et from valeurs par rapport à l'autre dans d (jours), h (les 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 la pagination

Les limit est le nombre d'articles à retourner (par défaut : 25 ; maximum : 200). 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 parcourt les résultats. Chacun comprend 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 le nombre total d'itérations 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 les événements de vue dans un compte, effectuez une GET requête à la ressource view_events :

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

Voici un exemple de requête en 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
		}, ...
}
]

Champs de filtrage et de sélection

Tous les paramètres peut être utilisé avec view_event demandes.

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 view_event requêtes lors du filtrage avec un where clause ou lors d'une sélection lors d'une fields clause:

Récupérer des prospects

Pour récupérer les événements de vue dans un compte, effectuez une GET demande au 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"
		}
]
}

Champs de filtrage et de sélection

Tous les paramètres peut être utilisé avec leads demandes.

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 leads requêtes lors du filtrage avec un where clause ou lors d'une sélection lors d'une fields clause: