L'API Google Calendar ha quote per garantire che venga utilizzata in modo equo da tutti gli utenti. Quando utilizzi l'API Calendar, devi tenere presente tre importanti limitazioni:
Quote di utilizzo delle API: applicate per progetto e per utente. Per ulteriori informazioni, consulta Tipi di quote di utilizzo dell'API Calendar.
Limiti di utilizzo generali di Google Calendar: l'API Google Calendar è un servizio condiviso che presenta limitazioni per proteggere le prestazioni complessive del sistema Google Workspace. Per saperne di più, consulta la pagina Evitare i limiti di utilizzo di Calendar.
Limiti operativi: questi limiti potrebbero essere limitati in qualsiasi momento. Ad esempio, se tenti di scrivere in un singolo calendario in rapida successione.
Quote dell'API Calendar
Vengono applicati due tipi di quote:
Al minuto per progetto cloud:è il numero di richieste che il tuo progetto cloud Google Cloud può effettuare in un minuto.
Al minuto per utente per progetto:il numero di richieste che un utente specifico può effettuare nel tuo progetto Cloud. Questo limite ha lo scopo di aiutarti a garantire una distribuzione equa dell'utilizzo tra i tuoi utenti.
Le quote vengono calcolate al minuto utilizzando una finestra scorrevole. Un picco rapido di traffico che supera la quota al minuto durante un minuto comporterà la limitazione della frequenza durante la finestra successiva per garantire che, in media, l'utilizzo rimanga entro le quote.
La tabella seguente descrive in dettaglio questi limiti:
| Tipo di limite di utilizzo | Limite |
|---|---|
| Al minuto per progetto | 10.000 richieste |
| Al minuto per utente per progetto | 600 richieste |
Soglia di fatturazione giornaliera
Questo limite al giorno per progetto definisce il numero massimo di richieste che il tuo progetto Google Cloud può utilizzare in un periodo di 24 ore prima dell'applicazione dei costi.
L'utilizzo al di sotto di questa soglia non comporta costi aggiuntivi e il tuo account Google Cloud non viene fatturato. I dettagli di fatturazione completi verranno condivisi nel corso del 2026 con un preavviso di almeno 90 giorni prima che le modifiche diventino effettive.
Non puoi richiedere un aumento di questo limite di soglia giornaliero.
La tabella seguente riporta i dettagli del limite:
| Tipo di limite di soglia | Limite |
|---|---|
| Al giorno per progetto | 1.000.000 di richieste |
Per saperne di più, vedi Modello standardizzato di Google Workspace per strumenti e API per agenti.
Risolvi gli errori di quota basati sul tempo
Per tutti gli errori basati sul tempo (massimo N richieste ogni X minuti), consigliamo che il codice rilevi l'eccezione e utilizzi un backoff esponenziale troncato per assicurarsi che i dispositivi non generino un carico eccessivo.
Il backoff esponenziale è una strategia standard di gestione degli errori per le applicazioni di rete. Un algoritmo di backoff esponenziale riprova le richieste utilizzando tempi di attesa tra le richieste che aumentano in modo esponenziale, fino a un tempo di backoff massimo. Se le richieste non vanno ancora a buon fine, è importante che i ritardi tra le richieste aumentino nel tempo fino a quando la richiesta non va a buon fine.
Algoritmo di esempio
Un algoritmo di backoff esponenziale ritenta le richieste in modo esponenziale, aumentando il tempo di attesa tra i tentativi fino a un tempo di backoff massimo. Ad esempio:
- Invia una richiesta all'API Google Calendar.
- Se la richiesta non va a buon fine, attendi 1 +
random_number_millisecondse riprova a inviarla. - Se la richiesta non va a buon fine, attendi 2 +
random_number_millisecondse riprova a inviarla. - Se la richiesta non va a buon fine, attendi 4 +
random_number_millisecondse riprova a inviare la richiesta. - E così via, fino a un tempo di
maximum_backoff. - Continua ad attendere e riprovare fino al numero massimo di nuovi tentativi, ma non aumentare il periodo di attesa tra un tentativo e l'altro.
dove:
- Il tempo di attesa è
min(((2^n)+random_number_milliseconds), maximum_backoff), connincrementato di 1 per ogni iterazione (richiesta). random_number_millisecondsè un numero casuale di millisecondi inferiore o uguale a 1000. In questo modo si evitano casi in cui molti client vengono sincronizzati da una determinata situazione e tutti riprovano contemporaneamente, inviando richieste in onde sincronizzate. Il valore dirandom_number_millisecondsviene ricalcolato dopo ogni richiesta di riprova.maximum_backoffdura in genere 32 o 64 secondi. Il valore appropriato dipende dal caso d'uso.
Il client può continuare a riprovare dopo aver raggiunto il tempo maximum_backoff.
I nuovi tentativi dopo questo punto non devono continuare ad aumentare il tempo di backoff. Ad esempio, se un client utilizza un valore maximum_backoff di 64 secondi, dopo aver raggiunto questo valore, il client può riprovare ogni 64 secondi. A un certo punto, è necessario impedire ai client di effettuare ulteriori tentativi indefinitamente.
Il tempo di attesa tra i tentativi e il numero di tentativi dipendono dal caso d'uso e dalle condizioni di rete.
Prezzi
Tutto l'utilizzo standard dell'API Google Calendar è disponibile senza costi aggiuntivi. Il superamento dei limiti delle richieste di quota è previsto per comportare addebiti sul tuo account di fatturazione Google Cloud nel corso del 2026. Per saperne di più, vedi Modello standardizzato di Google Workspace per strumenti e API per agenti.
Richiedi un aumento della quota
A seconda dell'utilizzo delle risorse del progetto, potresti voler richiedere una modifica della quota. Le chiamate API effettuate da un service account sono considerate come se utilizzassero un singolo account. La richiesta di una quota modificata non ne garantisce l'approvazione. L'approvazione delle richieste di aggiustamento della quota che aumenterebbero in modo significativo il valore della quota può richiedere più tempo.
Non tutti i progetti hanno le stesse quote. Man mano che utilizzi sempre più Google Cloud nel tempo, i valori delle quote potrebbero dover aumentare. Se prevedi un aumento imminente e consistente dell'utilizzo, puoi richiedere un aggiustamento della quota in modo proattivo nella pagina Quote e limiti di sistema della console Google Cloud.
Per saperne di più, consulta le seguenti risorse:
- Informazioni sugli aggiustamenti delle quote
- Visualizzare l'utilizzo e i limiti delle quote
- Richiedere un limite di quota più alto
Risoluzione dei problemi
Se una delle due quote viene superata, la velocità viene limitata e ricevi un codice di stato 403
usageLimits o 429
usageLimits in risposta alle tue query.
Se ciò dovesse accadere, prova a svolgere i seguenti passaggi:
Assicurati di seguire tutte le best practice: utilizza il backoff esponenziale, randomizza i pattern di traffico e utilizza le notifiche push.
Se il tuo progetto è in crescita e hai più utenti, puoi richiedere un aumento della quota.
Se raggiungi i limiti di quota per utente, puoi:
Se utilizzi un service account, distribuisci il carico tra gli utenti o dividilo tra più service account.
Anche se puoi richiedere un aumento della quota per utente, in generale non è consigliabile aumentarla oltre il valore predefinito, in quanto la tua applicazione potrebbe iniziare a raggiungere altri tipi di limiti, ad esempio i limiti generali di utilizzo del calendario o i limiti operativi.
Verifica i limiti di quota registrando un progetto di solo test separato con una configurazione simile a quella del progetto di produzione. Per saperne di più, consulta Testare la gestione dei limiti di quota.
Randomizzare i pattern di traffico
I client di calendario sono soggetti a pattern di traffico irregolari causati da più client che eseguono operazioni contemporaneamente. Ad esempio, una pratica errata comune per un client Calendar è eseguire una sincronizzazione completa a mezzanotte. Ciò porterebbe quasi certamente al superamento della quota al minuto e comporterebbe la limitazione della frequenza e i backoff.
Per evitare questo problema, assicurati che il traffico sia distribuito durante la giornata, ove possibile. Se il tuo cliente deve eseguire una sincronizzazione giornaliera, chiedigli di determinare un'ora casuale (diversa per ogni cliente). Se devi eseguire un'operazione a intervalli regolari, varia l'intervallo di +/- 25%. In questo modo, il traffico verrà distribuito in modo più uniforme e l'esperienza utente sarà molto migliore.
Utilizzare le notifiche push
Un caso d'uso comune è eseguire un'azione ogni volta che qualcosa cambia nel calendario dell'utente. Un anti-pattern qui è quello di eseguire il polling ripetutamente di ogni calendario di interesse. In questo modo, la quota verrà esaurita molto rapidamente. Ad esempio, se la tua applicazione ha 5000 utenti e interroga il calendario di ogni utente una volta al minuto, ciò richiede una quota al minuto di almeno 5000, prima ancora di iniziare a lavorare.
Le applicazioni lato server possono registrarsi per le notifiche push, il che ci consente di
avvisarti quando si verifica qualcosa di interessante. Questi richiedono più lavoro per la configurazione, ma consentono un utilizzo molto più efficiente della quota e offrono un'esperienza utente migliore. Assicurati di specificare il eventType per cui vuoi
ricevere notifiche. Per ulteriori informazioni, vedi Notifiche
push.
Allocazione corretta con i service account
Se la tua applicazione esegue richieste utilizzando la delega a livello di dominio, per impostazione predefinita l'account di servizio viene addebitato in relazione alle quote "al minuto per utente per progetto", e non l'utente di cui stai eseguendo l'impersonificazione. Ciò significa che l'account di servizio probabilmente esaurirà la quota e verrà limitato in base alla frequenza, anche se potrebbe operare sui calendari di più utenti.
Per evitarlo, puoi utilizzare il parametro URL quotaUser (o l'intestazione HTTP x-goog-quota-user) per indicare a quale utente viene addebitato il costo. Viene utilizzato
solo per i calcoli della quota. Per saperne di più, consulta Limitare le richieste per utente.
Testa la gestione del limite di quota
Per assicurarti che la tua applicazione possa gestire correttamente il raggiungimento dei limiti di quota in pratica (ad esempio, tramite tentativi con backoff esponenziale) e per ridurre al minimo eventuali interruzioni per i tuoi utenti, ti consigliamo vivamente di testare lo scenario in un ambiente reale.
Per eseguire test senza interferenze con l'utilizzo reale dell'applicazione, ti consigliamo di registrare un progetto separato solo per i test nella console Google Cloud e poi configurare la schermata di consenso OAuth in modo simile al progetto di produzione. Puoi quindi impostare limiti di quota artificialmente bassi per questo progetto e osservare il comportamento della tua applicazione.