Gestion des quotas pour l'API Google Analytics Data

Minhaz Kazi, Developer Advocate, Google Analytics – février 2023

Si vous développez des applications à l'aide de l'API Google Analytics Data, vous devez comprendre comment fonctionnent les quotas et les limites de l'API. Si votre application est bien conçue, les utilisateurs sont moins susceptibles d'atteindre les limites de quota. Certaines bonnes pratiques pertinentes permettent également d'effectuer des requêtes performantes auprès de l'API. Cela peut accélérer les rapports et les tableaux de bord dans votre application, et améliorer l'expérience utilisateur. Cet article décrit le système de quotas et les bonnes pratiques pour implémenter l'API Google Analytics Data.

Comprendre le système de quotas de l'API Google Analytics Data

Google Analytics étant utilisé par des millions de développeurs et d'utilisateurs, les quotas sur les requêtes API protègent le système contre le traitement d'un volume de données trop important, tout en assurant une distribution équitable des ressources système. L'API Data pour les propriétés Google Analytics 4 utilise un système de token bucket pour gérer les quotas d'API. Pour comprendre le concept, imaginez un bucket pouvant contenir un nombre maximal de jetons. Toute requête d'API vérifie d'abord le bucket. S'il n'y en a plus, la requête échoue. Sinon, la requête sera exécutée et consommera un ou plusieurs jetons du bucket en fonction de sa complexité. Les jetons sont réapprovisionnés dans le bucket jusqu'à la limite maximale à des intervalles de temps fixes.

Selon la méthode de l'API Data que vous utilisez, il existe trois catégories de quotas distinctes :

Les méthodes de l'API Data vérifieront plusieurs buckets pour les [jetons de quota][Quotas de l'API Google Analytics Data]:

  1. Par propriété et par jour
  2. Par propriété et par heure
  3. Par projet, par propriété et par heure
  4. Requêtes simultanées par propriété
  5. Erreurs du serveur par projet, par propriété et par heure

Ces cinq buckets sont vérifiés chaque fois qu'une requête Data API est reçue pour une propriété. Si l'un des buckets est vide, la requête échoue immédiatement avec une erreur 429. Si aucun des buckets n'est vide, un seul jeton est consommé à partir du bucket Requêtes simultanées par propriété, puis la requête API est exécutée. En fonction de la complexité de la requête, un certain nombre de jetons seront consommés dans chacun des trois premiers buckets une fois l'exécution terminée. Le nombre de requêtes simultanées par propriété sera également réinitialisé à ce moment-là.

Le quota Par projet, par propriété et par heure garantit que l'épuisement du quota pour un ou plusieurs utilisateurs n'affectera pas les autres utilisateurs de votre application. Ici, project fait référence au projet GCP de votre application. Le quota Par propriété et par heure est généralement quatre fois supérieur au quota Par projet, par propriété et par heure. Ainsi, pour les utilisateurs finaux, une propriété doit être consultée par au moins quatre projets différents avant que le quota Par propriété et par heure puisse être épuisé. L'application des quotas au niveau du projet et de la propriété permet de limiter les problèmes de quota à une seule propriété et de ne pas affecter les autres propriétés auxquelles votre application accède.

Le quota erreurs du serveur fait référence aux réponses de l'API avec les codes 500 ou 503. Si votre application génère trop d'erreurs lors de l'accès à une propriété, elle épuisera le quota Erreurs du serveur par projet, par propriété et par heure.

Tous les jetons de quota sont réinitialisés à la limite aux intervalles indiqués. Pour obtenir des informations à jour sur les quotas, consultez [Quotas de l'API Google Analytics Data]. Par exemple, les méthodes Core obtiennent 1 250 jetons de quota dans le bucket Par projet,par propriété et par heure. En supposant qu'une requête moyenne de votre application consomme 10 jetons de quota, votre application pourra effectuer 125 requêtes Core par heure pour une propriété standard et 10 fois plus (1 250 requêtes Core) pour toute propriété Analytics 360. La limite de jetons de quota plus élevée est l'un des principaux avantages des propriétés Analytics 360.

Comme la consommation de jetons pour les trois premiers buckets dépend de la complexité de la requête, il est difficile de prédire l'utilisation exacte de jetons avant l'exécution de la requête. Les éléments suivants augmentent généralement la complexité d'une requête, ce qui entraîne une utilisation de jetons :

  • Demander plus de dimensions
  • Interroger une période plus longue
  • Inclure des dimensions à cardinalité élevée
  • Interroger une propriété avec un nombre d'événements plus élevé

Par conséquent, la même requête pour deux propriétés différentes peut entraîner une utilisation de jetons complètement différente, car la cardinalité des dimensions peut varier ou le volume de trafic peut être différent. Toutefois, vous pouvez vous attendre à ce que les propriétés présentant des niveaux de trafic et une configuration similaires aient une utilisation de jetons similaire. Vous pouvez utiliser cette hypothèse pour prédire l'utilisation des jetons client lors des phases de planification et de conception des applications.

Surveiller l'utilisation du quota

Pour surveiller l'utilisation du quota et communiquer ces informations à votre utilisateur final, vous pouvez ajouter "returnPropertyQuota": true au corps de la requête API. L'objet PropertyQuota sera renvoyé avec la réponse de l'API. L'objet PropertyQuota contient les quantités consommées et l'état du quota restant pour les cinq buckets. Voici un exemple de corps de requête et de réponse :

Demande

{
  "dimensions": [
    {
      "name": "medium"
    }
  ],
  "metrics": [
    {
      "name": "activeUsers"
    }
  ],
  "dateRanges": [
    {
      "startDate": "yesterday",
      "endDate": "yesterday"
    }
  ],
  "returnPropertyQuota": true
}

Réponse

{
  "dimensionHeaders": [
    {
      "name": "medium"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  ...
  
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 24997
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 4997
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 1247
    }
  },
  
  "kind": "analyticsData#runReport",
  ...
}

Ainsi, après chaque requête API Data réussie, vous pouvez voir la quantité de quota utilisée par la requête et la quantité de quota restante pour la propriété. Il est également possible de présenter ces informations à l'utilisateur via l'interface de votre application.

Gestion des quotas

Nous vous recommandons d'appliquer les bonnes pratiques de gestion des quotas décrites ci-dessous pour exploiter pleinement l'API Data. De plus, passer à Analytics 360 pour vos propriétés peut augmenter la quantité de données accessibles via l'API.

Bonnes pratiques

Il existe deux grandes façons de réduire l'utilisation du quota pour votre application :

  • Envoyer moins de requêtes API
  • Envoyer des requêtes d'API moins complexes

En gardant ces deux principes à l'esprit, voici les pratiques que vous pouvez mettre en œuvre :

  • Mise en cache : l'implémentation d'une couche de mise en cache améliorera l'usabilité et la gestion des quotas de votre application. Google Analytics mettra en cache vos requêtes d'API, mais les requêtes répétées continueront à générer des jetons de quota. En mettant en cache la réponse de l'API, vous pouvez réduire considérablement le nombre de requêtes répétées. Par exemple, les données intrajournalières des propriétés standards peuvent avoir un délai d'expiration du cache de quatre heures ou plus. Consultez Fraîcheur des données pour Google Analytics.
  • Fusionner les requêtes : essayez de fusionner plusieurs requêtes API en une seule. Par exemple, cinq demandes de données sur une période de deux jours peuvent utiliser trois fois plus de jetons de quota qu'une demande sur une période de 10 jours. Si vous avez plusieurs demandes qui ne diffèrent que par une seule dimension, envisagez de les fusionner en une seule demande.
  • Simplifiez les requêtes : limitez vos requêtes à la quantité minimale de données requise par votre application et l'utilisateur. Un grand nombre de lignes/colonnes ou des critères de filtrage complexes consomment plus de jetons de quota. Les plages de dates plus longues sont généralement plus coûteuses (par exemple, le passage d'une plage de dates de 28 jours à 365 jours peut consommer trois fois plus de jetons de quota). Dans la mesure du possible, vous pouvez également envisager d'utiliser des dimensions avec une cardinalité inférieure (par exemple, demander dateHour au lieu de dateHourMinute).
  • Utilisation efficace de limit : la modification de limit dans la requête API pour réduire le nombre de lignes renvoyées n'a pas d'incidence significative sur les jetons de quota consommés. Par exemple, cinq requêtes avec une limite de 10 000 lignes peuvent consommer cinq fois plus de jetons de quota qu'une requête avec une limite de 50 000 lignes.
  • Utiliser la bonne catégorie de méthode : comme indiqué ci-dessus, les limites de quota sont réparties sur trois catégories de méthodes. Utiliser la bonne méthode pour le bon cas d'utilisation peut vous permettre d'économiser du quota dans d'autres catégories. Par exemple, plutôt que de créer votre propre entonnoir dans votre application à l'aide des données des méthodes Core, utilisez la méthode runFunnelReport pour créer des entonnoirs.
  • Mise à jour des paramètres par défaut : lorsque les utilisateurs créent ou personnalisent des rapports sur votre plate-forme, ils peuvent ne pas mettre à jour les options par défaut proposées par votre application et ne les modifier qu'au moment de l'exécution. Si votre application a une période par défaut de 365 jours et que l'utilisateur consulte généralement des rapports sur 28 jours, cela consommera régulièrement plus de quota que nécessaire. Envisagez de limiter les plages et les sélections dans les paramètres par défaut, et laissez les utilisateurs sélectionner les paramètres optimaux pour leurs cas d'utilisation. Dans certains cas, vous pouvez également limiter les paramètres par défaut que les utilisateurs peuvent modifier.
  • Mise en file d'attente des requêtes et chargement différé : tenez compte de la limite de jetons Concurrent Requests Per Property (Requêtes simultanées par propriété). Votre application ne doit pas envoyer trop de requêtes en même temps. Si votre application comporte un grand nombre d'éléments d'interface utilisateur qui génèrent un nombre important de requêtes API, envisagez de paginer l'interface utilisateur, d'utiliser le chargement différé et de mettre en file d'attente les requêtes avec un intervalle exponentiel entre les tentatives. Utilisez la méthode returnPropertyQuota pour surveiller de manière agressive l'utilisation des jetons Concurrent Requests Per Property de votre application.

Gérer l'expérience et les attentes des utilisateurs

  • Fournissez des commentaires aux utilisateurs avant qu'ils n'exécutent des requêtes susceptibles d'utiliser un grand nombre de jetons. Par exemple, les requêtes comportant plusieurs dimensions à cardinalité élevée ou une grande période peuvent utiliser un grand nombre de jetons. L'affichage d'un avertissement et d'une invite de confirmation pour ces requêtes peut empêcher les utilisateurs d'apporter des modifications inutiles aux rapports et les aider à limiter le champ d'application de leurs requêtes.
  • Pour les solutions de reporting personnalisées, permettez aux utilisateurs de comprendre l'utilisation des requêtes de chaque élément de leur rapport. Par exemple, vous pouvez fournir une vue de débogage listant l'utilisation des jetons de quota pour chaque élément de rapport.
  • Fournissez des commentaires sur le type spécifique d'erreur de quota et indiquez à l'utilisateur les actions à effectuer.
  • Les propriétés Google Analytics 360 bénéficient d'une limite de quota 5 à 10 fois supérieure à celle des propriétés standards. Vous disposez donc de plus de flexibilité avec les propriétés Google Analytics 360.

Il n'est pas possible d'augmenter les quotas de l'API Data au-delà des limites par défaut pour Google Analytics 4. Google Analytics 360 offre des limites de quotas plus élevées pour les propriétés Google Analytics 4. Si vos utilisateurs atteignent les limites de quota même après avoir appliqué les bonnes pratiques, ils doivent envisager de passer à Analytics 360 pour leurs propriétés. Les utilisateurs peuvent également utiliser l'exportation BigQuery de Google Analytics. Les utilisateurs pourront ainsi exporter les données au niveau des événements vers BigQuery et effectuer leurs propres analyses.

Pour toute autre question concernant les quotas de l'API Data, rendez-vous sur GA Discord ou posez votre question sur Stack Overflow. Si vous avez des demandes de fonctionnalités spécifiques concernant l'API Data, vous pouvez les publier dans notre Issue Tracker.