L'API Google Agenda est soumise à des quotas pour s'assurer qu'elle est utilisée de manière équitable par tous les utilisateurs. Trois limites importantes sont à prendre en compte lors de l'utilisation de l'API Agenda:
- Les quotas d'utilisation des API sont appliqués par projet et par utilisateur. Pour en savoir plus, consultez la section suivante.
- Limites d'utilisation générales d'Agenda: évitez les limites d'utilisation d'Agenda.
- Limites opérationnelles:vous pouvez être soumis à une limite de débit à tout moment. Par exemple, si vous essayez d'écrire dans un seul agenda de manière rapprochée.
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 et par projet et par utilisateur:il s'agit du nombre de requêtes effectuées par un utilisateur particulier 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 par minute à l'aide d'une fenêtre glissante. Par conséquent, une rafale de trafic rapide qui dépasse votre quota par minute pendant une minute entraînera une limitation du débit pendant la fenêtre suivante afin de vous assurer que, en moyenne, votre utilisation reste dans les limites des quotas.
Si l'un de ces 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. Dans ce cas, procédez comme suit:
- Veillez à respecter toutes les bonnes pratiques : utilisez la stratégie de rétrogradation exponentielle, saisissez de manière aléatoire les modèles de trafic et utilisez 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 avez atteint la limite de quota par utilisateur, 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 risque de commencer à atteindre d'autres types de limites, par exemple les limites d'utilisation générales d'Agenda ou les limites opérationnelles.
Demande d'augmentation du 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 débit de vos requêtes, nous renvoyons une réponse 403 "usageLimits" ou une réponse 429 (voir la documentation complète sur les erreurs). Il ne s'agit pas d'une erreur fatale. Nous vous invitons à réessayer la requête après un court intervalle. Si les requêtes arrivent toujours trop rapidement, nous vous redemanderons, 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 règle générale, vous devez utiliser un intervalle exponentiel tronqué entre les tentatives. La documentation Cloud Storage explique bien son fonctionnement et l'algorithme à privilégier. 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.
Aléatoirer les modèles de trafic
Les clients de calendrier 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. Vous dépasseriez presque certainement votre quota par minute, ce qui entraînerait une limitation de débit et des retards.
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 de manière régulière, variez l'intervalle de plus ou moins 25%. Cela permet de répartir le trafic de manière plus uniforme et de proposer une expérience utilisateur bien meilleure.
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-modèle consiste à interroger à plusieurs reprises chaque calendrier d'intérêt. Cela utilisera très rapidement tout votre quota. Par exemple, si votre application compte 5 000 utilisateurs et interroge le calendrier de chaque utilisateur une fois par minute, vous aurez besoin d'un quota par minute d'au moins 5 000 utilisateurs, même avant que le travail ne soit effectué.
Les applications côté serveur peuvent s'inscrire aux notifications push, ce qui nous permet de vous informer lorsqu'un événement intéressant se produit. Leur configuration nécessite plus de travail, mais elles permettent d'utiliser votre quota de manière beaucoup plus efficace et d'offrir une meilleure expérience utilisateur. Assurez-vous de spécifier le eventType pour lequel vous souhaitez recevoir une notification. Pour en savoir plus, consultez la section 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 fonction des quotas "par minute et par projet et par utilisateur", et non de l'utilisateur que vous imitez. Cela signifie que le quota du compte de service risque de s'épuiser et que la limite de débit sera appliquée, 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 l'utilisateur qui sera facturé. Il n'est utilisé que pour les calculs de quota. Pour en savoir plus, consultez la section 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 en pratique (par exemple, en effectuant des nouvelles tentatives avec un délai avant expiration exponentiel) 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 distinct à des fins de test 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
L'utilisation de l'API Google Agenda est disponible sans frais supplémentaires. Si vous dépassez les limites de requêtes de quota, vous ne payez pas de frais supplémentaires et votre compte n'est pas facturé.