L'API Google Agenda est soumise à des quotas pour s'assurer qu'elle est utilisée de manière équitable par tous les utilisateurs. Lorsque vous utilisez l'API Calendar, vous devez tenir compte de trois limites importantes :
Quotas d'utilisation de l'API : appliqués par projet et par utilisateur. Pour en savoir plus, consultez Types de quotas d'utilisation de l'API Calendar.
Limites d'utilisation générales de Google Agenda : l'API Google Agenda est un service partagé qui comporte des limites pour protéger les performances globales du système Google Workspace. Pour en savoir plus, consultez Éviter les limites d'utilisation de l'agenda.
Limites opérationnelles : ces limites peuvent être modifiées à tout moment. Par exemple, si vous tentez d'écrire dans un seul agenda en succession rapide.
Quotas de l'API Calendar
Deux types de quotas sont appliqués :
Par minute et par projet : il s'agit du nombre de requêtes que votre projet Google Cloud peut effectuer en une minute.
Par minute, par utilisateur et par projet : il s'agit du nombre de requêtes qu'un utilisateur spécifique peut effectuer 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. Si vous envoyez un pic de trafic rapide qui dépasse votre quota par minute pendant une minute, vous serez limité en débit pendant la période suivante pour vous assurer que votre utilisation reste en moyenne dans les limites des quotas.
Le tableau suivant détaille ces limites :
| Type de limite d'utilisation | Limite |
|---|---|
| Par minute et par projet | 10 000 requêtes |
| Par minute, par utilisateur et par projet | 600 requêtes |
Seuil de facturation quotidien
Cette limite par jour et par projet définit le nombre maximal de requêtes que votre projet Google Cloud peut utiliser sur une période de 24 heures avant que des frais ne s'appliquent.
L'utilisation en dessous de ce seuil n'entraîne pas de frais supplémentaires et votre compte Google Cloud n'est pas facturé. Les informations de facturation complètes seront communiquées plus tard en 2026, au moins 90 jours avant l'entrée en vigueur des modifications.
Vous ne pouvez pas demander d'augmentation de cette limite de seuil quotidien.
Le tableau suivant indique la limite :
| Type de limite de seuil | Limite |
|---|---|
| Par jour et par projet | 1 000 000 de requêtes |
Pour en savoir plus, consultez Modèle standardisé Google Workspace pour les outils et API d'agent.
Résoudre les erreurs de quota basées sur le temps
Pour toutes les erreurs basées sur le temps (maximum de N requêtes par X minutes), nous vous recommandons que votre code intercepte l'exception et utilise un intervalle exponentiel tronqué pour s'assurer que vos appareils ne génèrent pas de charge excessive.
L'intervalle exponentiel entre les tentatives est une stratégie standard de gestion des exceptions pour les applications réseau. Un algorithme de temporisation de retransmission exponentielle relance les requêtes en augmentant de manière exponentielle le temps d'attente entre les requêtes jusqu'à ce que la durée maximale de l'intervalle entre les tentatives soit atteinte. Si les requêtes échouent toujours, il est important que les délais entre les requêtes augmentent au fil du temps jusqu'à ce que la requête aboutisse.
Exemple d'algorithme
Un algorithme d'intervalle exponentiel entre les tentatives relance les requêtes de manière exponentielle, en augmentant le temps d'attente entre les tentatives jusqu'à ce que la durée maximale de l'intervalle exponentiel soit atteinte. Exemple :
- Envoyez une requête à l'API Google Agenda.
- Si la requête échoue, attendez 1 +
random_number_millisecondssecondes, puis effectuez une nouvelle tentative. - Si la requête échoue, attendez 2 +
random_number_millisecondssecondes, puis effectuez une nouvelle tentative. - Si la requête échoue, attendez 4 +
random_number_millisecondssecondes, puis effectuez une nouvelle tentative. - Poursuivez ainsi jusqu'à atteindre la valeur
maximum_backoff. - Continuez d'attendre et de relancer la requête jusqu'à atteindre le nombre maximal de tentatives, mais n'augmentez pas le temps d'attente entre les tentatives.
où :
- Le temps d'attente est défini sur
min(((2^n)+random_number_milliseconds), maximum_backoff), avecnincrémenté de 1 pour chaque itération (requête). random_number_millisecondscorrespond à un nombre aléatoire de millisecondes inférieur ou égal à 1 000. Cela permet d'éviter les cas où de nombreux clients se retrouvent synchronisés pour une raison quelconque et effectuent tous une nouvelle tentative en même temps, en envoyant des requêtes par vagues synchronisées. La valeur derandom_number_millisecondsest recalculée après chaque nouvelle tentative de la requête.- La valeur
maximum_backoffest généralement définie sur 32 ou 64 secondes. La valeur appropriée dépend du cas d'utilisation.
Le client peut continuer à effectuer des nouvelles tentatives après avoir atteint la valeur maximum_backoff.
Au-delà de ce point, il n'est pas nécessaire de continuer à augmenter la durée de l'intervalle exponentiel entre les tentatives. Par exemple, si un client utilise un délai maximum_backoff de 64 secondes, une fois celui-ci atteint, il peut effectuer une nouvelle tentative toutes les 64 secondes. À un certain moment, vous devez empêcher les clients d'effectuer des tentatives à l'infini.
Le temps d'attente entre les nouvelles tentatives et le nombre de tentatives dépendent de votre cas d'utilisation et des conditions du réseau.
Tarifs
L'utilisation standard de l'API Google Agenda est disponible sans frais supplémentaires. Le dépassement des limites de quota de demandes entraînera des frais sur votre compte de facturation Google Cloud plus tard en 2026. Pour en savoir plus, consultez Modèle standardisé Google Workspace pour les outils et API d'agent.
Demander une augmentation du quota
Selon l'utilisation des ressources de votre projet, vous pouvez demander un ajustement de quota. Les appels d'API effectués par un compte de service sont considérés comme utilisant un seul compte. La demande d'ajustement de quota ne garantit pas l'approbation. L'approbation des demandes d'ajustement de quota qui augmenteraient considérablement la valeur du quota peut prendre plus de temps.
Tous les projets ne sont pas soumis aux mêmes quotas. À mesure que votre utilisation de Google Cloud s'accroît, vos quotas peuvent augmenter en conséquence. Si vous prévoyez une augmentation notable de l'utilisation, vous pouvez anticiper cette évolution en demandant des ajustements de quota sur la page Quotas et limites du système de la console Google Cloud.
Pour en savoir plus, consultez les ressources suivantes :
- À propos des ajustements de quotas
- Afficher votre utilisation et vos limites de quotas
- Demander une augmentation de limite de quota
Résoudre les problèmes
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 429
usageLimits en réponse à vos requêtes.
Si cela se produit, vous pouvez essayer les solutions suivantes :
Veillez à suivre toutes les bonnes pratiques : utilisez un intervalle exponentiel entre les tentatives, randomisez les schémas de trafic et utilisez des notifications push.
Si votre projet se développe et que vous avez plus d'utilisateurs, vous pouvez demander une augmentation de quota.
Si vous atteignez les limites 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 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 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.
Testez vos limites de quota en enregistrant un projet de test distinct dont la configuration est semblable à celle de votre projet de production. Pour en savoir plus, consultez Tester la gestion des limites de quota.
Randomiser 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. 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 de carence.
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 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 à effectuer une action chaque fois qu'un événement change dans l'agenda de l'utilisateur. Un anti-pattern consiste ici à interroger de manière répétée tous les calendriers qui vous intéressent. Cela consommera très rapidement l'intégralité de 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écessite 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 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.
Allocation 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 utilisateur et par projet", 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 à facturer. Cette valeur n'est utilisée que pour les calculs de quota. Pour en savoir plus, consultez Limiter les requêtes par utilisateur.
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 utilisant des nouvelles tentatives avec intervalle exponentiel) et pour minimiser les perturbations potentielles pour vos utilisateurs, nous vous recommandons vivement de tester votre scénario dans un environnement réel.
Pour effectuer des tests sans interférences avec l'utilisation de votre application réelle, nous vous recommandons d'enregistrer un projet de test distinct dans la console Google Cloud, puis de configurer l'écran de consentement OAuth de la même manière que pour votre projet de production. Vous pouvez ensuite définir des limites de quota artificiellement basses pour ce projet et observer le comportement de votre application.