L'API Google Calendar ha delle quote per garantire che venga utilizzata in modo equo da tutti gli utenti. Esistono tre limitazioni importanti da considerare quando si utilizza l'API Calendar:
- Le quote di utilizzo dell'API vengono applicate per progetto e per utente. Per ulteriori informazioni, consulta la sezione successiva.
- Limiti di utilizzo generali di Calendar: evita di superare i limiti di utilizzo di Calendar.
- Limiti operativi: la frequenza potrebbe essere limitata in qualsiasi momento. Ad esempio, se provi a 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:si tratta del numero di richieste effettuate da un determinato utente nel tuo progetto cloud. Lo scopo di questo limite è aiutarti a garantire una distribuzione equa dell'utilizzo tra gli utenti.
Le quote vengono calcolate al minuto utilizzando una finestra mobile, pertanto un picco improvviso di traffico che supera la quota al minuto durante un minuto comporterà un limite di velocità durante la finestra successiva per garantire che, in media, il tuo utilizzo rimanga entro le quote.
Se una delle 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. In questo caso, ecco cosa puoi fare:
- Assicurati di seguire tutte le best practice: utilizza il backoff esponenziale, genera pattern di traffico casuali, 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 account di servizio, alloca il carico agli utenti o suddividilo tra più account di servizio.
- Sebbene sia possibile 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 limiti generali di utilizzo del calendario o 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 rallenti la frequenza delle richieste, revocheremo una risposta 403 "usageLimits" o 429 (consulta la documentazione completa sugli errori). Non si tratta di un errore fatale e ti invitiamo a riprovare a inviare la richiesta dopo un breve intervallo. Se le richieste continuano ad arrivare troppo rapidamente, te lo chiederemo di nuovo e così via. Affinché funzioni correttamente, è importante che i ritardi tra le richieste aumentino nel tempo.
In genere, dovresti utilizzare il backoff esponenziale troncato. La documentazione di Cloud Storage fornisce una buona spiegazione del funzionamento e dell'algoritmo preferito. Se utilizzi una libreria client Google, in genere questa operazione viene eseguita automaticamente. Consulta la documentazione della libreria. In genere, dovresti utilizzare l'implementazione della libreria anziché scriverne una personalizzata.
Randomizza i pattern di traffico
I client di Calendar sono soggetti a pattern di traffico irregolari 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. Ciò comporterebbe quasi certamente il superamento della quota al minuto e l'applicazione di limiti di frequenza e backoff.
Per evitare che ciò accada, assicurati che il traffico sia distribuito nell'arco della giornata, ove possibile. Se il cliente deve eseguire una sincronizzazione giornaliera, invitalo a determinare un orario casuale (diverso per ogni cliente). Se devi eseguire un'operazione su base regolare, 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 è voler eseguire un'azione ogni volta che qualcosa cambia nel calendario dell'utente. Un anti-pattern in questo caso è eseguire ripetutamente il polling di ogni calendario di interesse. In questo modo, consumerai molto rapidamente tutta la quota. Ad esempio, se la tua applicazione ha 5000 utenti e esegue il polling del calendario di ogni utente una volta al minuto, sarà necessaria una quota al minuto di almeno 5000 anche prima di iniziare a lavorare.
Le applicazioni lato server possono registrarsi per le notifiche push, il che ci consente di informarti quando si verifica qualcosa di interessante. La loro configurazione richiede più lavoro, ma consentono di utilizzare la quota in modo molto più efficiente e di offrire una migliore esperienza utente. Assicurati di specificare i eventType per i quali vuoi ricevere una notifica. Per ulteriori informazioni, consulta la sezione 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 all'account di servizio vengono addebitate le quote "al minuto per progetto per utente" e non all'utente di cui stai assumendo l'identità. Ciò significa che l'account di servizio potrebbe esaurire la quota e avere una limitazione di frequenza, anche se potrebbe essere in esecuzione 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 verrà addebitato l'importo. Viene utilizzato solo per i calcoli
delle quote. Per ulteriori informazioni, consulta la sezione Limitare le richieste per utente nella documentazione di Cloud.
Testare la gestione del limite di quota
Per assicurarti che la tua applicazione possa gestire in modo corretto il raggiungimento dei limiti di quota in pratica (ad es. eseguendo ripetuti tentativi con backoff esponenziale) e per minimizzare eventuali potenziali 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, 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 artificiosamente 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 della quota non comporta costi aggiuntivi e non viene addebitato alcun importo sul tuo account.