Présentation : Dimensions, champs et paramètres

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.

Remarque : que vous ne pouvez pas renvoyer le champ video.custom_fields, mais dans certains cas, vous pouvez retourner video.custom_fields.{field_name}. Ceci est représenté ci-dessous, mais comme n' {field_name} est pas un vrai nom de champ, il ne sera pas utilisé dans les demandes d'exemple.

Entrée

Sélectionnez Dimension (s) sur (s) à signaler :

Champs à retourner :

(utilise un exemple de compte Brightcove)

Données pour ad_mode_begin , ad_mode_complete , et play_request est disponible à partir du 13/06/2016.

Sortie

`from` Date la plus ancienne pour cette combinaison de dimensions :

Exemple de demande d'API :

Données de réponse

  Response will appear here...

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 du fields 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 renvoyer video.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.

Combinaisons de cotes
	`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-DDformat, tel que 2013-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 et from 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).

Les données en temps réel ne sont disponibles que pour les 32 jours précédents. Si vous définissez reconciled=false et la from date antérieure à 32 jours il y a 32 jours, l'API ne renvoie aucune donnée, car il n'y a pas de données non réconciliées à ce stade.

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

Les champs disponibles pour retourner ou trier dépendent des mesures renvoyées pour la ou les dimensions sur lesquelles vous produirez des rapports. Ces paramètres sont strictement validés, et votre demande renverra une erreur si le fields ou sort Le paramètre pointe vers un champ non valide pour la demande.

Pour les rapports sur les dimensions vidéo, les valeurs de tri valides incluent les champs de métadonnées vidéo: video.name , video.reference_id , et video.tags.

nom_video_vs. nom_video.name

video_name est le nom de la vidéo enregistré dans les données d'analyse
video.name est le nom de la vidéo dans les métadonnées vidéo

Dans la plupart des cas, les deux valeurs seront identiques, mais il y a des cas où elles ne seront pas :

Dans certains cas, vous pouvez voir une valeur pour video.name, mais pas pour video_name- dans ce cas, le nom de la vidéo pour une raison quelconque n'a pas été envoyé au collecteur de données analytiques
Dans certains cas, les valeurs peuvent être différentes - dans ce cas, la vidéo a été renommée à un moment donné : video.name est le nom actuel de la vidéo dans votre médiathèque Video Cloud ; video_name sera le nom de la vidéo du au moment où les données ont été envoyées au collecteur de données analytiques (si vous interrogez une période au cours de laquelle le nom a changé, la valeur renvoyée par l'API sera le nom associé à la majorité des vues pendant la période).

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

https://analytics.api.brightcove.com/v1/data?accounts=1752604059001&dimensions=video&fields=avg_seconds_viewed:video_seconds_viewed/video_view,video_seconds_viewed,video.name&sort=-video_view&limit=4

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

Contenu de la page

Présentation : Dimensions, champs et paramètres

Dimensions et champs

Sélectionnez Dimension (s) sur (s) à signaler :

Champs à retourner :Sélectionner toutDésélectionner tout

from Date la plus ancienne pour cette combinaison de dimensions :

Exemple de demande d'API :

Données de réponse

Remarques

Exemple de demande

Exemple d'utilisation de cURL

Exemple

Combinaisons de cotes

Paramètres

Comptes

Où filtres

Espaces et caractères spéciaux

Filtrage par propriétés vidéo

Remarques

Exemples

Balise unique

Plusieurs balises :

Champs personnalisés

Balises et champs personnalisés

Résumé des filtres et des valeurs admissibles

Plages de dates

Limite et décalage

Données rapprochées

Rapports géographiques

Dimensions pour l'analyse géographique

Champs et tri

Champs calculés

Exemples

Exemple de demande

Exemple de réponse (à la demande ci-dessus)

Champs à retourner :

`from` Date la plus ancienne pour cette combinaison de dimensions :