Présentation: dimensions, champs et paramètres

Dimensions et champs

Les dimensions sont les principaux compartiments de données pour l'analyse. Pour voir les guides complets des dimensions individuelles, cliquez sur le nom de la dimension dans la liste ci-dessous.

Sélectionnez les dimensions ci-dessous pour voir les champs qui peuvent être retournés pour cela. Vous pouvez également cliquer sur le Faire une demande bouton pour faire une demande d'échantillon et voir les résultats. Si vous sélectionnez plusieurs dimensions incompatibles, vous verrez un message à cet effet.

Note: que vous ne pouvez pas retourner le champ video.custom_fieldsmais dans certains cas vous peut retourner video.custom_fields.{field_name}. Ceci est représenté ci-dessous, mais depuis {field_name} n’est pas un vrai nom de champ, il ne sera pas utilisé dans les exemples de demandes.

Contribution

Sélectionnez Dimension (s) à signaler:

Champs à retourner:

(utilise un exemple de compte Brightcove)

Données pour ad_mode_begin, ad_mode_complete play_request est disponible à partir de 06-13-2016.

Sortie

Plus tôt `from` date 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 retournés que s'ils sont spécifiés dans la valeur du fields paramètre.
Si vous spécifiez un champ à renvoyer non pris en charge pour la combinaison de dimensions ou de UNSUPPORTED_FIELD_COMBINATION_ERROR l'erreur sera renvoyée.
Le système bytes_delivered le champ inclut toutes les données fournies par Video Cloud aux clients, y compris les données vidéo, les images, les pistes de texte et autres actifs, ainsi que player code lui-même. Certaines de ces données proviennent de CDN et peuvent ne pas être disponibles avant 3 jours.
En plus des champs indiqués pour le video dimension, vous pouvez aussi retourner video.custom_fields.{field_name}

Demande d'exemple

Un cas d'utilisation typique pour obtenir un rapport sur plusieurs dimensions: vous voulez une ventilation des vues vidéo entre les postes de travail et les appareils mobiles et souhaitez également savoir combien de vues d'appareils mobiles étaient sur des appareils iOS ou Android et combien de postes de travail les vues étaient sur les Mac contre les machines Windows. Actuellement, dans le module Studio Analytics, aucun rapport standard ne fournit ces informations, mais vous pouvez les obtenir via ce module. 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 vues vidéo pour la période allant de janvier 1 à avril 1 dans 2014.)

Exemple utilisant cURL

Si vous voulez essayer l'API en utilisant cURL, voici quelques notes:

Vous devrez d'abord obtenir un jeton d'accès
Puisque l'URL de la requête inclura toujours Paramètres d'URL, vous devrez le mettre entre guillemets (simples ou doubles)

Échantillon

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 $ACCESS_TOKEN avec 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 générer un jeton d'accès.

Combinaisons de dimensions prises en charge

Pour une référence rapide, le tableau ci-dessous indique les combinaisons de dimensions prises en charge ou non. Notez qu'il existe quelques cas où plus de deux dimensions peuvent être utilisées. Vous pouvez les comprendre en utilisant le Dimensions et champs outil ci-dessus.

Combinaisons de cote supportées
	`account`	`browser_type`	`city`	`country`	`date`	`date_hour`	`destination_domain`	`destination_path`	`device_os`	`device_manufacturer`	`device_type`	`live_stream`	`player`	`referrer_domain`	`region`	`search_terms`	`social_platform`	`source_type`	`video`
`account`	n / a
`browser_type`		n / a
`city`			n / a
`country`				n / a
`date`					n / a
`date_hour`						n / a
`destination_domain`							n / a
`destination_path`								n / a
`device_os`									n / a
`device_manufacturer`										n / a
`device_type`											n / a
`live_stream`												n / a
`player`													n / a
`referrer_domain`														n / a
`region`															n / a
`search_terms`																n / a
`social_platform`																	n / a
`source_type`																		n / a
`video`																			n / a

Paramètres

Vous trouverez ci-dessous un tableau résumant les paramètres disponibles dans le Analytics API. L'utilisation des paramètres est discutée plus en détail dans les sections suivantes.

Paramètre	Requis	Description	Valeurs	Défaut

Responsable Administration et Finance

Le système Video Cloud les comptes pour lesquels 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ù les filtres

La syntaxe générale pour les filtres est:

where=dimension1==value1;dimension2==value2

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 OR logiques et les points-virgules comme des AND logiques. Par exemple, where=video==1234,5678;player==9876 est interprété comme "where video = 1234 OR 5678 ET player = 9876 "

Espaces et personnages spéciaux

Les valeurs de chaîne doivent être codé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, uniquement. si cette dimension est également incluse dans le dimensions vous demandez.

Filtrage par propriétés vidéo

En utilisant le spécial where=video.q=={property}:{value} filtre, vous pouvez limiter votre rapport à un ensemble spécifique de vidéos en fonction d'une variété de propriétés, notamment:

étiquettes
Pièce d'identité
Les champs personnalisés
{a_specific_custom_field}
créé à

Remarques

La syntaxe de base est where=video.q==custom_fields:value (correspond à la valeur dans un champ personnalisé) ou where=video.q==myfield:value (correspond à la valeur dans le champ personnalisé spécifique myfield). Si vous recherchez des champs personnalisés spécifiques, notez que vous devez effectuer une recherche sur Nom interne, pas le nom d'affichage:

Une vérification rapide si vous utilisez le bon nom: le nom interne sera tous en minuscules et ne contiennent aucun espace.

Exemples

Voici quelques exemples where filtres pour la recherche sur les balises et les champs personnalisés:

Balise unique

where=video.q==tags:foo

Tags multiples:

where=video.q==tags:foo,bar

Les champs personnalisés

where=video.q==custom_fields:foo

Tags 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 En utilisant l' CMS API: Rechercher des vidéos.

Résumé des filtres et des valeurs autorisées

Le tableau suivant montre les valeurs autorisées pour chaque dimension utilisée comme filtre:

Filtre de dimension	Valeurs admissibles

Plages de dates

Les plages de dates, spécifiées dans from et to paramètres pour tous les types de rapports, peuvent être indiqués dans différents formats:

Valeurs de texte:
- to=now (disponible et la valeur par défaut pour toutes les demandes)
Valeurs de temps de l'époque en millisecondes, telles que 1377047323000
Dates exprimées en format de date international standard ISO 8601: 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 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 un seul jour, définissez les valeurs de et à partir de cette date:

...&dimensions=video&from=2013-11-01&to=2013-11-01

Limite et décalage

Le système limit est le nombre d'éléments à renvoyer (par défaut: 10). Pour retourner tous les éléments, 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 pages à travers les résultats.

Données réconciliées

Le système reconciled Le paramètre est un booléen. S'il est défini sur true, les résultats seront limités aux données réconciliées. Si false, les résultats seront limités aux données en temps réel (non synchronisées).

Les données en temps réel sont uniquement disponibles pour les jours 32 précédents. Si vous définissez reconciled=false et la from date antérieure à 32 il y a quelques jours, l'API ne renverra 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 le code de pays ISO-3611-1. par exemple: 'US'
region - Comme le code de région ISO-3611-2. par exemple: 'US-WA'
city - Nom de Ville. Ex .: Seattle

Remarque: Pour un pays ou une région inconnus, 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 voulez retourner. Par défaut, video_view est renvoyé et le champ correspondant à la dimension que vous signalez (par exemple destination_domain) sont retournés. Voir dimensions et champs pour plus de détails.

Utilisez le sort paramètre pour spécifier quel champ métrique est utilisé pour trier les éléments retourné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 revenir ou trier dépendent du métrique retourné pour la (les) dimension (s) que vous signalez. Ces paramètres sont strictement validés et votre requête renverra une erreur si le fields or sort le paramètre pointe vers un champ non valide pour la requête.

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

nom_vidéo par rapport à nom_vidéo

video_name est le nom de la vidéo enregistré dans les données analytiques
video.name est le nom de la vidéo dans les métadonnées de la 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.namemais pas pour video_name - Dans ce cas, le nom de la vidéo n'a pas été envoyé pour une raison quelconque au collecteur de données d'analyse.
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 Video Cloud médiathèque; video_name sera le nom de la vidéo de la vidéo au moment où les données ont été envoyées au collecteur de données analytiques (si vous interrogez une période dans 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 demandes d'API en utilisant la syntaxe suivante:

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 normaux et les opérateurs arithmétiques suivants:

+ (une addition)
- (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

Demande d'échantillon

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) à signaler:

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

Plus tôt from date pour cette combinaison de dimensions:

Exemple de demande d'API:

Données de réponse

Remarques

Demande d'exemple

Exemple utilisant cURL

Échantillon

Combinaisons de dimensions prises en charge

Paramètres

Responsable Administration et Finance

Où les filtres

Espaces et personnages spéciaux

Filtrage par propriétés vidéo

Remarques

Exemples

Balise unique

Tags multiples:

Les champs personnalisés

Tags et champs personnalisés

Résumé des filtres et des valeurs autorisées

Plages de dates

Limite et décalage

Données réconciliées

Rapports géographiques

Dimensions pour l'analyse géographique

Champs et tri

Champs calculés

Exemples

Demande d'échantillon

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

Champs à retourner:

Plus tôt `from` date pour cette combinaison de dimensions: