L'API Google Agenda est soumise à des quotas pour garantir une utilisation équitable par tous les utilisateurs. Trois limites importantes sont à prendre en compte lorsque vous utilisez l'API Agenda :
- Les quotas d'utilisation de l'API sont appliqués par projet et par utilisateur. Pour en savoir plus, consultez la section suivante.
- Limites générales d'utilisation de l'agenda : évitez les limites d'utilisation de l'agenda.
- Limites opérationnelles : vous pouvez être limité à tout moment. Par exemple, si vous tentez d'écrire dans un seul agenda en succession rapide.
Types de quotas d'utilisation de l'API Agenda
Deux types de quotas sont appliqués :
- Par minute et par projet : il s'agit du nombre de requêtes effectuées par votre projet Google Cloud.
- Par minute, par projet et par utilisateur : il s'agit du nombre de requêtes effectuées par un utilisateur spécifique de votre projet Cloud. Cette limite vise à vous aider à garantir une répartition équitable de l'utilisation entre vos utilisateurs.
Les quotas sont calculés par minute à l'aide d'une fenêtre glissante. Par conséquent, un pic de trafic rapide qui dépasse votre quota par minute pendant une minute entraînera une limitation du débit lors de la fenêtre suivante pour garantir qu'en moyenne, votre utilisation reste dans les limites des quotas.
Si l'un des quotas est dépassé, vous êtes limité et recevez un
403 usageLimits code d'état
ou un
429 usageLimits code d'état
pour vos requêtes. Dans ce cas, voici ce que vous pouvez faire :
- Assurez-vous de suivre toutes les bonnes pratiques : utilisez un intervalle exponentiel entre les tentatives, randomisez les schémas de trafic, utilisez des notifications push.
- Si votre projet se développe et que vous avez plus d'utilisateurs, vous pouvez demander une augmentation du quota par projet.
- Si la limite de quota par utilisateur est atteinte, vous pouvez procéder comme suit :
- Si vous utilisez un compte de service, allouez la charge aux utilisateurs ou répartissez-la entre plusieurs comptes de service.
- Bien que vous puissiez demander une augmentation du quota par utilisateur, il n'est généralement pas recommandé de l'augmenter au-delà de la valeur par défaut, car votre application peut commencer à atteindre d'autres types de limites, par exemple les limites générales d'utilisation de l'agenda, ou les limites opérationnelles.
Demande d'augmentation de quota
Pour afficher ou modifier les limites d'utilisation de votre projet, ou pour demander une augmentation des quotas, procédez comme suit :
- Si vous ne possédez pas encore de compte de facturation pour votre projet, créez-en un.
- Accédez à la page "API activées" de la bibliothèque d'API dans la console APIs, puis sélectionnez une API dans la liste.
- Sélectionnez Quotas pour afficher et modifier les paramètres associés aux quotas. Pour afficher les statistiques d'utilisation, sélectionnez Utilisation.
Utiliser un intervalle exponentiel entre les tentatives
Lorsque nous souhaitons que vous ralentissiez votre taux de requêtes, nous renvoyons une réponse 403 "usageLimits" ou une réponse 429 (consultez la documentation complète sur les erreurs). Il ne s'agit pas d'une erreur fatale et nous nous attendons à ce que vous relanciez la requête après un court intervalle. Si les requêtes arrivent toujours trop rapidement, nous vous le demanderons à nouveau, et ainsi de suite. Pour que cela fonctionne correctement, il est important que les délais entre les requêtes augmentent au fil du temps.
En général, vous devez utiliser un intervalle exponentiel tronqué. La documentation Cloud Storage explique bien comment cela fonctionne et l'algorithme préféré. Si vous utilisez une bibliothèque cliente Google, cela sera normalement géré pour vous. Consultez la documentation de votre bibliothèque. En règle générale, vous devez utiliser l'implémentation de la bibliothèque plutôt que d'écrire la vôtre.
Randomiser les schémas de trafic
Les clients Agenda sont sujets à des schémas de trafic irréguliers causés par plusieurs clients effectuant des opérations en même temps. Par exemple, une mauvaise pratique courante pour un client Agenda consiste à effectuer une synchronisation complète à minuit. Cela entraînerait presque certainement un dépassement de votre quota par minute, ainsi qu'une limitation du débit et des intervalles exponentiels entre les tentatives.
Pour éviter cela, assurez-vous que votre trafic est réparti tout au long de la journée dans la mesure du possible. Si votre client doit effectuer une synchronisation quotidienne, demandez-lui de déterminer une heure aléatoire (différente pour chaque client). Si vous devez effectuer une opération régulièrement, faites varier l'intervalle de +/- 25 %. Cela permettra de répartir le trafic plus uniformément et d'offrir une bien meilleure expérience utilisateur.
Utiliser les notifications push
Un cas d'utilisation courant consiste à vouloir effectuer une action chaque fois que quelque chose change dans l'agenda de l'utilisateur. Un anti-modèle consiste ici à interroger de manière répétée chaque agenda d'intérêt. Cela utilisera très rapidement tout votre quota. Par exemple, si votre application compte 5 000 utilisateurs et interroge l'agenda de chaque utilisateur une fois par minute, cela nécessitera un quota par minute d'au moins 5 000, avant même que le travail ne soit effectué.
Les applications côté serveur peuvent s'inscrire aux notifications push, ce qui nous permet de vous avertir lorsque quelque chose d'intéressant se produit. Ces notifications nécessitent plus de travail pour être configurées, mais permettent une utilisation beaucoup plus efficace de votre quota et offrent une meilleure expérience utilisateur. Assurez-vous de spécifier l'eventType pour lequel vous souhaitez être averti. Pour en savoir plus, consultez
Notifications push.
Comptabilisation appropriée avec les comptes de service
Si votre application effectue des requêtes à l'aide de
la délégation au niveau du domaine,
le compte de service est facturé par défaut en ce qui concerne les quotas "par minute, par
projet et par utilisateur", et non l'utilisateur que vous usurpez. Cela signifie que le compte de service risque de manquer de quota et d'être limité, même s'il peut fonctionner sur les agendas de plusieurs utilisateurs. Pour éviter cela, utilisez le paramètre d'URL quotaUser (ou l'en-tête HTTP x-goog-quota-user) pour indiquer quel utilisateur sera facturé. Il n'est utilisé que pour les calculs de quota. Pour en savoir plus, consultez
Limiter les requêtes par utilisateur
dans la documentation Cloud.
Tester la gestion des limites de quota
Pour vous assurer que votre application peut gérer correctement l'atteinte des limites de quota dans la pratique (par exemple, en effectuant des nouvelles tentatives avec un intervalle exponentiel entre les tentatives) et pour minimiser les perturbations potentielles pour vos utilisateurs, nous vous recommandons vivement de tester ce scénario dans un environnement réel.
Pour qu'un tel test n'interfère pas avec l'utilisation réelle de votre application, nous vous recommandons d'enregistrer un projet de test distinct dans la console Google APIs et de le configurer de manière similaire à votre projet de production. Vous pouvez ensuite définir des quotas artificiellement bas pour ce projet et observer le comportement de votre application.
Tarifs
Toute utilisation de l'API Google Agenda est disponible sans frais supplémentaires. Le dépassement des limites de requêtes de quota n'entraîne pas de frais supplémentaires et votre compte n'est pas facturé.