Paper Contacter le support | état du système L'état du système
Contenu de la page

    Aperçu: Analytics API v1

    Dans cette rubrique, vous obtiendrez un aperçu de la Analytics API.

    Introduction

    Le système Analytics API vous permet d'obtenir des données d'analyse pour votre Video Cloud comptes directement. Vous pouvez également afficher les rapports d'analyse intégrés dans le module d'analyse de Video Cloud Studio. L'accès aux données par programme vous donne une flexibilité supplémentaire.

    Voir aussi le Référence de l'API.

    Utilisations typiques

    Voici quelques utilisations typiques de l'API:

    • Créer des graphiques et des affichages personnalisés
    • Utilisation simultanée de plusieurs API - par exemple, obtenir des données vidéo à l'aide du CMS API pour les vidéos avec le plus de vues au cours de la semaine précédente
    • Combinaison de vos données d'analyse vidéo avec d'autres données d'analyse de site
    • Pour quelques exemples de solutions, voir

    URL de base

    L'URL de base pour le Analytics API est:

      https://analytics.api.brightcove.com/v1

    En-têtes

    Authentification requise)

    Le système Analytics API utilise Brightcove Service OAuth authentifier les appels

    Vous devrez d'abord obtenir les informations d'identification du client (un client_id et client_secret). Ceci est une opération unique qui peut être effectuée en utilisant le OAuth Credentials UI. Vous pouvez obtenir les informations d'identification du client directement à partir du service Brightcove OAuth à l'aide de CURL CLASSIQUE, Facteurou Insomnie.

    Vous devez disposer des autorisations Analytics Read et Video Read pour les informations d'identification du client:

    Autorisations pour Analytics API Lettres de créance
    Autorisations pour Analytics API Lettres de créance

    Si vous créez vos identifiants directement via le OAuth API, les autorisations requises sont:

      [
        "video-cloud/analytics/read"
        "video-cloud/video/read"
      ]

    Vous aurez également besoin d'un access_token, qui est obtenu en utilisant client_id et client_secret et passé dans un en-tête Authorization avec votre demande d'API:

      Authorization: Bearer {access_token}

    Le système access_token expire après cinq minutes, vous devez donc en obtenir un pour chaque demande ou vérifier que votre jeton est toujours valide. Voir Obtenir des jetons d'accès pour une explication détaillée sur la façon d'obtenir des jetons d'accès, y compris des exemples de code.

    Accept-Encoding: gzip (optionnel)

    Si vous passez cet en-tête, la réponse sera renvoyée sous forme compressée. Cela peut améliorer les performances pour les rapports volumineux.

    La mise en cache

    Pour des raisons de performances, les réponses aux API sont mises en cache pendant environ 5 minutes, bien que la durée exacte puisse varier en fonction de plusieurs facteurs. Pour toute Analytics API requête, vous pouvez obtenir des informations sur le cache à partir des en-têtes de réponse:

    En-têtes de contrôle du cache
    En-têtes de contrôle du cache

    Le système Cache-Control vous indique le temps maximum pendant lequel les résultats seront mis en cache en secondes (dans l'exemple ci-dessus, 24 secondes). le Last-Modified et Expires les en-têtes vous indiquent quand le cache actuel a été créé et quand il expirera.

    Dans la plupart des cas, cela ne pose probablement pas de problème, mais si la fraîcheur des données analytiques est d'une importance critique, sachez que plus une requête est longue, plus elle sera mise en cache et plus elle rapportera des données en temps réel (non réconciliées). ne seront pas mis en cache tant que ceux qui récupèrent des données réconciliées (uniquement, ou en plus des données en temps réel). Trouver un explication complète des données en temps réel et réconciliées si tu veux; la version courte est que le Analytics API repose sur deux compartiments de données:

    • données en temps réel ou non rapprochées, qui sont mises à disposition immédiatement et stockées pour les jours 32
    • les données réconciliées, qui sont stockées de manière permanente; les données en temps réel sont réconciliées pour améliorer la précision et stockées dans le référentiel de données rapprochées toutes les heures 24

    Vous pouvez limiter les résultats aux données réconciliées ou en temps réel en utilisant réconciliés paramètre.

    Pour minimiser la mise en cache:

    • Utilisez le reconciled=false paramètre pour limiter les résultats aux données en temps réel
    • Utilisez un petit plage de dates, et assurez-vous que toute la gamme tombe dans les derniers jours 32

    Délais d'attente

    Analytics API demande un délai d'attente après 8 minutes s'il n'est pas terminé. Si vous voyez des délais d'expiration inférieurs à 8 minutes, la cause est une limite côté client.

    Nombre maximum d'articles que vous pouvez retourner

    Le nombre maximal d'éléments pouvant être renvoyés est d'un million. Dans la plupart des cas, il est peu probable que vous atteigniez la limite, mais si vous demandez des rapports sur date dimension sur une longue période, par exemple, c’est possible. Si vous atteignez la limite d'un million d'éléments, vous devrez modifier la demande pour réduire le nombre d'éléments retournés. En règle générale, le moyen le plus simple de procéder consiste à réduire la plage de données (en utilisant la from et to paramètres discutés plus tard).

    Demandes simultanées

    Un seul compte est limité à une demande à la fois. Plusieurs demandes simultanées s'exécuteront en série.

    Exemple :

    1. Démarrer une demande d'API "A".
    2. Démarrez la demande d'API "B" pour le même compte.
    3. La demande "B" ne se termine pas tant que "A" n'est pas terminé.
    4. Si la requête "A" prend trop de temps, la requête "A" recevra une erreur indiquant "votre requête est en attente, réessayez".
    5. Si la demande "A" prend trop de temps, la requête "B" risque de recevoir la même erreur. Notez que la requête "B" obtiendra une erreur si le temps nécessaire pour compléter A + B est supérieur à notre valeur de timeout.

    Si vous effectuez plusieurs demandes simultanées, elles seront traitées une à la fois, dans l'ordre reçu.

    Les demandes qui retournent avec une "erreur en attente" finiront par être terminées et seront enregistrées dans notre cache. Cela signifie que les demandes futures pour les mêmes données retourneront presque instantanément, mais seulement si la demande est faite avant l'expiration du cache de cinq minutes.

    Vos systèmes doivent gérer l'erreur en attente en attendant les minutes 2-4 et en faisant à nouveau la même demande.

    Les meilleures pratiques

    Types de demandes

    Le système Analytics API accepte trois types de requêtes

    Données (également appelées un rapport)
    Un rapport sur un ou plusieurs dimensions. Le point de terminaison d'une demande de rapport est:
      https://analytics.api.brightcove.com/v1/data?accounts={account_id(s)}&dimensions={dimensions}
    Engagerapport de gestion
    Données d'engagement détaillées disponibles pour les périodes des derniers jours 32. Voir la section d'engagement pour plus de détails.
    Point de fin de l'information vidéo
    Un morceau spécifique de données analytiques servi avec une latence minimale. Voir Endpoint de données vidéo pour plus d’informations.

    Où les filtres et plages de dates peut être appliqué aux rapports. Les demandes de rapport peuvent avoir des paramètres supplémentaires détaillés dans ce document.

    Dimensions et champs

    Des informations détaillées sur les dimensions et les champs figurent désormais dans un document séparé: Vue d'ensemble des dimensions, des champs et des paramètres.

    Paramètres

    Des informations détaillées sur les paramètres figurent maintenant dans un document séparé: Vue d'ensemble des dimensions, des champs et des paramètres.

    Engagerapports de gestion

    Rapports d'engagement détaillés montrant les vues pour chaque 100e partie de vidéos (ou les moyennes de toutes les vidéos pour un compte ou player) sont disponibles pour les périodes des 32 derniers jours. (Les demandes de plages de dates en dehors des 32 derniers jours renverront une erreur.)

    Engagement du compte

    Pour obtenir des valeurs moyennes d'engagement sur les vidéos visionnées, utilisez le point de terminaison:

      
          https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id
      

    Player participation

    Pour obtenir des valeurs moyennes pour toutes les vidéos visionnées dans un player, utilisez le point de terminaison:

      
          https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/players/:player_id
      

    Engagement vidéo

    Pour obtenir des données d'engagement pour une vidéo spécifique, utilisez le point de terminaison:

      
          https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/videos/:video_id
      

    Live Analytiques

    Le système Analytics API fournit deux points de terminaison pour récupérer des analyses pour Brightcove Live flux, soit par une série chronologique ou par événement. Voir le Analytics API Référence pour en savoir plus.


    Dernière mise à jour de la page le 12 juin 2020