Aperçu: Dimensions, champs et paramètres

Dimensions et champs

Les dimensions sont les principaux ensembles 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 la ou les dimensions ci-dessous pour voir les champs qui peuvent être renvoyés pour cela. Vous pouvez également cliquer sur le Faire une demande pour faire une demande d'échantillon et voir les résultats. Si vous sélectionnez plusieurs dimensions incompatibles, vous verrez un message à cet effet.

  Response will appear here...

Remarques

1. 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.
2. Si vous spécifiez un champ à renvoyer qui n'est pas pris en charge pour la dimension ou la combinaison de dimensions, un UNSUPPORTED_FIELD_COMBINATION_ERROR l'erreur sera renvoyée.
3. Les bytes_delivered Le 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 3 jours.
4. En plus des champs affichés pour le video dimension, vous pouvez également retourner video.custom_fields.{field_name}

Exemple de demande

Un cas d'utilisation typique pour obtenir un rapport sur plusieurs dimensions : vous voulez une répartition des vues vidéo entre le bureau et les appareils mobiles, et vous voulez également savoir combien de vues sur les appareils mobiles étaient sur les appareils iOS par rapport aux appareils Android, et combien de vues sur les appareils mobiles les vues étaient sur des machines Mac par rapport à des 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 de vidéos pour la période du 1er janvier au 1er avril 2014.)

Exemple utilisant cURL

Si vous voulez essayer l'API en utilisant boucle , voici quelques remarques :

• Vous devrez d'abord obtenir un jeton d'accès
• Étant donné que l'URL de la demande 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 pour générer un jeton d'accès.

Combinaisons de dimensions prises en charge

Pour une référence rapide, le tableau ci-dessous montre 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.

Paramètres d'URL

Les rapports de l'API Analytics prennent en charge les paramètres d'URL suivants.

Comptes

Le ou les comptes Video Cloud 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 des filtres est :

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

Espaces et caractères spéciaux

Les valeurs de chaîne doivent être codées en URI. Vous pouvez également échapper des caractères spéciaux à l'aide d'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

Utilisation du spécial where=video.q=={property}:{value} filtre, vous pouvez limiter votre rapport à un ensemble spécifique de vidéos en fonction de diverses propriétés, notamment :

• tags
• Pièce d'identité
• 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 des champs personnalisés spécifiques, notez que vous devez rechercher sur le Nom interne , pas le nom d'affichage :

Une vérification rapide pour savoir si vous utilisez le bon nom : le nom interne sera tout en minuscules et sans espace.

Exemples

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

Balise unique

where=video.q==tags:foo

Plusieurs balises :

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

Les champs personnalisés

where=video.q==custom_fields:foo

Balises et champs personnalisés

where=video.q==tags:foo,bar+custom_fields:fish

Notez que le video.q la fonctionnalité de recherche comprend AND , OR et NOT logique comme suit :

• UNE + signe (plus) avant le terme de recherche signifie résultats doit inclure ce terme.
• UNE - (moins) signe avant le terme de recherche signifie résultats ne doit pas inclure ce terme.
• S'il n'y a ni signe plus ni signe moins, les résultats peuvent inclure ou non ce terme.

Les exemples suivants illustrent l'utilisation de cette logique.

Pour une explication complète de cette syntaxe de requête, consultez Utilisation de l'API CMS : Rechercher des vidéos.

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

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

Plages de dates

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

• Valeurs de texte :
  • to=now(disponible et la valeur par défaut pour toutes les demandes)
• Valeurs de temps d'époque en millisecondes, telles que 1377047323000
• Dates exprimées au 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'une ou l'autre des to et from valeurs l'une par rapport à l'autre en j (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 de début et de fin sur cette date :

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

Limite et décalage

Les limit est 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 parcourt les résultats.

Données rapprochées

Les reconciled paramètre est un booléen. S'il est réglé 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 (heures non rapprochées).

Rapports géographiques

Dimensions pour l'analyse géographique

• country- En tant que code de pays ISO-3611-1. par exemple: 'NOUS'
• region- En tant que code de région ISO-3611-2. par exemple: 'US-WA'
• city- Nom de Ville. par exemple: Seattle

Remarque : Pour un pays ou une 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 créez un rapport (par exemple destination_domain ) sont renvoyés. Voir dimensions et champs pour plus de détails.

Utilisez le sort paramètre pour spécifier quel champ de métrique est 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 à l'aide de la syntaxe :

fields=calulated_field_name:expression

Vous pouvez utiliser des champs calculés pour créer vos propres champs personnalisés à partir de métriques 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

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