Administrar las cuotas

La API de Google Calendar tiene cuotas para garantizar que todos los usuarios la usen de manera justa. Existen tres limitaciones importantes que debes tener en cuenta cuando usas la API de Calendar:

  • Las cuotas de uso de la API se aplican por proyecto y por usuario. Consulta la siguiente sección para obtener más información.
  • Límites de uso general de Calendario: Evita los límites de uso del Calendario.
  • Límites operativos: Es posible que se apliquen limitaciones de frecuencia en cualquier momento. Por ejemplo, si intentas escribir en un solo calendario seguidas con rapidez.

Tipos de cuotas de uso de la API de Calendario

Se aplican dos tipos de cuotas:

  • Por minuto, por proyecto: Es la cantidad de solicitudes que realiza tu proyecto de Google Cloud.
  • Por minuto, por proyecto y por usuario: Es la cantidad de solicitudes que realiza un usuario en particular en tu proyecto de Cloud. Este límite tiene como objetivo ayudarte a garantizar una distribución justa del uso entre tus usuarios.

Las cuotas se calculan por minuto mediante una ventana variable, por lo que un aumento rápido de tráfico que supere tu cuota por minuto durante un minuto dará como resultado un límite de frecuencia durante la siguiente ventana para garantizar que, en promedio, el uso se mantenga dentro de las cuotas.

Si se supera alguna de las cuotas, se te limitará la frecuencia y recibirás un código de estado 403 usageLimits o un código de estado 429 usageLimits en tus consultas. Si esto sucede, puedes hacer lo siguiente:

  1. Asegúrate de seguir todas las prácticas recomendadas: usa la retirada exponencial, aleatoriza los patrones de tráfico y usa las notificaciones push.
  2. Si tu proyecto está creciendo y tienes más usuarios, puedes solicitar un aumento en la cuota por proyecto.
  3. Si se alcanza el límite de cuota por usuario, puedes hacer lo siguiente:
    • Si usas una cuenta de servicio, asigna la carga a los usuarios o divídela entre varias cuentas de servicio.
    • Si bien puedes solicitar un aumento de la cuota por usuario, en general, no se recomienda aumentarla por encima del valor predeterminado, ya que tu aplicación puede comenzar a alcanzar otros tipos de límites, por ejemplo, los límites de uso general de calendario o los límites operativos.

Solicitud de aumento de cuota

Si deseas ver o cambiar los límites de uso de tu proyecto, o solicitar un aumento de la cuota, haz lo siguiente:

  1. Si no tienes una cuenta de facturación para tu proyecto, crea una.
  2. Visita la página de API habilitadas de la biblioteca de API en la Consola de APIs y selecciona una API de la lista.
  3. Si deseas consultar y cambiar la configuración de cuotas, selecciona la opción Cuotas. Para consultar las estadísticas de uso, selecciona la opción Uso.

Cómo usar la retirada exponencial

Cuando queremos que disminuyas tu frecuencia de solicitudes, te mostraremos una respuesta 403 “usageLimits” o una respuesta 429 (consulta la documentación de errores completa). Este no es un error fatal y esperamos que vuelvas a intentar la solicitud después de un intervalo corto. Si las solicitudes siguen llegando demasiado rápido, volveremos a preguntar, y así sucesivamente. Para que esto funcione correctamente, es importante que las demoras entre las solicitudes aumenten con el tiempo.

Por lo general, debes usar la retirada exponencial truncada. En la documentación de Cloud Storage, encontrarás una buena explicación de cómo funciona este proceso y cuál es el algoritmo preferido. Si usas una biblioteca cliente de Google, en general, esto se hará por ti. Consulta la documentación de tu biblioteca. Por lo general, deberías usar la implementación de la biblioteca en lugar de escribir la tuya.

Aleatorización de patrones de tráfico

Los clientes de Calendario son propensos a los patrones de aumento repentino de tráfico causados por varios clientes que realizan operaciones al mismo tiempo. Por ejemplo, una práctica no recomendada común para los clientes de Calendario es realizar una sincronización completa a la medianoche. Es casi seguro que esto provocaría que se exceda tu cuota por minuto, lo que provocaría un límite de frecuencia y retiradas.

Para evitar esto, asegúrate de distribuir el tráfico durante todo el día siempre que sea posible. Si tu cliente necesita realizar una sincronización diaria, pídele que determine un momento aleatorio (diferente para cada cliente). Si necesitas realizar una operación de forma regular, varía el intervalo en +/- 25%. Esto distribuirá el tráfico de manera más uniforme y brindará una mejor experiencia del usuario.

Usa notificaciones push

Un caso de uso común es realizar una acción cada vez que algo cambia en el calendario del usuario. Un antipatrón aquí es sondear repetidamente cada calendario de interés. Esto consumirá muy rápidamente toda la cuota; por ejemplo, si tu aplicación tiene 5,000 usuarios y consulta el calendario de cada uno una vez por minuto, esto requerirá una cuota por minuto de al menos 5,000, incluso antes de que se complete cualquier trabajo.

Las aplicaciones del servidor pueden registrarse para recibir notificaciones push, lo que nos permite notificarte cuando ocurre algo de interés. Estas requieren más trabajo de configuración, pero permiten un uso mucho más eficiente de tu cuota y proporcionan una mejor experiencia del usuario. Asegúrate de especificar el eventType sobre el que deseas recibir notificaciones. Para obtener más información, consulta Notificaciones push.

Contabilidad adecuada con cuentas de servicio

Si tu aplicación realiza solicitudes mediante la delegación de todo el dominio, de forma predeterminada, se cobra a la cuenta de servicio en relación con las cuotas "por minuto, por proyecto y por usuario", y no en relación con el usuario al que suplantas. Esto significa que la cuenta de servicio es probable que se quede sin cuota y tenga un límite de frecuencia, aunque pueda operar en los calendarios de varios usuarios. Para evitarlo, usa el parámetro de URL quotaUser (o el encabezado HTTP x-goog-quota-user) para indicar a qué usuario se le cobrará. Solo se usa para cálculos de cuotas. Consulta Limita las solicitudes por usuario en la documentación de Cloud para obtener más información.

Prueba el control del límite de cuota

Para asegurarte de que tu aplicación pueda manejar correctamente los límites de cuota en la práctica (p.ej., realizando reintentos con retirada exponencial) y minimizar cualquier posible interrupción para tus usuarios, te recomendamos que pruebes esta situación en un entorno real.

Para que esta prueba no interfiera en el uso real de tu aplicación, te recomendamos que registres un proyecto solo de prueba independiente en la Consola de APIs de Google y que lo configures de manera similar a tu proyecto de producción. Luego, podrás establecer cuotas artificialmente bajas para este proyecto y observar el comportamiento de tu aplicación.

Precios

Todo uso de la API del Calendario de Google está disponible sin costo adicional. Exceder los límites de solicitud de cuota no genera cargos adicionales y no se factura tu cuenta.