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 ha delle quote per garantire che venga utilizzata in modo equo da tutti gli utenti. Quando utilizzi l'API Calendar, devi tenere in considerazione tre limitazioni importanti:

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 che presenta limitazioni per proteggere il rendimento complessivo del sistema Google Workspace. Per ulteriori informazioni, consulta 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:è il numero di richieste che il tuo progetto 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 rapido picco di traffico 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 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 giornaliero 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 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 descrive in dettaglio il limite:

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

Per ulteriori informazioni, consulta Modello standardizzato di Google Workspace per strumenti degli agenti e API.

Risolvere gli errori di quota basati sul tempo

Per tutti gli errori basati sul tempo (massimo N richieste ogni X minuti), ti consigliamo di fare in modo che il 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 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.

Esempio di algoritmo

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 la richiesta.
Se la richiesta non va a buon fine, attendi 2 + random_number_milliseconds e riprova la richiesta.
Se la richiesta non va a buon fine, attendi 4 + random_number_milliseconds e riprova la richiesta.
E così via, fino a un tempo maximum_backoff.
Continua ad attendere e a riprovare fino a un numero massimo di tentativi, ma non aumentare il periodo di attesa tra i 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 minore o uguale a 1000. In questo modo si evitano i casi in cui molti client vengono sincronizzati da una determinata situazione e riprovano tutti contemporaneamente, inviando richieste in onde sincronizzate. Il valore di random_number_milliseconds viene ricalcolato dopo ogni richiesta di ripetizione.
maximum_backoff è 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 l'addebito sul tuo account di fatturazione Google Cloud nel corso del 2026. Per ulteriori informazioni, 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 di un account di servizio sono considerate come se utilizzassero un singolo account. La richiesta di una quota aggiustata 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 due quote viene superata, la frequenza viene limitata e ricevi un codice di 403 usageLimits stato o un codice di 429 usageLimits stato in risposta alle tue query.

In questo caso, puoi provare a:

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 account di servizio, alloca il carico agli utenti o dividilo tra più account di servizio.
- Sebbene tu possa richiedere un aumento della quota per utente, in genere non è consigliabile aumentarla oltre il valore predefinito, in quanto l'applicazione potrebbe iniziare a raggiungere altri tipi di limiti, ad esempio i limiti di utilizzo generali di Calendar o i limiti operativi.
Verifica i limiti di quota registrando un progetto separato solo di test con una configurazione simile a quella del progetto di produzione. Per ulteriori informazioni, consulta Testare la gestione dei limiti di quota.

Randomizzare i pattern di traffico

I client di Calendar sono soggetti a pattern di traffico con picchi causati da più client che eseguono operazioni contemporaneamente. Ad esempio, una pratica errata comune per un client di Calendar è eseguire una sincronizzazione completa a mezzanotte. Questo porterebbe quasi certamente al superamento della quota al minuto e alla limitazione di frequenza e al backoff.

Per evitare questo problema, assicurati che il traffico sia distribuito durante la giornata, ove possibile. Se il client deve eseguire una sincronizzazione giornaliera, chiedigli di determinare un orario casuale (diverso per ogni client). Se devi eseguire un'operazione regolarmente, 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 è 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 ed esegue il polling del calendario di ogni utente una volta al minuto, è necessaria una quota al minuto di almeno 5000, anche prima di eseguire qualsiasi operazione.

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

Allocazione corretta con gli account di servizio

Se la tua applicazione esegue richieste utilizzando la delega a livello di dominio, per impostazione predefinita l'account di servizio viene addebitato in base alle quote "al minuto per utente per progetto" e non all'utente di cui stai eseguendo lo spoofing. Ciò significa che l'account di servizio probabilmente esaurirà la quota e la frequenza verrà limitata, anche se potrebbe operare sui calendari di più utenti.

Per evitare questo problema, puoi utilizzare il parametro URL quotaUser (o l'intestazione HTTP x-goog-quota-user) per indicare l'utente a cui viene addebitato l'importo. Questo parametro viene utilizzato solo per i calcoli delle quote. Per ulteriori informazioni, consulta Limitare le richieste per utente.

Testare 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 nuovi tentativi con backoff esponenziale) e per ridurre al minimo eventuali interruzioni per gli 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 di 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 dell'applicazione.

Quote del server MCP di Calendar

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

Quote MCP di Calendar