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

    Vue d'ensemble : Analytics API v1

    Dans cette rubrique, vous obtiendrez une vue d'ensemble de l'API Analytics.
     

    Introduction

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

    Voir également la référence de l'API.

    Utilisations typiques

    Voici quelques utilisations typiques de l'API :

    • Création de graphiques et d'affichages personnalisés
    • Travailler avec plusieurs API ensemble - par exemple, obtenir des données vidéo en utilisant CMS API pour les vidéos avec le plus grand nombre 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 obtenir des exemples de solutions, consultez

    URL de base

    L'URL de base de l' Analytics API est :

      <code class="language-http translate="Non » > https://analytics.api.brightcove.com/v1

    En-têtes

    Authentification (obligatoire)

    Le Analytics API utilise le service OAuth Brightcove pour authentifier les appels.

    Vous devrez d'abord obtenir les informations d'identification client (a client_id et client_secret). Il s'agit d'une opération unique qui peut être effectuée à l'aide de l' interface utilisateur des informations d'identification OAuth. Vous pouvez obtenir les informations d'identification du client directement à partir du service Brightcove OAuth en utilisant CURL , Postman , ou Insomnia.

    Vous avez besoin des autorisations de lecture Analytics et de lecture vidéo pour les informations d'identification du client :

    <img class="bcls-image » alt="Autorisations pour < span translate="Non » Informations d'identification de l'API > Analytics » src= » /assets/images/analytiics/getting-started/analytics-permissions.png "/>
    Autorisations des Analytics API informations d'identification

    Si vous créez vos informations d'identification directement via l'API OAuth, les autorisations requises sont les suivantes :

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

    Vous aurez également besoin d'un access_token, qui est obtenu en utilisant le client_id et client_secret et transmis dans un en-tête Autorisation avec votre requête API :

      Authorization: Bearer {access_token}

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

    Accept-Encoding: gzip (optional)

    Passer cet en-tête entraînera le retour de la réponse sous forme compressée. Cela peut améliorer les performances des rapports volumineux.

    Mise en cache

    Pour des raisons de performances, les réponses 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 de cache
    En-têtes de contrôle de cache

    Le vous Cache-Control indique la durée maximale pendant laquelle 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, ce n'est probablement pas un problème, mais si la fraîcheur des données analytiques est d'une importance cruciale, vous devez savoir que plus une requête s'exécute, plus elle sera mise en cache, et les rapports qui récupèrent des données en temps réel (horaires non réconciliés) 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). Trouvez une explication complète des données en temps réel et réconciliées si vous le souhaitez ; la version courte est que le Analytics API repose sur deux compartiments de données :

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

    Vous pouvez limiter les résultats aux données rapprochées ou en temps réel à l'aide du paramètre réconcilié .

    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 une petite plage de dates et assurez-vous que l'ensemble de la plage se situe dans les 32 derniers jours

    Délais

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

    Nombre maximum d'articles que vous pouvez retourner

    Le nombre maximal d'articles pouvant être retournés est d'un million. Dans la plupart des cas, il est peu probable que vous atteignez la limite, mais si vous demandez des rapports sur la date dimension sur une longue période de temps, par exemple, c'est possible. Si vous atteignez la limite de millions d'articles, vous devrez modifier la demande pour réduire le nombre d'articles retournés. En général, le moyen le plus simple de le faire est de réduire la plage de données (en utilisant le 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.

    Par exemple :

    1. Démarrez une demande d'API « A ».
    2. Démarrez la demande d'API « B » pour le même compte.
    3. La demande « B » ne sera pas complétée tant que « A » n'aura pas été complétée.
    4. Si la demande « A » prend trop de temps, la requête « A » recevra une erreur indiquant « votre demande est en attente ; réessayez ».
    5. Si la requête « A » prend trop de temps, la requête « B » peut recevoir la même erreur. Notez que la requête « B » obtiendra une erreur si le temps nécessaire pour terminer A + B est supérieur à notre valeur de délai d'attente.

    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 enregistrées dans notre cache. Cela signifie que les futures demandes pour les mêmes données retourneront presque instantanément, mais seulement si la requête est faite avant l'expiration du cache de cinq minutes.

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

    Meilleures pratiques

    Types de requête

    Analytics API Accepte trois types de requête

    Données (aussi appelées rapport)
    Un rapport sur un ou plusieurs dimensions. Le point de terminaison d'une demande de rapport est le suivant :
      https://analytics.api.brightcove.com/v1/data?accounts={account_id(s)}&dimensions={dimensions}
    Rapport sur l'engagement
    Données d'engagement détaillées disponibles pour les périodes au cours des 32 derniers jours. Consultez la section « Engagement » pour plus de détails.
    Point de terminaison d'informations vidéo
    Un élément spécifique de données analytiques servi avec une latence minimale. Voir Video Data Endpoint pour plus d'informations.

    Où les filtres et les plages de dates peuvent être appliqués 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 sont maintenant 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 sont maintenant dans un document séparé : Vue d'ensemble des dimensions, des champs et des paramètres.

    Rapports sur l'engagement

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

    Mobilisation 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
      

    Engagement joueur

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

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

    Engagement envers la 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
      

    Analyses en direct

    Le Analytics API fournit deux points de terminaison pour récupérer des analyses pour les flux Brightcove Live, soit par série chronologique, soit par événement. Voir le Analytics API Reference pour plus de détails.