Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Limiti di utilizzo

L'API Google Calendar prevede delle quote per garantire che venga utilizzata in modo equo da tutti gli utenti. Esistono tre limitazioni importanti da considerare quando utilizzi l'API Calendar:

Quote di utilizzo dell'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 con limitazioni per proteggere le prestazioni complessive del sistema Google Workspace. Per saperne di più, consulta Evita 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: questo è il numero di richieste che il tuo progetto Google Cloud può effettuare in un minuto.
Al minuto per utente per progetto: questo è il numero di richieste che un singolo utente 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 temporale mobile. Un picco di traffico rapido che supera la quota al minuto durante un minuto comporterà una limitazione di frequenza durante la finestra successiva per garantire che, in media, l'utilizzo rimanga entro le quote.

La tabella seguente descrive 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 per giorno per progetto definisce il numero massimo di richieste che il tuo progetto Google Cloud può utilizzare in un periodo di 24 ore prima che vengano applicati addebiti.

L'utilizzo al di sotto di questa soglia non comporta costi aggiuntivi e non viene addebitato sul tuo account Google Cloud. I dettagli completi sulla fatturazione verranno condivisi più avanti nel 2026 con un preavviso di almeno 90 giorni prima dell'entrata in vigore di eventuali modifiche.

Non puoi richiedere un aumento di questo limite di soglia giornaliero.

La tabella seguente descrive il limite:

Tipo di limite di soglia	Limite
Al giorno per progetto	1.000.000 di richieste

Per saperne di più, consulta Modello standardizzato di Google Workspace per strumenti e API degli agenti.

Risolvi gli errori di quota basati sul tempo

Per tutti gli errori basati sul tempo (massimo di N richieste per X minuti), ti consigliamo di fare in modo che il tuo codice rilevi l'eccezione e utilizzi un backoff esponenziale troncato per assicurarti che i tuoi 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 che aumentano in modo esponenziale tra le richieste, fino a un tempo di backoff massimo. Se le richieste continuano a non andare 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 riprova le richieste in modo esponenziale, aumentando il tempo di attesa tra i nuovi 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_milliseconds e riprova a inviare la richiesta.
Se la richiesta non riesce, attendi 2 + random_number_milliseconds e riprova a inviare la richiesta.
Se la richiesta non riesce, attendi 4 + random_number_milliseconds e riprova a inviare la richiesta.
E via così fino all'maximum_backoffintervallo di backoff massimo.
Continua ad attendere e riprovare fino al numero massimo di nuovi tentativi, ma non aumentare il periodo di attesa tra i nuovi tentativi.

dove:

Il tempo di attesa è min(((2^n)+random_number_milliseconds), maximum_backoff), con n incrementato di 1 per ogni iterazione (richiesta).
random_number_milliseconds è un numero casuale di millisecondi inferiore o uguale a 1000. In questo modo si evitano i casi in cui molti client vengono sincronizzati da una determinata situazione e tutti riprovano contemporaneamente, inviando richieste in ondate sincronizzate. Il valore di random_number_milliseconds viene ricalcolato dopo ogni richiesta di nuovo tentativo.
maximum_backoff è in genere di 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 nuovi tentativi e il numero di nuovi tentativi dipendono dal caso d'uso e dalle condizioni della rete.

Prezzi

L'utilizzo standard dell'API Google Calendar è disponibile senza costi aggiuntivi. Il superamento dei limiti di richieste della quota comporterà addebiti sul tuo account di fatturazione Google Cloud nel corso del 2026. Per saperne di più, consulta Modello standardizzato di Google Workspace per strumenti e API degli agenti.

Richiedi un aumento della quota

A seconda dell'utilizzo delle risorse del progetto, potresti voler richiedere un aggiustamento della quota. Le chiamate API effettuate da un service account vengono considerate come se utilizzassero un singolo account. La richiesta di aggiustamento di una quota non ne garantisce l'approvazione. Le richieste di aggiustamento della quota che aumenterebbero in modo significativo il valore della quota possono richiedere più tempo per essere approvate.

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:

Risoluzione dei problemi

Se una delle quote viene superata, la frequenza viene limitata e ricevi un codice di stato 403 usageLimits o 429 usageLimits in risposta alle tue query.

In questo caso, puoi provare quanto segue:

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 procedere nel seguente modo:
- Se utilizzi un service account, distribuisci il carico tra gli utenti o suddividilo tra più service account.
- Sebbene sia possibile richiedere un aumento della quota per utente, in genere non è consigliabile aumentarla oltre il valore predefinito, poiché l'applicazione potrebbe iniziare a raggiungere altri tipi di limiti, ad esempio i limiti di utilizzo generali del calendario o i limiti operativi.
Testa i limiti di quota registrando un progetto separato solo per i test con una configurazione simile a quella del progetto di produzione. Per saperne di più, consulta Testa la gestione dei limiti di quota.

Randomizza i pattern di traffico

I client di Calendar sono soggetti a picchi di traffico causati da più client che eseguono operazioni contemporaneamente. Ad esempio, una cattiva pratica comune per un client di Calendar è eseguire una sincronizzazione completa a mezzanotte. Questo comporterebbe quasi certamente il superamento della quota al minuto e l'applicazione di limitazioni di frequenza e backoff.

Per evitare che ciò accada, assicurati che il traffico sia distribuito nell'arco della giornata, se possibile. Se il client deve eseguire una sincronizzazione giornaliera, chiedigli di determinare un'ora casuale (diversa per ogni client). Se devi eseguire un'operazione su base regolare, varia l'intervallo del +/- 25%. In questo modo, il traffico verrà distribuito in modo più uniforme e l'esperienza utente sarà molto migliore.

Utilizza le notifiche push

Un caso d'uso comune è l'esecuzione di un'azione ogni volta che cambia qualcosa nel calendario dell'utente. Un anti-pattern in questo caso è eseguire il polling ripetuto di ogni calendario di interesse. In questo modo, la tua quota verrà esaurita molto rapidamente. Ad esempio, se la tua applicazione ha 5000 utenti ed esegue il polling del calendario di ogni utente una volta al minuto, è necessaria una quota al minuto di almeno 5000, anche prima che venga eseguito qualsiasi lavoro.

Le applicazioni lato server possono registrarsi per le notifiche push, il che ci consente di inviarti una notifica quando si verifica un evento di interesse. Queste richiedono più lavoro per la configurazione, ma consentono un utilizzo molto più efficiente della quota e offrono un'esperienza utente migliore. Assicurati di specificare la eventType per cui vuoi ricevere le notifiche. Per saperne di più, consulta Notifiche push.

Allocazione corretta con i service account

Se la tua applicazione esegue richieste utilizzando la delega a livello di dominio, per impostazione predefinita il service account viene addebitato in base alle quote "per minuto per utente per progetto" e non all'utente di cui stai assumendo l'identità. Ciò significa che il service account probabilmente esaurirà la quota e sarà soggetto a limitazione di 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 specificare una stringa arbitraria (fino a 40 caratteri) che identifica in modo univoco ogni singolo utente. L'API Calendar utilizza questo valore solo per i calcoli delle quote.

Per utilizzare quotaUser per applicare la limitazione di frequenza per utente a utenti distinti, le tue richieste devono soddisfare i seguenti requisiti:

Includi una chiave API con limitazioni per l'IP: passa una chiave API nel parametro di query key e configura la chiave con limitazioni per l'indirizzo IP specificando gli indirizzi IP pubblici dei tuoi server di backend. Se ometti la chiave API o non configuri le limitazioni degli indirizzi IP, l'API Calendar ignora quotaUser e addebita la quota all'account autenticato (ad esempio l'account di servizio).
Ometti l'intestazione X-Goog-User-Project: non inviare un'intestazione HTTP X-Goog-User-Project per le richieste che utilizzano quotaUser. Se fornisci un progetto utente, la chiave API per l'attribuzione della quota viene sostituita, quindi l'API Calendar ignora quotaUser.

Per saperne di più, consulta Limitazione delle richieste per utente.

Testa la gestione dei limiti 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 potenziali disturbi per i tuoi utenti, ti consigliamo vivamente di testare lo scenario in un ambiente reale.

Per eseguire i test senza interferire con l'utilizzo reale dell'applicazione, ti consigliamo di registrare un progetto separato solo per i test nella console Google Cloud e poi di configurare la schermata per il 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.

Quote del server MCP di Calendar

Il server MCP di Calendar utilizza una metrica di allocazione dei costi delle query. Le seguenti tabelle mostrano in dettaglio il costo delle query per ogni metodo del server MCP di Calendar per sezione:

Quote MCP di Calendar