Gestion des quotas pour l'API Google Analytics Data

Minhaz Kazi, Developers Advocate, Google Analytics – Février 2023

Si vous développez des applications à l'aide de l'API Google Analytics Data, vous devez comprendre le fonctionnement des quotas et des 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 conduisent également à des requêtes performantes vers l'API. Cela peut accélérer les rapports et les tableaux de bord de votre application et améliorer l'expérience utilisateur. Cet article présente le système de quotas et les bonnes pratiques de mise en œuvre de 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, le quota des requêtes API empêche le système de traiter plus de données qu'il ne peut en gérer, tout en garantissant une répartition é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 qu'un bucket peut contenir un nombre maximal de jetons. Toute requête API vérifiera d'abord le bucket. S'il ne reste plus de jetons, la requête échouera. Sinon, la requête est exécutée et consomme un ou plusieurs jetons du bucket en fonction de la complexité de la requête. Les jetons sont réapprovisionnés au maximum dans le bucket à des intervalles de temps fixes.

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

• Temps réel (pour runRealtimeReport)
• Entonnoir de conversion (pour la campagne runFunnelReport)
• Noyau (pour toutes les autres méthodes)

Les méthodes de l'API Data vérifient la présence de jetons de quota dans plusieurs buckets:

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 de serveur par projet, par propriété et par heure

Ces cinq buckets sont vérifiés chaque fois qu'une requête API Data arrive pour une propriété. Si l'un des buckets est vide, la requête échoue immédiatement et génère une erreur 429. Si aucun des buckets n'est vide, un seul jeton sera consommé à partir du bucket Requêtes simultanées par propriété, puis la requête API sera exécutée. Selon la complexité de la requête, une certaine quantité de jetons sera consommée dans chacun des trois premiers buckets une fois l'exécution terminée. Dans le cas de requêtes simultanées par propriété, un jeton est alors réapprovisionné.

Le quota Par projet, par propriété et par heure garantit que l'épuisement du quota pour un ou plusieurs utilisateurs n'aura pas d'incidence sur les autres utilisateurs de votre application. Ici, le terme projet fait référence au projet GCP de votre application. Le quota Par propriété et par heure correspond généralement à quatre fois le quota Par projet, par propriété et par heure. Par conséquent, pour les utilisateurs finaux, une propriété doit être accessible par au moins quatre projets différents avant que le quota Par propriété et par heure ne puisse être épuisé. L'application des quotas au niveau du projet et de la propriété garantit que les problèmes de quota sont limités à une seule propriété et n'affectent pas les autres propriétés auxquelles votre application accède.

Avertissement :Il est vivement déconseillé aux développeurs de segmenter les jetons de quota entre plusieurs projets d'API. Cela constitue un non-respect des Conditions d'utilisation des API Google.

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

Tous les jetons de quota sont réapprovisionnés dans la limite autorisée à intervalles indiqués. Consultez la page Quotas concernant l'API Google Analytics Data pour obtenir des informations à jour sur les quotas. 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 peut effectuer 125 requêtes de cœur par heure pour une propriété standard et 10 fois ce nombre (1 250 requêtes cœurs) pour toute propriété Analytics 360. La limite de quota plus élevée en termes de jetons est l'un des principaux avantages des propriétés Analytics 360.

La consommation de jetons pour les trois premiers buckets dépend de la complexité de la requête. Il est donc difficile de prévoir leur utilisation exacte avant l'exécution de la requête. Les opérations suivantes augmentent généralement la complexité d'une requête, ce qui entraîne l'utilisation de jetons:

• Demander plus de dimensions
• Interroger une période plus longue
• Inclure des dimensions à cardinalité plus élevée
• Interroger une propriété présentant 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 totalement différente des jetons, 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 avec des niveaux de trafic et une configuration similaires présentent une utilisation similaire des jetons. Vous pouvez utiliser cette hypothèse pour prédire l'utilisation des jetons client lors des phases de planification et de conception d'applications.

Remarque :Si vous avez déjà utilisé l'API Reporting pour Universal Analytics, vous remarquerez que l'API Reporting applique des quotas au niveau de l'application ou du projet d'API. Mais pour l'API Data, l'application est appliquée au niveau de la propriété Google Analytics ainsi qu'au niveau du projet d'API.

Surveiller l'utilisation des quotas

Pour surveiller l'utilisation des quotas et transmettre ces informations à l'utilisateur final, vous pouvez ajouter "returnPropertyQuota": true au corps de la requête API. L'objet PropertyQuota est renvoyé avec la réponse de l'API. L'objet PropertyQuota contiendra les montants de consommation et l'état du quota restant pour les cinq buckets. Voici un exemple de corps et de réponse de requête:

Requête

{
  "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 d'API Data qui aboutit, vous pouvez vous attendre à voir le quota utilisé par la requête et le quota restant pour la propriété. Il est également possible de présenter ces informations à l'utilisateur via l'interface de votre application.

Remarque :À l'étape actuelle de l'API Data, vous devez exécuter une requête API pour obtenir l'objet PropertyQuota. Si la propriété a déjà épuisé un bucket de jetons, votre requête échouera avec une erreur 429 et la réponse ne contiendra pas l'objet PropertyQuota. Si vous êtes concerné par ce changement et que vous pensez que votre application pourrait bénéficier d'un autre moyen d'accéder aux informations sur les quotas, attribuez +1 à cette demande de fonctionnalité dans l'outil Issue Tracker.

Gestion des quotas

Nous vous recommandons de mettre en œuvre les bonnes pratiques de gestion des quotas décrites ci-dessous pour tirer le meilleur parti de l'API Data. En outre, la mise à niveau de vos propriétés vers la version 360 peut augmenter la quantité de données accessibles via l'API.

Bonnes pratiques

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

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

Voici les pratiques que vous pouvez appliquer en gardant à l'esprit ces deux principes:

• Mise en cache:la mise en œuvre d'une couche de mise en cache améliore la facilité d'utilisation et la gestion des quotas pour votre application. Google Analytics met en cache vos requêtes API, mais les requêtes répétées entraînent toujours 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 pour les propriétés standards peuvent avoir un délai d'expiration du cache supérieur ou égal à quatre heures. Consultez Fraîcheur des données pour Google Analytics.
• Fusion de requêtes:essayez de fusionner plusieurs requêtes API en une seule. Par exemple, 5 requêtes de données sur une période de deux jours peuvent utiliser trois fois plus de jetons qu'une seule requête sur 10 jours. Si plusieurs requêtes ne varient que selon une seule dimension, envisagez de les fusionner en une seule requête.
• Simplification des requêtes:limitez vos requêtes au volume minimal de données requis par votre application et l'utilisateur. Un grand nombre de lignes/colonnes ou de critères de filtre complexes consommeront davantage de jetons de quota. Les plages de dates plus longues sont généralement plus chères (par exemple, passer de 28 à 365 jours peut consommer trois fois le quota de jetons). Dans la mesure du possible, vous pouvez également envisager d'utiliser des dimensions avec une cardinalité inférieure (par exemple, demandez dateHour au lieu de dateHourMinute).
• Utilisation effective de limit:la modification de l'limit dans la requête API pour réduire le nombre de lignes renvoyées n'a pas d'incidence significative sur le quota des jetons consommés. Par exemple, 5 requêtes avec une limite de 10 000 lignes peuvent consommer cinq fois les jetons de quota, alors qu'une requête avec une limite de 50 000.
• Utilisation de la bonne catégorie de méthodes:comme indiqué ci-dessus, les limites de quota sont réparties dans trois catégories de méthodes. En utilisant la méthode adaptée au cas d'utilisation approprié, vous pouvez économiser du quota sur d'autres catégories. Par exemple, plutôt que de créer votre propre entonnoir dans votre application à l'aide des données issues des méthodes principales, utilisez la méthode runFunnelReport.
• Mettre à jour les paramètres par défaut:lors de la création ou de la personnalisation de rapports sur votre plate-forme, il est possible que les utilisateurs ne mettent pas à jour les options par défaut présentées par votre application et ne les modifient qu'au moment de l'exécution. Si la plage de dates par défaut de votre application est de 365 jours et que l'utilisateur consulte généralement un rapport sur 28 jours, cela finira par consommer plus de quota que nécessaire de façon régulière. Envisagez de limiter les plages et les sélections dans les paramètres par défaut, et laissez les utilisateurs choisir les paramètres qui conviennent le mieux à leurs cas d'utilisation. Dans certains cas, vous pouvez également limiter les valeurs par défaut que les utilisateurs peuvent modifier.
• Mise en file d'attente des requêtes et chargement différé:faites attention à la limite de 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, ce qui entraîne un nombre important de requêtes API, envisagez de paginer l'interface utilisateur, de procéder au chargement différé et de mettre les requêtes en file d'attente avec un intervalle exponentiel entre les nouvelles tentatives. Utilisez la méthode returnPropertyQuota pour surveiller de manière agressive l'utilisation des jetons Requêtes simultanées par propriété de votre application.

Gestion de l’expérience utilisateur et des attentes

• Envoyez des commentaires aux utilisateurs avant qu'ils n'exécutent des requêtes avec une utilisation potentielle élevée des jetons. Par exemple, les requêtes avec plusieurs dimensions à cardinalité élevée ou avec une longue 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, fournissez aux utilisateurs un moyen de comprendre l'utilisation des requêtes de chaque élément de leur rapport. Par exemple, vous pouvez fournir une vue de débogage répertoriant l'utilisation des jetons de quota pour chaque élément du rapport.
• Indiquez le type spécifique d'erreur de quota et spécifiez l'action de l'utilisateur.
• Étant donné que 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 bénéficiez d'une plus grande flexibilité avec les propriétés Google Analytics 360.

Les augmentations de quota au-delà des limites par défaut ne sont pas disponibles pour l'API Data pour Google Analytics 4. Google Analytics 360 propose des quotas plus élevés 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 à la version 360. Les utilisateurs peuvent également utiliser l'exportation BigQuery de Google Analytics. Les utilisateurs pourront ainsi exporter des données au niveau des événements vers BigQuery et exécuter leur propre analyse.

Si vous avez d'autres questions sur les quotas de l'API Data, accédez à GA Discord ou posez-les sur Stack Overflow. Si vous avez des demandes de fonctionnalités spécifiques concernant l'API Data, vous pouvez les publier sur notre Issue Tracker.