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:
- Le quote di utilizzo delle API vengono applicate per progetto e per utente. Per saperne di più, consulta la sezione successiva.
- Limiti di utilizzo generali di Calendar: evita i limiti di utilizzo di Calendar.
- Limiti operativi:potresti essere soggetto a limiti di frequenza in qualsiasi momento. Ad esempio, se tenti di scrivere in un unico calendario in rapida successione.
Tipi di quote di utilizzo dell'API Calendar
Vengono applicati due tipi di quote:
- Al minuto per progetto:il numero di richieste effettuate dal tuo progetto Google Cloud.
- Al minuto per progetto per utente:il numero di richieste effettuate da un utente specifico 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, quindi 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.
Se una delle due quote viene superata, la frequenza viene limitata e ricevi un
codice di stato 403 usageLimits
o un
codice di stato 429 usageLimits
per le tue query. Se ciò avviene, ecco cosa puoi fare:
- Assicurati di seguire tutte le best practice: utilizza il backoff esponenziale, randomizza i pattern di traffico, utilizza le notifiche push.
- Se il tuo progetto è in crescita e hai più utenti, puoi richiedere un aumento della quota per progetto.
- Se viene raggiunto il limite di quota per utente, puoi procedere nel seguente modo:
- 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 di utilizzo generali di Calendar o i limiti operativi.
Richiesta di aumento della quota
Per visualizzare o modificare i limiti di utilizzo relativi al progetto o per richiedere un incremento della quota, procedi come segue:
- Se non hai ancora un account di fatturazione per il progetto, creane uno.
- Visita la pagina API abilitate della libreria di API nella console API e seleziona un'API dall'elenco.
- Per visualizzare e modificare le impostazioni relative alla quota, seleziona Quote. Per visualizzare le statistiche sull'utilizzo, seleziona Utilizzo.
Utilizza il backoff esponenziale
Quando vogliamo che tu rallenti la frequenza delle richieste, restituiremo una risposta "usageLimits" 403 o una risposta 429 (consulta la documentazione completa sugli errori). Questo non è un errore irreversibile e prevediamo che tu riprovi a inviare la richiesta dopo un breve intervallo. Se le richieste continuano ad arrivare troppo rapidamente, ti chiederemo di nuovo di rallentare e così via. Affinché funzioni correttamente, è importante che i ritardi tra le richieste aumentino nel tempo.
In genere, devi utilizzare il backoff esponenziale troncato. La documentazione di Cloud Storage fornisce una buona spiegazione di come funziona e dell'algoritmo preferito. Se utilizzi una libreria client Google, questa operazione viene gestita automaticamente. Consulta la documentazione della libreria. In genere, dovresti utilizzare l'implementazione della libreria anziché scriverne una tua.
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, se possibile. Se il tuo cliente deve eseguire una sincronizzazione giornaliera, chiedigli di determinare un orario casuale (diverso per ogni cliente). 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 è quello di voler 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 ciascun utente una volta al minuto, sarà necessaria una quota al minuto di almeno 5000 anche prima di qualsiasi lavoro.
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 una migliore esperienza utente. Assicurati di specificare il eventType per
cui vuoi ricevere notifiche. Per ulteriori informazioni, consulta la sezione
Notifiche push.
Contabilità 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
progetto per utente", e non l'utente di cui stai eseguendo l'impersonificazione. Ciò significa
che l'account di servizio probabilmente esaurirà la quota e verrà limitato,
anche se potrebbe operare sui calendari di più utenti. Puoi evitarlo
utilizzando il parametro URL quotaUser (o l'intestazione
HTTP x-goog-quota-user) per indicare a quale utente verrà addebitato l'addebito. Questo valore viene utilizzato solo per i calcoli
della quota. Per saperne di più, consulta la sezione
Limitazione delle richieste per utente
nella documentazione di Cloud.
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, eseguendo nuovi tentativi con backoff esponenziale) e per ridurre al minimo eventuali potenziali disagi per gli utenti, ti consigliamo vivamente di testare questo scenario in un ambiente reale.
Affinché un test di questo tipo non interferisca con l'utilizzo reale dell'applicazione, ti consigliamo di registrare un progetto separato solo per i test nella console API di Google e di configurarlo in modo simile al progetto di produzione. Puoi quindi impostare quote artificialmente basse per questo progetto e osservare il comportamento della tua applicazione.
Prezzi
L'uso dell'API Google Calendar è disponibile senza costi aggiuntivi. Il superamento dei limiti delle richieste di quota non comporta costi aggiuntivi e il tuo account non viene fatturato.