La API de Calendario de Google tiene cuotas para garantizar que todos los usuarios la utilicen de manera justa. Hay 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 generales de uso del Calendario: Evita los límites de uso del Calendario.
- Límites operativos: Es posible que se apliquen límites de frecuencia en cualquier momento. Por ejemplo, si intentas escribir en un solo calendario en rápida sucesión.
Tipos de cuotas de uso de la API del Calendario
Se aplican dos tipos de cuotas:
- Por minuto y por proyecto: Es la cantidad de solicitudes que realiza tu proyecto de Google Cloud.
- Por minuto por proyecto por usuario: Es la cantidad de solicitudes que realiza un usuario en particular en tu proyecto de Cloud. El objetivo de este límite es ayudarte a garantizar una distribución equitativa del uso entre tus usuarios.
Las cuotas se calculan por minuto con una ventana deslizante, por lo que un aumento repentino del tráfico que supere tu cuota por minuto durante un minuto generará una limitación de frecuencia durante la siguiente ventana para garantizar que, en promedio, tu uso se mantenga dentro de las cuotas.
Si se excede cualquiera de las cuotas, se aplicará un límite de 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:
- Asegúrate de seguir todas las prácticas recomendadas: usa la retirada exponencial, aleatoriza los patrones de tráfico, usa notificaciones push.
- Si tu proyecto está creciendo y tienes más usuarios, puedes solicitar un aumento en la cuota por proyecto.
- 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 en la cuota por usuario, en general, no se recomienda aumentarla por encima del valor predeterminado, ya que tu aplicación podría comenzar a alcanzar otros tipos de límites, por ejemplo, los límites generales de uso del calendario o los límites operativos.
Solicitud de aumento de cuota
Para consultar o cambiar los límites de uso de tu proyecto, o bien solicitar un aumento de la cuota, haz lo siguiente:
- Si no tienes una cuenta de facturación para tu proyecto, crea una.
- Visita la página de API habilitadas de la biblioteca de API en la Consola de APIs y selecciona una API de la lista.
- 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.
Usa la retirada exponencial
Cuando queramos que disminuyas la frecuencia de tus solicitudes, mostraremos una respuesta "usageLimits" 403 o una respuesta 429 (consulta la documentación completa sobre errores). Este no es un error fatal, y esperamos que vuelvas a intentarlo después de un breve intervalo. Si las solicitudes siguen llegando demasiado rápido, volveremos a preguntarte, y así sucesivamente. Para que esto funcione correctamente, es importante que las demoras entre las solicitudes aumenten con el tiempo.
En general, debes usar la retirada exponencial truncada. La documentación de Cloud Storage incluye una buena explicación de cómo funciona y el algoritmo preferido. Si utilizas una biblioteca cliente de Google, esto se controlará automáticamente. Consulta la documentación de la biblioteca. Por lo general, debes usar la implementación de la biblioteca en lugar de escribir la tuya propia.
Aleatoriza los patrones de tráfico
Los clientes de calendario son propensos a patrones de tráfico irregulares causados por varios clientes que realizan operaciones al mismo tiempo. Por ejemplo, una práctica incorrecta común para un cliente de Calendar es realizar una sincronización completa a la medianoche. Esto casi con certeza haría que excedas tu cuota por minuto y generaría limitaciones de frecuencia y reintentos.
Para evitar esto, asegúrate de que tu tráfico se distribuya a lo largo del día siempre que sea posible. Si tu cliente necesita realizar una sincronización diaria, pídele que determine una hora aleatoria (diferente para cada cliente). Si necesitas realizar una operación de forma periódica, varía el intervalo en un +/- 25%. Esto distribuirá el tráfico de manera más uniforme y proporcionará una mejor experiencia del usuario.
Cómo usar las notificaciones push
Un caso de uso común es querer realizar una acción cada vez que cambia algo en el calendario del usuario. Un antipatrón aquí es sondear repetidamente cada calendario de interés. Esto agotará muy rápidamente toda tu cuota. Por ejemplo, si tu aplicación tiene 5,000 usuarios y sondea el calendario de cada usuario una vez por minuto, esto requerirá una cuota por minuto de al menos 5,000 incluso antes de que se realice cualquier trabajo.
Las aplicaciones del servidor pueden registrarse para recibir notificaciones push, lo que nos permite notificarte cuando sucede algo de interés. Estas requieren más trabajo de configuración, pero permiten un uso mucho más eficiente de tu cuota y brindan una mejor experiencia del usuario. Asegúrate de especificar el eventType para 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 con la delegación de todo el dominio, de forma predeterminada, la cuenta de servicio se cobra en relación con las cuotas "por minuto por proyecto por usuario", y no el usuario al que suplantas. Esto significa que es probable que la cuenta de servicio se quede sin cuota y se limite su velocidad, aunque opere en los calendarios de varios usuarios. Para evitar esto, usa el parámetro de URL quotaUser (o el encabezado HTTP x-goog-quota-user) para indicar qué usuario se cobrará. Solo se usa para los cálculos de cuotas. Consulta Cómo limitar las solicitudes por usuario en la documentación de Cloud para obtener más información.
Cómo probar el control de límites de cuota
Para garantizar que tu aplicación pueda controlar correctamente el alcance de 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 este caso en un entorno real.
Para que esta prueba no interfiera en el uso real de tu aplicación, te recomendamos que registres un proyecto independiente solo para pruebas en la Consola de APIs de Google y que lo configures de manera similar a tu proyecto de producción. Luego, puedes 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. Si superas los límites de solicitudes de cuota, no se aplicarán cargos adicionales ni se facturará tu cuenta.