A API Google Agenda tem cotas para garantir que ela seja usada de forma justa por todos os usuários. Há 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 mais informações.
- Limites gerais de uso do Google Agenda: evite limites de uso do Google Agenda.
- Limites operacionais:você pode ter um limite de taxa a qualquer momento. Por exemplo, se você tentar gravar em um único calendário em rápida sucessão.
Tipos de cotas de uso da API Calendar
Dois tipos de cotas são aplicados:
- Por minuto por projeto:é o número de solicitações feitas pelo seu projeto do Google Cloud.
- Por minuto por projeto por usuário:é o número de solicitações feitas por um usuário específico no seu projeto na nuvem. Esse limite tem como objetivo ajudar você a garantir uma distribuição justa do uso entre os usuários.
As cotas são calculadas por minuto usando uma janela deslizante. Portanto, um pico rápido de tráfego que exceda a 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á um limite de taxa e receberá um
403 usageLimits código de status
ou um
429 usageLimits código de status
para suas consultas. Se isso acontecer, faça o seguinte:
- Siga todas as práticas recomendadas: use a espera exponencial, randomize padrões de tráfego, use notificações push.
- Se o projeto estiver crescendo e você tiver mais usuários, poderá solicitar um aumento na cota por projeto.
- Se o limite de cota por usuário for atingido, faça o seguinte:
- Se você usar uma conta de serviço, aloque a carga para os usuários ou divida-a entre várias contas de serviço.
- Embora seja possível solicitar um aumento na cota por usuário, em geral, não é recomendável aumentá-la acima do valor padrão, porque o aplicativo pode começar a atingir outros tipos de limites, por exemplo, limites gerais de uso do Google Agenda, ou limites operacionais.
Solicitar aumento de cota
Para ver ou alterar limites de uso do projeto ou para solicitar um aumento da cota, faça o seguinte:
- Se você ainda não tem uma conta de faturamento para seu projeto, crie uma.
- Acesse a página "APIs ativadas" da biblioteca de APIs no Console de APIs e selecione uma API da lista.
- Para visualizar e alterar configurações relacionadas a cotas, selecione Cotas. Para ver as estatísticas de uso, selecione Uso.
Usar a espera exponencial
Quando quisermos que você diminua a taxa de solicitações, vamos retornar uma resposta "usageLimits" 403 ou uma resposta 429 (consulte a documentação completa de erros). Esse não é um erro fatal, e esperamos que você tente novamente a solicitação após um pequeno intervalo. Se as solicitações ainda estiverem chegando muito rapidamente, vamos pedir novamente e assim por diante. Para que isso funcione corretamente, é importante que os atrasos entre as solicitações aumentem com o tempo.
Em geral, você deve usar a espera exponencial truncada. A documentação do Cloud Storage tem uma boa explicação de como isso funciona e o algoritmo preferido. Se você estiver usando uma biblioteca de cliente do Google, isso será processado normalmente. Consulte a documentação da biblioteca. Normalmente, é melhor usar a implementação da biblioteca em vez de escrever a sua.
Randomizar padrões de tráfego
Os clientes do Google Agenda são propensos a padrões de tráfego com picos causados por vários clientes que realizam operações ao mesmo tempo. Por exemplo, uma prática ruim comum para um cliente do Google Agenda é realizar uma sincronização completa à meia-noite. Isso quase certamente levaria a exceder a cota por minuto e resultaria em limitação de taxa e espera.
Para evitar isso, distribua o tráfego ao longo do dia sempre que possível. Se o cliente precisar fazer uma sincronização diária, peça que ele determine um horário aleatório (diferente para cada cliente). Se você precisar realizar uma operação regularmente, varie o intervalo em +/- 25%. Isso vai distribuir o tráfego de maneira mais uniforme e proporcionar uma 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 no calendário do usuário. Um antipadrão aqui é consultar repetidamente todos os calendários de interesse. Isso vai usar rapidamente toda a sua cota. Por exemplo, se o aplicativo tiver 5.000 usuários e consultar o calendário 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 feito.
Os aplicativos do lado do servidor podem se registrar para receber notificações push, o que nos permite notificar você quando algo de interesse acontecer. Elas exigem mais trabalho para configurar, mas permitem um uso muito mais eficiente da sua cota e proporcionam uma melhor experiência do usuário. Especifique o eventType para o qual você quer ser notificado. 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 em relação às cotas "por minuto por
projeto por usuário", e não o usuário que você está representando. Isso significa que a conta de serviço provavelmente vai ficar sem cota e será limitada pela taxa, mesmo que esteja operando em calendários 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 cota. Consulte
Limitar solicitações por usuário
na documentação do Cloud para mais informações.
Testar o processamento de limites de cota
Para garantir que o aplicativo possa processar normalmente os limites de cota na prática (por exemplo, fazendo novas tentativas com espera exponencial) e para minimizar possíveis interrupções para os usuários, recomendamos testar este cenário em um ambiente real.
Para que esse teste não interfira no uso real do aplicativo, nós recomendamos registrar um projeto de teste separado no Console de APIs do Google e configurá-lo de maneira semelhante ao projeto de produção. Em seguida, defina cotas artificialmente baixas para esse projeto e observe o comportamento do aplicativo.
Preços
Todo o uso da API Google Agenda está disponível sem custo adicional. Exceder os limites de solicitação de cota não gera cobranças extras, e sua conta não é faturada.