Dimensions et champs
Les dimensions sont les compartiments de données principaux pour l'analyse. Pour voir les repères complets des cotes individuelles, cliquez sur le nom de la cote dans la liste ci-dessous.
Sélectionnez (s) dimension (s) ci-dessous pour afficher les champs qui peuvent être renvoyés pour elle. Vous pouvez également cliquer sur le bouton Faire une demande pour effectuer un exemple de demande et afficher les résultats. Si vous sélectionnez plusieurs cotes incompatibles, un message s'affiche à cet effet.
Remarques
- Par défaut,
video_view
est le seul champ renvoyé - les autres champs ne seront renvoyés que s'ils sont spécifiés dans la valeur dufields
paramètre. - Si vous spécifiez un champ à renvoyer qui n'est pas pris en charge pour la combinaison de dimension ou de dimension, une
UNSUPPORTED_FIELD_COMBINATION_ERROR
erreur sera renvoyée. - Le
bytes_delivered
champ comprend toutes les données fournies par Video Cloud aux clients, y compris les données vidéo, les images, les pistes de texte et d'autres ressources, ainsi que le code du lecteur lui-même. Certaines de ces données sont obtenues à partir de CDN et peuvent ne pas être disponibles avant trois jours. - En plus des champs affichés pour la
video
dimension, vous pouvez également renvoyervideo.custom_fields.{field_name}
Exemple de demande
Un cas d'utilisation typique pour obtenir un rapport sur plusieurs dimensions : vous voulez une ventilation des vues vidéo entre les appareils mobiles et de bureau, et vous voulez également savoir combien de vues d'appareils mobiles se trouvaient sur les appareils iOS par rapport aux appareils Android, et combien de vues de bureau étaient sur Mac par rapport aux machines Windows. Actuellement, il n'y a pas de rapport standard dans le module Studio Analytics qui fournit ces informations, mais vous pouvez l'obtenir via cet Analytics API appel :
https://analytics.api.brightcove.com/v1/data?accounts=57838016001&dimensions=video,device_type,device_os&from=2014-01-01&to=2014-04-01&fields=video_view
(Dans ce cas, nous demandons des visionnages vidéo pour la période allant du 1er janvier au 1er avril 2014.)
Exemple d'utilisation de cURL
Si vous voulez essayer l'API en utilisant cURL, voici quelques notes :
- Vous devrez d'abord obtenir un jeton d'accès
- Étant donné que l'URL de la requête inclura toujours des paramètres d'URL, vous devrez la placer entre guillemets (simples ou doubles)
Exemple
Voici un exemple de commande cURL :
curl -s --header "Authorization: Bearer $ACCESS_TOKEN" \
"https://analytics.api.brightcove.com/v1/data?accounts=$ACCOUNT_ID&dimensions=video&from=2017-04-04&limit=100"
Si vous remplacez par $ACCESS_TOKEN
un jeton d'accès valide et $ACCOUNT_ID
avec votre identifiant de compte, cette demande devrait fonctionner. Notez que vous pouvez utiliser cet exemple d'application pour générer un jeton d'accès.
Combinaisons de cotes
Pour une référence rapide, le tableau ci-dessous présente les combinaisons de cotes prises en charge ou non. Notez qu'il y a quelques cas où plus de deux dimensions peuvent être utilisées. Vous pouvez les comprendre à l'aide de l'outil Dimensions et champs ci-dessus.
compte |
browser_type |
ville |
pays |
date |
date_heure |
destination_domaine_ |
chemin destination_ |
périphérique_os |
appareile_manufacturier |
périphérique_type |
live_stream |
joueur |
referrer_domaine_ |
région |
search_terms |
social_platform |
source_type |
vidéo |
|
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
account |
s. o. | ![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
||
browser_type |
![]() |
s. o. | ![]() |
![]() |
|||||||||||||||
city |
![]() |
s. o. | ![]() |
![]() |
![]() |
![]() |
|||||||||||||
country |
![]() |
![]() |
s. o. | ![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
||||||||||
date |
![]() |
![]() |
![]() |
![]() |
s. o. | ![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
|
date_hour |
![]() |
![]() |
![]() |
![]() |
s. o. | ![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
|
destination_domain |
![]() |
![]() |
![]() |
s. o. | ![]() |
![]() |
|||||||||||||
destination_path |
![]() |
![]() |
![]() |
s. o. | |||||||||||||||
device_os |
![]() |
![]() |
![]() |
![]() |
s. o. | ![]() |
![]() |
![]() |
|||||||||||
device_manufacturer |
![]() |
![]() |
![]() |
s. o. | |||||||||||||||
device_type |
![]() |
![]() |
![]() |
![]() |
s. o. | ![]() |
![]() |
![]() |
|||||||||||
live_stream |
![]() |
![]() |
s. o. | ||||||||||||||||
player |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
s. o. | ![]() |
![]() |
![]() |
||||||||
referrer_domain |
![]() |
![]() |
![]() |
![]() |
s. o. | ![]() |
![]() |
![]() |
|||||||||||
region |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
s. o. | |||||||||||
search_terms |
![]() |
![]() |
![]() |
![]() |
s. o. | ![]() |
|||||||||||||
social_platform |
![]() |
![]() |
s. o. | ![]() |
|||||||||||||||
source_type |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
s. o. | ![]() |
|||||||||||
video |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
s. o. |
Paramètres
Voici un tableau récapitulant les paramètres disponibles dans le Analytics API. L'utilisation des paramètres est discutée plus en détail dans les sections qui suivent.
Paramètre | Obligatoire | Description | Valeurs | Par défaut |
---|
Comptes
Le (s) compte (s) Video Cloud pour lequel vous souhaitez un rapport sont spécifiés à l'aide du accounts
paramètre. Par exemple :
https://analytics.api.brightcove.com/v1/data?accounts={account1_id,account2_id}
Où filtres
La syntaxe générale des filtres est la suivante :
where=dimension1==value1;dimension2==value2
Par exemple :
https://analytics.api.brightcove.com/v1?accounts=account_id(s)&dimensions=device_type&where=video==video_id;device_type==tablet
Les virgules sont traitées comme des RO logiques et les points-virgules comme des PAD logiques. Par exemple, where=video==1234,5678;player==9876
est interprété comme « où la vidéo = 1234 OU 5678 ET lecteur = 9876"
Espaces et caractères spéciaux
Les valeurs de chaîne doivent être encodées en URI. Vous pouvez également échapper des caractères spéciaux en utilisant un « » :
where=search_terms==boston,%20ma
Vous pouvez utiliser n'importe quelle dimension comme filtre, mais seulement si cette dimension est également incluse dans le dimensions
vous demandez.
Filtrage par propriétés vidéo
À l'aide du where=video.q=={property}:{value}
filtre spécial, vous pouvez limiter votre rapport à un ensemble spécifique de vidéos en fonction d'une variété de propriétés, notamment :
- tags
- reference_id
- custom_fields [1]
- {a_specific_custom_field}
- created_at
Remarques
[ 1] La syntaxe de base est where=video.q==custom_fields:value
(correspond à la valeur dans n'importe quel champ personnalisé) ou where=video.q==myfield:value
(correspond à la valeur du champ personnalisé spécifique myfield
). Si vous effectuez une recherche sur un champ personnalisé spécifique, notez que vous devez effectuer une recherche sur le nom interne et non sur le Nom complet :

Vérifiez rapidement si vous utilisez le bon nom : le nom interne sera en minuscules et ne contiendra aucun espace.
Exemples
Voici quelques exemples de where
filtres pour la recherche sur les balises et les champs personnalisés :
Balise unique
where=video.q==tags:foo
Plusieurs balises :
where=video.q==tags:foo,bar
Champs personnalisés
where=video.q==custom_fields:foo
Balises et champs personnalisés
where=video.q==tags:foo,bar+custom_fields:fish
Pour une explication complète de cette syntaxe de requête, voir Utilisation de l'API CMS : Rechercher des vidéos.
Résumé des filtres et des valeurs admissibles
Le tableau suivant présente les valeurs autorisées pour chaque dimension utilisée comme filtre :
Filtre de cotation | Valeurs admissibles |
---|
Plages de dates
Les plages de dates, spécifiées dans from
et les to
paramètres pour tous les types de rapports, peuvent être indiquées dans différents formats :
- Valeurs textuelles :
to=now
( disponible et valeur par défaut pour toutes les requêtes)
- 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 que2013-09-12
. Pour les dates exprimées dans ce format :- Toute plage de dates spécifiée sera interprétée dans le fuseau horaire défini pour le compte
- L'heure de la date donnée sera interprétée comme minuit (
00:00:00
) à la date spécifiée dans le fuseau horaire défini pour le compte
- Dates relatives: vous pouvez exprimer l'un ou l'autre des
to
etfrom
valeurs par rapport à l'autre en d (jours) ou h (heures). 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=2014-12-31
Notez que les nombres négatifs (-2d) sont interprétés comme « avant » (l'autre valeur) et les nombres positifs (48h) sont traités comme « de » (l'autre valeur)
Pour générer un rapport sur une dimension telle que « vidéo » pour une seule journée, définissez les valeurs à et à partir de à cette date :
...&dimensions=video&from=2013-11-01&to=2013-11-01
Limite et décalage
limit
Le nombre d'articles à retourner (par défaut : 10). Pour retourner tous les articles, utilisez limit=all
. 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.
Données rapprochées
Le reconciled
paramètre est booléen. S'il est défini sur true
, les résultats seront limités aux données rapprochées. Si false
, les résultats seront limités aux données en temps réel (horaires non rapprochées).
Rapports géographiques
Dimensions pour l'analyse géographique
country
- Comme code pays ISO-3611-1, par exemple : 'NOUS'region
- Comme le code de la région ISO-3611-2, par exemple : 'US-WA'city
- Nom de la ville. par exemple : Seattle
Remarque : Pour le pays ou la région inconnu, l'API renvoie « ZZ » comme code (selon ISO-3611-alpha2).
Champs et tri
Utilisez le fields
paramètre pour spécifier les champs que vous souhaitez renvoyer. Par défaut, video_view
est renvoyé et le champ correspondant à la dimension sur laquelle vous rapporter (par exemple destination_domain
) est renvoyé. Voir dimensions et champs pour plus de détails.
Utilisez le sort
paramètre pour spécifier le champ de mesure utilisé pour trier les éléments renvoyés, par exemple : sort=video_view
. Vous pouvez inverser l'ordre de tri en annulant le champ de tri : sort= -video_view
Champs calculés
Vous pouvez ajouter des champs calculés à vos requêtes API en utilisant la syntaxe :
fields=calulated_field_name:expression
Vous pouvez utiliser des champs calculés pour créer vos propres champs personnalisés à partir de mesures existantes ou pour renommer un champ existant.
Le nom du champ calculé peut être n'importe quelle chaîne compatible URI. L'expression peut inclure des noms de champs réguliers et les opérateurs arithmétiques suivants :
+
( ajout)-
( soustraction)*
( multiplication)/
( division)^
( exposant)()
( parenthèses)
Exemples
fields=avg_seconds_viewed:video_seconds_viewed/video_view,video.name
fields=avg_incomplete_ads:(ad_mode_begin-ad_mode_complete)/video_view,video.name
fields=Video%20Views:video_view,video.name
Exemple de demande
Exemple de réponse (à la demande ci-dessus)
{
"item_count": 110,
"items": [
{
"avg_seconds_viewed": 2152.2519913106444,
"video.name": "Flamingos",
"video_seconds_viewed": 2972260,
"video": "4825279519001",
"video_view": 1381
},
{
"avg_seconds_viewed": 14.016225448334756,
"video.name": "Tiger",
"video_seconds_viewed": 16413,
"video": "4093643993001",
"video_view": 1171
},
{
"avg_seconds_viewed": 12.06,
"video.name": "Zebra",
"video_seconds_viewed": 9045,
"video": "3851389913001",
"video_view": 750
},
{
"avg_seconds_viewed": 23.343065693430656,
"video.name": "Sea-SeaTurtle",
"video_seconds_viewed": 15990,
"video": "1754276205001",
"video_view": 685
}
],
"summary": {
"avg_seconds_viewed": 274.27374399301004,
"video_seconds_viewed": 3139063,
"video_view": 11445
}
}