Cette page a été traduite par l'API Cloud Translation.

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 : 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 de les bonnes pratiques pertinentes mènent également à des requêtes performantes vers l'API. Cela peut accélérer les rapports et les tableaux de bord de votre application et obtenir une une expérience utilisateur satisfaisante. Cet article décrit le système de quotas et les meilleures d'implémentation de l'API Google Analytics Data.

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

Google Analytics étant utilisé par des millions de développeurs et d'utilisateurs, les quotas sur les API empêchent le système de traiter plus de données qu'il ne peut en traiter garantissant une répartition équitable des ressources système. L'API Data pour Google Les propriétés Analytics 4 utilisent un système de seau à jetons pour gérer les quotas de l'API. À comprendre ce concept: imaginez qu'un bucket peut contenir le nombre de jetons. Toute requête API vérifiera d'abord le bucket. S'il n'y a pas il reste des jetons, la requête échoue. Sinon, la requête sera exécutée et consomment un ou plusieurs jetons du bucket selon la complexité la demande. Les jetons sont réapprovisionnés dans le bucket au maximum selon une fréquence les intervalles de temps.

Selon la méthode d'API Data que vous utilisez, vous disposez de trois quotas catégories:

Temps réel (pour runRealtimeReport)
Entonnoir de conversion (pour runFunnelReport)
Core (pour toutes les autres méthodes)

Les méthodes de l'API Data vérifient si plusieurs buckets jetons de quota:

Par propriété et par jour
Par propriété et par heure
Par projet, par propriété et par heure
Requêtes simultanées par propriété
Erreurs 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 . Si n'importe lequel des buckets est vide, la requête échoue immédiatement. affiche une erreur 429. Si aucun des buckets n'est vide, un seul le jeton est consommé à partir du bucket Requêtes simultanées par propriété et alors la requête API est exécutée. Selon la complexité de la demande, une certaine quantité de jetons sera consommée dans chacun des trois premiers buckets. une fois l'exécution terminée. La colonne Requêtes simultanées par propriété qu’un jeton soit réapprovisionné à ce moment-là.

Le quota Par projet, par propriété et par heure garantit que l'épuisement du quota 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 de généralement quatre fois le quota Par projet, par propriété et par heure. Pour la fin une propriété doit être accessible par au moins quatre projets différents avant le quota Par propriété et par heure peut être épuisé. Application des quotas au niveau au niveau du projet et de la propriété garantit que les problèmes de quota sont limités et n'affectera pas les autres propriétés auxquelles votre application accède.

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

Tous les jetons de quota sont renouvelés jusqu'à la limite, à intervalles réguliers. Consultez Quotas de l'API Google Analytics Data pour mettre à jour les informations sur les quotas. Par exemple : Les méthodes Core reçoivent 1 250 jetons de quota dans la catégorie Par projet,par propriété et par heure bucket. En supposant qu'une requête moyenne de votre application consomme 10 requêtes votre application pourra effectuer 125 requêtes Core par heure pendant une propriété standard et 10 fois ce montant (1 250 requêtes Core) pour n'importe quel type de données Analytics 360. La limite de jetons la plus élevée est l'une des les 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 difficile de prédire l'utilisation exacte du jeton avant qu'elle ne soit l'exécution. Les éléments suivants augmentent généralement la complexité d'une requête, et donc ce qui entraîne l'utilisation de jetons:

Demander plus de dimensions
Interroger une période plus longue
Inclure des dimensions ayant une cardinalité plus é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 l'utilisation des jetons est complètement différente, car la cardinalité des dimensions peut ou le volume de trafic peut être différent. Cependant, vous pouvez vous attendre dont les niveaux de trafic et la configuration sont similaires une utilisation similaire des jetons. Vous pouvez utiliser cette hypothèse pour prédire l'utilisation des jetons client pendant les phases de planification et de conception de l'application.

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. Cette opération renvoie objet PropertyQuota avec la réponse de l'API. L'objet PropertyQuota contient les montants de consommation et l'état du quota restant pour les cinq Cloud Storage. Voici un exemple de corps de requête et de réponse:

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 réussie de l'API Data, vous pouvez vous attendre à voir le quota de requêtes consommées et le quota restant pour la propriété. Il est de présenter ces informations à l'utilisateur via votre application de commande.

Gestion des quotas

Nous vous recommandons d'appliquer les bonnes pratiques de gestion des quotas décrites ci-dessous pour obtenir et exploiter tout le potentiel de l'API Data. Aussi faire passer vos propriétés à la version 360 peut augmenter le nombre aux données accessibles via l'API.

Bonnes pratiques

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

Envoyer moins de requêtes API
Envoyer des requêtes 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éliore à la fois la facilité d'utilisation et la gestion des quotas de votre application. Google Analytics met en cache vos requêtes API, mais les requêtes répétées entraîneront tout de même des jetons de quota. Par la réponse de l'API, vous pouvez réduire considérablement le nombre requêtes. Par exemple, les données intrajournalières des propriétés standards peuvent comporter quatre heures ou un délai d'expiration du cache supérieur. Consultez la section Fraîcheur des données pour Analytics.
Fusionner des requêtes:essayez de fusionner plusieurs requêtes API en une seule. Par exemple, trois requêtes de données sur une période de deux jours peuvent être utilisées par rapport à une requête sur une période de 10 jours. Si vous avez plusieurs demandes qui varient d'une seule dimension à l'autre, envisagez de les fusionner en une seule demande.
Simplification des requêtes:limitez vos requêtes au volume minimal de données. requises par votre application et l'utilisateur. un grand nombre de lignes/colonnes ou des critères de filtrage complexes consomment davantage de jetons. Périodes plus longues sont généralement plus chers (par exemple, si vous modifiez une période de 28 jours à 365) jours peuvent consommer trois fois le quota de jetons). Vous pouvez également envisager d'utiliser des dimensions présentant une cardinalité plus faible autant que possible (par exemple, requête dateHour au lieu de dateHourMinute).
Utilisation effective de limit:modification de limit dans l'API pour réduire le nombre de lignes renvoyées n'a pas d'incidence de jetons consommés. Par exemple, cinq requêtes avec une limite de 10 000 lignes peuvent consomment cinq fois plus de jetons, contre 1 requête avec une limite de 50 000.
Utilisation de la catégorie de méthode appropriée:comme indiqué ci-dessus, les limites de quota réparties en trois catégories de méthodes. Utiliser la méthode adaptée permet d'économiser du quota pour d'autres catégories. Par exemple, plutôt que créer votre propre entonnoir dans votre application à l'aide de données issues des méthodes Core, Utilisez la méthode runFunnelReport pour créer des entonnoirs de conversion.
Mettre à jour les paramètres par défaut:lorsque vous créez ou personnalisez des rapports sur votre les options par défaut proposées par votre application et ne les modifiez qu'au moment de l'exécution. Si votre application dispose d'un la plage de dates par défaut est de 365 jours. L'utilisateur consulte généralement le rapport sur 28 jours. cela finira par consommer plus de quotas 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 sélectionnent les paramètres optimaux pour leurs cas d'utilisation. Ou dans certains cas, vous pouvez également limiter les valeurs par défaut que les utilisateurs peuvent modifier.
Mise en file d'attente et chargement différé: Faites attention aux problèmes simultanés Limite de jetons "Requêtes par propriété". Votre application ne doit pas envoyer trop de requêtes à la fois. Si votre application comporte un grand nombre d'éléments d'interface utilisateur entraînant un nombre important de requêtes API, pensez à la pagination de l'interface utilisateur, le chargement différé et la mise en file d'attente des requêtes entre les tentatives. Utilisez la méthode returnPropertyQuota pour agresser surveiller l'utilisation des jetons Requêtes simultanées par propriété de votre application ;

Gestion de l'expérience utilisateur et des attentes

Donnez des commentaires aux utilisateurs avant qu'ils n'exécutent des requêtes avec une utilisation potentiellement élevée de jetons. Par exemple, les requêtes comportant plusieurs dimensions à cardinalité élevée ou ayant une une période longue pourrait utiliser un grand nombre de jetons. Avertissement et une invite de confirmation pour de telles requêtes peut empêcher les utilisateurs des modifications inutiles aux rapports et de les aider à limiter le champ d'application requêtes.
Pour les solutions de création de rapports personnalisés, permettez aux utilisateurs de comprendre des requêtes pour chaque élément du rapport. Par exemple, vous pouvez fournir une vue de débogage répertoriant l'utilisation des jetons pour chaque élément du rapport.
Envoyer des commentaires sur le type spécifique d'erreur de quota et prescrire un utilisateur action.
Comme les propriétés Google Analytics 360 ont une limite de quota 5 à 10 fois supérieure à celle aux propriétés standards, vous bénéficiez d'une plus grande flexibilité grâce à Google Analytics 360 propriétés.

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 Propriétés Google Analytics 4. Si vos utilisateurs atteignent même les limites de quota après avoir mis en œuvre les bonnes pratiques, il doit envisager de mettre à niveau son à une version 360. Les utilisateurs peuvent aussi utiliser la BigQuery Export de Google Analytics. Cela permettra aux utilisateurs d'exporter les données au niveau des événements à BigQuery et exécuter leur propre analyse.

Si vous avez d'autres questions sur les quotas de l'API Data, accédez à Discord en disponibilité générale ou posez-les sur Stack Overflow. Si vous avez des demandes spécifiques concernant la fonctionnalité vous pouvez les publier dans Issue Tracker.