assistance Contacter le support | Étatétat du système du système
Contenu de la page

    Présentation : Dimensions, champs et paramètres

    Les dimensions sont les catégories de données clés pour les rapports Analytics API de données. Cette rubrique fournit un guide interactif sur les dimensions et les champs qui peuvent être renvoyés pour elles. Il indique également quelles dimensions peuvent être combinées dans un rapport et les champs disponibles pour les différentes combinaisons.

    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.

    Entrée

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

     
     

    Champs à retourner :

     
     

    (utilise un exemple de compte Brightcove)

    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

    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 combinaison de dimension ou de dimension, une UNSUPPORTED_FIELD_COMBINATION_ERROR erreur sera renvoyée.
    3. 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.
    4. 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. Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui   Oui Oui Oui Oui   Oui Oui
    browser_type Oui s. o.     Oui Oui                          
    city Oui   s. o. Oui Oui Oui                 Oui        
    country Oui   Oui s. o. Oui Oui     Oui   Oui   Oui           Oui
    date Oui Oui Oui Oui s. o.   Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui
    date_hour Oui Oui Oui Oui   s. o. Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui
    destination_domain Oui       Oui Oui s. o.           Oui           Oui
    destination_path Oui       Oui Oui   s. o.                      
    device_os Oui     Oui Oui Oui     s. o.       Oui   Oui       Oui
    device_manufacturer Oui       Oui Oui       s. o.                  
    device_type Oui     Oui Oui Oui         s. o.   Oui   Oui       Oui
    live_stream         Oui Oui           s. o.              
    player Oui     Oui Oui Oui Oui   Oui   Oui   s. o. Oui       Oui Oui
    referrer_domain Oui       Oui Oui             Oui s. o.   Oui   Oui Oui
    region Oui   Oui Oui Oui Oui     Oui   Oui       s. o.        
    search_terms Oui       Oui Oui               Oui   s. o.   Oui  
    social_platform         Oui Oui                     s. o.   Oui
    source_type Oui       Oui Oui             Oui Oui   Oui   s. o. Oui
    video Oui     Oui Oui Oui Oui   Oui   Oui   Oui Oui     Oui Oui 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 :

    Nom interne vs nom d'affichage
    Nom interne vs nom d'affichage

    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).

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