Paper Contacter le support | état du système L'état 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 Analytics API rapports de données. Cette rubrique fournit un guide interactif sur les dimensions et les champs pouvant être renvoyés. Il indique également les dimensions pouvant être combinées dans un rapport et les champs disponibles pour les différentes combinaisons.

    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.

    Contribution

    Sélectionnez Dimension (s) à signaler:

    Champs à retourner:

    (utilise un exemple de compte Brightcove)

    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

    1. 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.
    2. 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.
    3. 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.
    4. 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 Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui
    browser_type Oui n / a Oui Oui
    city Oui n / a Oui Oui Oui Oui
    country Oui Oui n / a Oui Oui Oui Oui Oui Oui
    date Oui Oui Oui Oui n / a Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui
    date_hour Oui Oui Oui Oui n / a Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui
    destination_domain Oui Oui Oui n / a Oui Oui
    destination_path Oui Oui Oui n / a
    device_os Oui Oui Oui Oui n / a Oui Oui Oui
    device_manufacturer Oui Oui Oui n / a
    device_type Oui Oui Oui Oui n / a Oui Oui Oui
    live_stream Oui Oui n / a
    player Oui Oui Oui Oui Oui Oui Oui n / a Oui Oui Oui
    referrer_domain Oui Oui Oui Oui n / a Oui Oui Oui
    region Oui Oui Oui Oui Oui Oui Oui n / a
    search_terms Oui Oui Oui Oui n / a Oui
    social_platform Oui Oui n / a Oui
    source_type Oui Oui Oui Oui Oui Oui n / a Oui
    video Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui Oui 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:

    Nom interne vs nom d'affichage
    Nom interne vs 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).

    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

    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

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

    Dernière mise à jour de la page le 21 juil.2020