Aperçu: API analytique 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 d'analyse de Video Cloud Studio. L'accès aux données par programmation vous offre une flexibilité supplémentaire.

Voir aussi le Référence 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
  • Combiner 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 de l' Analytics API est :

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

Headers

Authentification requise)

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

Vous devrez d'abord obtenir les informations d'identification du client (un client_id et client_secret). Il s'agit d'une opération unique qui peut être effectuée à l'aide du 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 à la fois des autorisations Analytics Read et Video Read pour les informations d'identification du client :

Autorisations pour les informations d'identification
Autorisations des Analytics API informations d'identification

Si vous créez vos identifiants directement via l'API OAuth, 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 le client_id et client_secret et transmis dans un en-tête d'autorisation avec votre requête API :

  Authorization: Bearer {access_token}

Les access_token expire après cinq minutes, vous devez donc en obtenir un pour chaque demande, ou vérifier que votre token 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)

Le passage de 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 de l'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

Les Cache-Control vous indique la durée maximale pendant laquelle les résultats seront mis en cache en secondes (dans l'exemple ci-dessus, 24 secondes). Les 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 d'analyse est d'une importance critique, vous devez savoir que plus une requête est longue, plus elle sera mise en cache longtemps, et les rapports qui récupèrent uniquement les données en temps réel (horaires non rapprochées) ne seront pas mis en cache tant que ceux qui récupèrent les 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 :

  • des données non rapprochées en temps réel ou horaires, qui sont mises à disposition immédiatement et stockées pendant 32 jours
  • les données rapprochées, qui sont stockées en permanence ; 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 rapprochées toutes les 24 heures

Vous pouvez limiter les résultats aux données rapprochées ou en temps réel à l'aide de la réconcilié 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 l'ensemble de la plage se situe dans les 32 derniers jours

Délais d'attente

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

Nombre maximum d'articles que vous pouvez retourner

Le nombre maximum d'articles pouvant être retourné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 les date dimension sur une longue période de temps, par exemple, c'est possible. Si vous atteignez la limite du million d'articles, vous devrez modifier la demande pour réduire le nombre d'articles retournés. En règle générale, la manière la plus simple de procéder consiste à réduire la plage de données (à l'aide de la from et to paramètres discutés plus loin).

Demandes simultanées

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

Par exemple :

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

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

Les demandes renvoyées avec une "erreur en attente" finiront par se terminer et seront enregistrées dans notre cache. Cela signifie que les futures demandes pour les mêmes données seront renvoyées presque instantanément, mais uniquement si la demande est effectuée 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 effectuant à nouveau la même demande.

Les meilleures pratiques

Types de demande

Analytics API Accepte trois types de requête

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}
Rapport de mission
Données d'engagement détaillées disponibles pour les périodes des 32 derniers jours. Voir la rubrique engagement pour plus de détails.
Point de terminaison d'informations vidéo
Une donnée d'analyse spécifique servie avec une latence minimale. Voir Point de terminaison 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 se trouvent désormais dans un document distinct : Présentation des dimensions, des champs et des paramètres.

Paramètres

Des informations détaillées sur les paramètres se trouvent désormais dans un document séparé : Présentation des dimensions, des champs et des paramètres.

Rapports de mission

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

Engagement de 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 des joueurs

Pour obtenir les valeurs moyennes de toutes les vidéos visionnées dans un lecteur, 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

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