Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Limites d'utilisation

L'API Google Calendar est soumise à des quotas pour garantir une utilisation équitable par tous les utilisateurs. Tenez compte de trois limites importantes lorsque vous utilisez l'API Calendar :

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 Calendar : l'API Calendar est un service partagé qui présente des limites visant à protéger les performances globales du système Google Workspace. Pour en savoir plus, consultez Respecter les limites d'utilisation d'Agenda.
Limites opérationnelles : ces limites peuvent être appliquées à tout moment. Par exemple, des limites peuvent s'appliquer si vous tentez d'écrire dans un seul agenda rapidement et de manière successive.

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 permet de 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. Un pic de trafic rapide qui dépasse votre quota par minute entraîne une limitation du débit lors de la fenêtre suivante pour garantir qu'en moyenne, votre utilisation reste 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 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 pour cette limite de seuil quotidien.

Le tableau suivant détaille la limite :

Type de limite de seuil	Limite
Par jour et par projet	1 000 000 de requêtes

Pour en savoir plus, consultez le modèle standardisé Google Workspace pour les outils et les 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é entre les tentatives pour vous 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 d'intervalle exponentiel entre les tentatives 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 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 :

Vous envoyez une requête à l'API Google Calendar.
Si la requête échoue, attendez 1 + random_number_milliseconds, puis effectuez une nouvelle tentative.
Si la requête échoue, attendez 2 + random_number_milliseconds, puis effectuez une nouvelle tentative.
Si la requête échoue, attendez 4 + random_number_milliseconds, 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), avec n incrémenté de 1 pour chaque itération (requête).
random_number_milliseconds correspond à 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 de random_number_milliseconds est recalculée après chaque nouvelle tentative de la requête.
La valeur maximum_backoff est 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 une valeur maximum_backoff de 64 secondes, une fois celle-ci atteinte, 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

Toute utilisation standard de l'API Google Calendar est disponible sans frais supplémentaires. Le dépassement des limites de requêtes de quota devrait entraîner des frais sur votre compte de facturation Google Cloud plus tard en 2026. Pour en savoir plus, consultez le modèle standardisé Google Workspace pour les outils et les 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. Les demandes d'ajustement de quota qui augmenteraient considérablement la valeur du quota peuvent nécessiter plus de temps pour être approuvées.

Tous les projets ne sont pas soumis aux mêmes quotas. À mesure que votre utilisation de Google Cloud s'accroît, vos valeurs de quota peuvent devoir augmenter. Si vous prévoyez une augmentation significative de votre utilisation, vous pouvez anticiper cette évolution en demandant des ajustements de quotas sur la page Quotas et limites système de la console Google Cloud.

Pour en savoir plus, consultez les ressources suivantes :

Résoudre les problèmes

Si l'un des quotas est dépassé, vous êtes limité en débit et recevez un 403 usageLimits code d'état ou un 429 usageLimits code d'état en réponse à vos requêtes.

Si tel est le cas, procédez comme suit :

Assurez-vous de suivre toutes les bonnes pratiques : utilisez un intervalle exponentiel entre les tentatives, randomisez les tendances du 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 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, nous vous recommandons généralement de ne pas dépasser la valeur par défaut, car votre application peut atteindre d'autres types de limites, par exemple, les limites d'utilisation générales de Calendar 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 tendances du trafic

Les clients Calendar sont sujets à des tendances de trafic irrégulières causées par plusieurs clients effectuant des opérations en même temps. Par exemple, une mauvaise pratique courante pour un client Calendar consiste à effectuer une synchronisation complète à minuit. Cela dépasse généralement votre quota par minute et entraîne une limitation du débit et des intervalles exponentiels entre les tentatives.

Pour éviter cela, répartissez 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 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 permet de répartir le trafic de manière plus uniforme et d'améliorer l'expérience utilisateur.

Utiliser les notifications push

Un cas d'utilisation courant consiste à effectuer une action chaque fois qu'un élément est modifié dans l'agenda de l'utilisateur. Une mauvaise pratique consiste à interroger de manière répétée chaque agenda d'intérêt. Cela épuise rapidement votre quota. Par exemple, si votre application compte 5 000 utilisateurs et interroge l'agenda de chaque utilisateur 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 permet à Calendar de vous avertir lorsqu'un événement intéressant se produit. Ces notifications nécessitent plus de travail pour être configurées, mais elles vous permettent d'utiliser le quota plus efficacement et d'améliorer l'expérience utilisateur. Spécifiez le eventType pour lequel vous souhaitez recevoir des notifications. Pour en savoir plus, consultez Push notifications.

Allocation appropriée avec des 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 pour les quotas "par minute, par utilisateur et par projet", et non pour l'utilisateur que vous imitez. Cela signifie que le compte de service est susceptible d'épuiser son quota et d'être limité en débit, 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 est facturé. Google n'utilise ce paramètre 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 gère correctement l'atteinte des limites de quota dans la pratique (par exemple, via des nouvelles tentatives avec un intervalle exponentiel entre les tentatives) et pour minimiser toute perturbation potentielle pour vos utilisateurs, testez votre application dans un environnement réaliste.

Pour effectuer des tests sans interférer avec l'utilisation réelle de votre application, enregistrez un projet de test distinct dans la console Google Cloud et ensuite configurez l'écran de consentement OAuth de manière semblable à 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.

Quotas du serveur MCP Calendar

Le serveur MCP Calendar utilise une métrique d'allocation du coût des requêtes. Les tableaux suivants détaillent le coût des requêtes pour chaque méthode du serveur MCP Calendar par section :

Quotas MCP Calendar