L'API Google Agenda est soumise à des quotas pour garantir une utilisation équitable par tous les utilisateurs. Lorsque vous utilisez l'API Calendar, vous devez tenir compte de trois limites importantes :
- 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 d'Agenda : évitez de dépasser les limites d'utilisation d'Agenda.
- Limites opérationnelles : vous pouvez être soumis à une limite de fréquence à tout moment. Par exemple, si vous tentez d'écrire dans un seul agenda en succession rapide.
Types de quotas d'utilisation de l'API Calendar
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 : nombre de requêtes envoyées par un utilisateur spécifique dans votre projet Cloud. Cette limite vise à vous aider à assurer une répartition équitable de l'utilisation entre vos utilisateurs.
Les quotas sont calculés à la minute à l'aide d'une fenêtre glissante. Par conséquent, si vous dépassez votre quota par minute lors d'un pic de trafic, vous serez limité lors de la prochaine fenêtre pour vous assurer que votre utilisation reste en moyenne dans les limites des quotas.
Si l'un des quotas est dépassé, vous êtes soumis à une limite de débit et recevez un code d'état 403 usageLimits ou un code d'état 429 usageLimits pour vos requêtes. Si cela se produit, voici ce que vous pouvez faire :
- Veillez à suivre toutes les bonnes pratiques : utiliser le backoff exponentiel, randomiser les schémas de trafic, utiliser les 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 vous atteignez la limite de quota par utilisateur, vous pouvez effectuer les opérations suivantes :
- Si vous utilisez un compte de service, répartissez la charge entre les utilisateurs ou divisez-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 le dépasser, 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 le rythme de vos 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. Nous vous recommandons de relancer la requête après un court intervalle. Si les requêtes arrivent toujours trop rapidement, nous vous le redemandons, 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é entre les tentatives. La documentation Cloud Storage explique bien comment cela fonctionne et quel est l'algorithme recommandé. Si vous utilisez une bibliothèque cliente Google, cette opération est normalement gérée pour vous. Consultez la documentation de votre bibliothèque. Normalement, vous devez utiliser l'implémentation de la bibliothèque plutôt que d'écrire la vôtre.
Randomiser les modèles de trafic
Les clients d'agenda sont sujets à des pics de trafic 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, ce qui entraînerait une limitation du débit et des délais d'attente.
Pour éviter cela, assurez-vous de répartir votre trafic tout au long de la journée, dans la mesure du possible. Si votre client doit effectuer une synchronisation quotidienne, demandez-lui de choisir une heure aléatoire (différente pour chaque client). Si vous devez effectuer une opération de manière régulière, variez l'intervalle de +/- 25 %. Cela permettra de répartir le trafic de manière plus uniforme 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 qu'un élément change dans l'agenda de l'utilisateur. Un anti-pattern consiste ici à interroger de manière répétée chaque calendrier qui vous intéresse. Cela épuisera très rapidement tout votre quota. Par exemple, si votre application compte 5 000 utilisateurs et interroge le calendrier de chacun d'eux une fois par minute, cela nécessitera un quota par minute d'au moins 5 000, même avant toute opération.
Les applications côté serveur peuvent s'inscrire aux notifications push, ce qui nous permet de vous avertir lorsqu'un événement intéressant se produit. Ces méthodes 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 le eventType pour lequel vous souhaitez recevoir des notifications. Pour en savoir plus, consultez Notifications push.
Comptabilité 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 fonction des quotas "par minute, par projet et par utilisateur", et non de l'utilisateur que vous usurpez. Cela signifie que le compte de service risque de manquer de quota et d'être limité en termes de fréquence, même s'il fonctionne 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 l'utilisateur qui sera facturé. Elle n'est utilisée 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 les limites de quota dans la pratique (par exemple, en effectuant des nouvelles tentatives avec un intervalle exponentiel entre les tentatives) et pour minimiser toute perturbation potentielle pour vos utilisateurs, nous vous recommandons vivement de tester ce scénario dans un environnement réel.
Pour éviter qu'un tel test n'interfère 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 la même manière que votre projet de production. Vous pouvez ensuite définir des quotas artificiellement bas pour ce projet et observer le comportement de votre application.
Tarifs
L'utilisation de l'API Google Agenda n'implique aucuns frais supplémentaires. Le dépassement des limites de quota de requêtes n'entraîne pas de frais supplémentaires et votre compte n'est pas facturé.