Gérer les quotas

L'API Google Calendar comporte des quotas qui garantissent une utilisation équitable par tous les utilisateurs. Il existe trois limites importantes à prendre en compte lors de l'utilisation de l'API Calendar:

  • Les quotas d'utilisation d'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:le débit peut être limité à tout moment. C'est le cas, par exemple, si vous tentez d'écrire rapidement des messages dans un même agenda.

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:il s'agit du nombre de requêtes effectuées par un utilisateur particulier de votre projet Cloud. Cette limite a pour but de vous aider à garantir une utilisation équitable entre vos utilisateurs.

Les quotas sont calculés par minute à l'aide d'une fenêtre glissante. Par conséquent, une utilisation intensive du trafic dépassant votre quota par minute pendant une minute entraînera une limitation du débit au cours de la fenêtre suivante, afin de vous assurer que votre utilisation respecte, en moyenne, les quotas.

Si l'un des quotas est dépassé, votre débit est limité et vous recevez un code d'état 403 usageLimits ou un code d'état 429 usageLimits pour vos requêtes. Dans ce cas, voici ce que vous pouvez faire:

  1. Veillez à respecter toutes les bonnes pratiques : utilisez un intervalle exponentiel entre les tentatives, aléatoire les modèles de trafic et utilisez les notifications push.
  2. Si votre projet se développe et que vous avez plus d'utilisateurs, vous pouvez demander une augmentation du quota par projet.
  3. Si vous atteignez 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 peut commencer à atteindre d'autres types de limites, telles que des limites générales d'utilisation de l'agenda ou des 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 :

  1. Si vous ne possédez pas encore de compte de facturation pour votre projet, créez-en un.
  2. 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.
  3. 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 la fréquence de vos requêtes, nous renvoyons une réponse 403 "usageLimits" ou 429 (consultez la documentation complète sur les erreurs). Il ne s'agit pas d'une erreur fatale. Nous vous conseillons de relancer 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, il est préférable d'utiliser un intervalle exponentiel entre les tentatives tronqué. La documentation Cloud Storage explique bien comment cela fonctionne et décrit l'algorithme préféré. Si vous utilisez une bibliothèque cliente Google, cette opération s'effectue normalement à votre place. 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 tendances du trafic

Les clients Agenda sont sujets à des pics de trafic causés par le fait que plusieurs clients effectuent des opérations en même temps. Par exemple, il arrive souvent qu'un client Agenda effectue une synchronisation complète à minuit. Cela entraînerait presque certainement le dépassement de votre quota par minute, ainsi qu'une limitation du débit et des intervalles entre les tentatives.

Pour éviter cela, veillez à répartir le trafic sur toute 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 d'environ 25%. Le trafic sera alors réparti plus équitablement, ce qui offrira une bien meilleure expérience utilisateur.

Utiliser les notifications push

Un cas d'utilisation courant consiste à effectuer une action chaque fois que quelque chose change dans l'agenda de l'utilisateur. Un anti-modèle consiste ici à sonder à plusieurs reprises tous les calendriers qui vous intéressent. Cette opération épuise tout votre quota très rapidement. Par exemple, si votre application compte 5 000 utilisateurs et interroge l'agenda de chaque utilisateur une fois par minute, un quota par minute minimum de 5 000 utilisateurs est nécessaire, avant même que tout travail ne soit effectué.

Les applications côté serveur peuvent s'inscrire aux notifications push, ce qui nous permet de vous avertir lorsqu'il se produit quelque chose qui vous intéresse. La configuration demande plus de travail, mais permet une utilisation beaucoup plus efficace de votre quota et offre une meilleure expérience utilisateur. Veillez à spécifier le eventType pour lequel vous souhaitez recevoir une notification. Pour en savoir plus, consultez la section Notifications push.

Comptabilisation 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 selon les quotas "par minute, par projet et par utilisateur", et non selon l'utilisateur dont vous empruntez l'identité. Cela signifie que le compte de service risque 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 ce service sera facturé. Elle n'est utilisée que pour les calculs de quotas. Pour en savoir plus, consultez la section Limiter le nombre de requêtes par utilisateur dans la documentation Cloud.

Tester la gestion de la limite 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 de 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 distinct réservé aux tests 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.

Tarification

Vous pouvez utiliser l'API Google Calendar 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é.