L'API Google Calendar prevede delle quote per garantire un utilizzo equo da parte di tutti gli utenti. Esistono tre importanti limitazioni da considerare quando si utilizza l'API Calendar:
- Le quote di utilizzo delle API vengono applicate per progetto e per utente. Per saperne di più, consulta la prossima sezione.
- Limiti di utilizzo generali di Calendar: evita i limiti di utilizzo di Calendar.
- Limiti operativi: la frequenza potrebbe essere limitata in qualsiasi momento. Ad esempio se tenti di scrivere in un singolo 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 qualsiasi utente specifico nel tuo progetto Cloud. Questo limite ha lo scopo di aiutarti a garantire una distribuzione equa dell'utilizzo tra gli utenti.
Le quote vengono calcolate al minuto utilizzando una finestra scorrevole, quindi un rapido bursting di traffico che supera la quota al minuto durante un minuto comporterà una limitazione di frequenza nella finestra successiva per garantire che, in media, l'utilizzo rimanga entro le quote.
Se una delle due quote viene superata, hai una limitazione di frequenza e ricevi un codice di stato 403 usageLimits o un codice di stato 429 usageLimits per le tue query. In questo caso, ecco cosa puoi fare:
- Assicurati di seguire tutte le best practice: utilizzo di backoff esponenziale, casuale dei pattern di traffico, uso delle 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 come segue:
- Se utilizzi un account di servizio, alloca il carico agli utenti o dividilo tra più account di servizio.
- Sebbene sia possibile 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 del calendario 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 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.
Usa il backoff esponenziale
Se vogliamo che rallenti la frequenza delle richieste, restituiremo una risposta 403 "usageLimits" o una risposta 429 (consulta la documentazione completa sugli errori). Questo non è un errore irreversibile e prevediamo di ritentare la richiesta dopo un breve intervallo. Se le richieste arrivano ancora troppo rapidamente, chiederemo di nuovo e così via. Affinché questo comando 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 contiene una spiegazione valida del funzionamento di questo processo e dell'algoritmo preferito. Se utilizzi una libreria client di Google, in genere viene gestita automaticamente. Consulta la documentazione della libreria. Normalmente si usa l'implementazione della libreria invece di scriverne una personalizzata.
Randomizza i pattern di traffico
I client Calendar sono inclini a modelli di traffico picchi causati da più clienti che eseguono operazioni contemporaneamente. Ad esempio, una prassi negativa comune per un client Calendar è l'esecuzione di una sincronizzazione completa a mezzanotte. Ciò quasi certamente comporterebbe il superamento della quota al minuto e comporterebbe una limitazione di frequenza e backoff.
Per evitare che ciò accada, assicurati che il traffico sia distribuito nell'arco dell'intera giornata, ove possibile. Se il client deve effettuare una sincronizzazione giornaliera, chiedigli di determinare un orario casuale (diverso per ogni client). Se devi eseguire un'operazione regolarmente, varia l'intervallo +/- 25%. In questo modo, il traffico verrà distribuito in modo più uniforme e migliorerà l'esperienza utente.
Utilizzare le notifiche push
Un caso d'uso comune è eseguire un'azione ogni volta che nel calendario dell'utente cambia qualcosa. Un anti-pattern è quello di analizzare ripetutamente ogni calendario di interesse. In questo modo esaurisci molto rapidamente tutta la tua quota; ad esempio, se l'applicazione ha 5000 utenti ed esegue il polling del calendario di ogni utente una volta al minuto, sarà necessaria una quota al minuto di almeno 5000 utenti anche prima di eseguire qualsiasi operazione.
Le applicazioni lato server possono registrarsi per le notifiche push, il che ci permette di informarti quando succede qualcosa di tuo interesse. La loro configurazione richiede un lavoro maggiore, ma consentono un utilizzo notevolmente più efficiente della tua quota e offrono un'esperienza utente migliore. Assicurati di specificare il eventType
per cui vuoi ricevere una notifica. Per maggiori informazioni, consulta
Notifiche push.
Contabilità 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 progetto per utente" e non in base all'utente che stai impersonando. Ciò significa che l'account di servizio probabilmente esaurirà la quota e sarà soggetto a limitazioni di frequenza, anche se potrebbe funzionare su calendari di più utenti. Puoi evitare
questo problema utilizzando il parametro URL quotaUser (o l'intestazione HTTP x-goog-quota-user)
per indicare l'utente che verrà addebitato. Viene utilizzato solo per i calcoli delle quote. Per ulteriori informazioni, consulta Limitazione delle richieste per utente nella documentazione di Cloud.
Gestione dei limiti di quota di test
Per assicurarti che l'applicazione sia in grado di gestire agevolmente il raggiungimento dei limiti di quota in pratica (ad esempio eseguendo nuovi tentativi con backoff esponenziale) e per ridurre al minimo eventuali disturbi 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 di solo test nella console API di Google e di configurarlo in modo simile al tuo 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 di richiesta di quota non comporta costi aggiuntivi e non vengono addebitati costi sul tuo account.