Gerenciar cotas

A API Google Calendar tem cotas para garantir que seja usada de forma justa por todos os usuários. Existem três limitações importantes a serem consideradas ao usar a API Calendar:

  • As cotas de uso da API são aplicadas por projeto e por usuário. Consulte a próxima seção para saber mais.
  • Limites gerais de uso do Agenda: evite limites de uso do Agenda.
  • Limites operacionais: é possível que haja limitação de taxa a qualquer momento. Por exemplo, se você tentar gravar em uma única agenda em rápida sucessão.

Tipos de cotas de uso da API Calendar

Dois tipos de cotas são aplicados:

  • Por minuto e projeto: é o número de solicitações feitas pelo projeto do Google Cloud.
  • Por minuto, projeto e usuário:é o número de solicitações feitas por qualquer usuário específico no projeto do Cloud. O objetivo desse limite é ajudar você a garantir uma distribuição justa do uso entre seus usuários.

As cotas são calculadas por minuto usando uma janela deslizante. Portanto, um burst rápido de tráfego que exceda sua cota por minuto durante um minuto resultará em limitação de taxa durante a próxima janela para garantir que, em média, seu uso permaneça dentro das cotas.

Se uma das cotas for excedida, você terá uma limitação de taxa e receberá um código de status 403 usageLimits ou um código de status 429 usageLimits para suas consultas. Se isso acontecer, faça o seguinte:

  1. Siga todas as práticas recomendadas: usar espera exponencial, usar padrões de tráfego aleatórios e usar notificações push.
  2. Caso seu projeto esteja crescendo e você tenha mais usuários, solicite um aumento da cota por projeto.
  3. Se o limite de cota por usuário for atingido, você poderá fazer o seguinte:
    • Se você usar uma conta de serviço, aloque a carga para os usuários ou a divida entre várias contas de serviço.
    • É possível solicitar um aumento na cota por usuário, mas, em geral, não é recomendável aumentá-la acima do valor padrão, porque seu aplicativo pode começar a atingir outros tipos de limites, como limites gerais de uso do calendário ou limites operacionais.

Solicitação de aumento de cota

Para conferir ou mudar os limites de uso do projeto ou solicitar um aumento da cota, siga estas etapas:

  1. Se você ainda não tem uma conta de faturamento para o projeto, crie uma.
  2. Acesse a página "APIs ativadas" da biblioteca de APIs no Console de APIs e selecione uma API da lista.
  3. Para ver e mudar configurações relacionadas a cotas, selecione Cotas. Para ver as estatísticas de uso, selecione Uso.

Usar a espera exponencial

Quando quisermos diminuir a taxa de solicitações, retornaremos uma resposta 403 "usageLimits" ou 429. Consulte a documentação completa do erro. Esse não é um erro fatal, e esperamos que você tente novamente a solicitação após um curto intervalo. Se as solicitações ainda chegarem muito rápido, perguntaremos novamente e assim por diante. Para que isso funcione corretamente, é importante que os atrasos entre as solicitações aumentem com o tempo.

Geralmente, é recomendável usar a espera exponencial truncada. A documentação do Cloud Storage tem uma boa explicação de como isso funciona e do algoritmo preferencial. Se você estiver usando uma biblioteca de cliente do Google, isso normalmente será resolvido para você. Consulte a documentação da biblioteca. Normalmente, é recomendável usar a implementação da biblioteca em vez de criar sua própria implementação.

Randomizar padrões de tráfego

Os clientes do Google Agenda estão propensos a picos de padrões de tráfego causados por vários clientes realizando operações ao mesmo tempo. Por exemplo, uma prática ruim comum para um cliente da Agenda é fazer uma sincronização completa à meia-noite. Isso provavelmente excederia sua cota por minuto e resultaria em limitação de taxa e esperas.

Para evitar que isso aconteça, o tráfego precisa ser distribuído ao longo do dia, sempre que possível. Se o seu cliente precisar fazer uma sincronização diária, peça para ele determinar um horário aleatório (diferente para cada cliente). Se você precisar realizar uma operação regularmente, aumente o intervalo em +/- 25%. Assim, o tráfego é distribuído de maneira mais uniforme e a experiência do usuário é muito melhor.

Usar notificações push

Um caso de uso comum é querer realizar uma ação sempre que algo mudar na agenda do usuário. Um antipadrão aqui é pesquisar repetidamente todas as agendas de interesse. Isso vai consumir muito rapidamente toda sua cota. Por exemplo, se seu aplicativo tiver 5.000 usuários e pesquisar a agenda de cada usuário uma vez por minuto, isso exigirá uma cota por minuto de pelo menos 5.000, mesmo antes de qualquer trabalho ser concluído.

Os aplicativos do lado do servidor podem se registrar para notificações push, o que nos permite notificar você quando algo de interesse acontece. A configuração deles requer mais trabalho, mas permite um uso muito mais eficiente da cota e oferece uma melhor experiência do usuário. Especifique os eventType para que você quer receber notificações. Para mais informações, consulte Notificações push.

Contabilidade adequada com contas de serviço

Se o aplicativo estiver realizando solicitações usando a delegação em todo o domínio, por padrão, a conta de serviço será cobrada com relação às cotas "por minuto e por projeto e por usuário", e não pelo usuário sendo representado. Isso significa que a conta de serviço provavelmente vai ficar sem cota e terá limitação de taxa, mesmo que esteja operando nas agendas de vários usuários. Para evitar isso, use o parâmetro de URL quotaUser (ou o cabeçalho HTTP x-goog-quota-user) para indicar qual usuário será cobrado. Isso é usado apenas para cálculos de cotas. Para mais informações, consulte Como limitar solicitações por usuário na documentação do Cloud.

Testar o processamento do limite de cota

Para garantir que seu aplicativo consiga atingir os limites de cota na prática, por exemplo, fazendo novas tentativas com espera exponencial, e para minimizar possíveis perturbações para os usuários, recomendamos testar esse cenário em um ambiente real.

Para que esse teste não interfira no uso real do aplicativo, recomendamos registrar um projeto separado somente de teste no Console de APIs do Google e configurá-lo de maneira semelhante ao projeto de produção. Depois, defina cotas artificialmente baixas para esse projeto e observe o comportamento do seu aplicativo.

Preços

O uso da API Google Calendar está disponível sem custo adicional. Exceder os limites de solicitação de cota não gera cobranças adicionais e sua conta não será faturada.