Gerenciar cotas

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 usuário. Consulte a próxima seção para mais informações.
  • Limites gerais de uso do Agenda: evite limites de uso do Agenda.
  • Limites operacionais:você pode ter uma limitação de taxa a qualquer momento. Por exemplo, se você tentar gravar em uma única agenda em sucessão rápida.

Tipos de cotas de uso da API Calendar

Dois tipos de cotas são aplicadas:

  • Por minuto por projeto:é o número de solicitações feitas pelo seu projeto do Google Cloud.
  • Por minuto, por projeto e por usuário:é o número de solicitações feitas por qualquer usuário específico no seu projeto do Cloud. O objetivo desse limite é 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, uma explosão rápida de tráfego que exceda sua cota por minuto durante um minuto vai 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ê vai receber um limite de taxa e 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: use a desistência exponencial, randomize os padrões de tráfego e use notificações push.
  2. Se o projeto estiver crescendo e você tiver mais usuários, solicite um aumento da cota por projeto.
  3. 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 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 operacionais.

Solicitação de aumento de cota

Para ver ou alterar limites de uso do projeto ou para solicitar um aumento da cota, faça o seguinte:

  1. Se você ainda não tem uma conta de faturamento para seu 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 visualizar e alterar configurações relacionadas a cotas, selecione Cotas. Para ver as estatísticas de uso, selecione Uso.

Usar a espera exponencial

Quando queremos que você diminua a taxa de solicitações, retornamos uma resposta 403 "usageLimits" ou 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 curto 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.

Geralmente, é necessário usar a espera exponencial truncada. A documentação do Cloud Storage explica bem como isso funciona e qual é o algoritmo preferido. Se você estiver usando uma biblioteca de cliente do Google, isso normalmente será processado para você. Consulte a documentação da biblioteca. Normalmente, use a implementação da biblioteca em vez de criar a sua própria.

Tornar os padrões de tráfego aleatórios

Os clientes de calendário são propensos a padrões de tráfego irregulares causados por vários clientes realizando operações ao mesmo tempo. Por exemplo, uma prática inadequada comum para um cliente do Google Agenda é realizar uma sincronização completa à meia-noite. Isso quase certamente vai levar ao excesso da cota por minuto e resultar em limitação de taxa e recuos.

Para evitar isso, distribua seu tráfego ao longo do dia sempre que possível. Se o 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, 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 é realizar uma ação sempre que algo muda no calendário do usuário. Um antipadrão aqui é consultar repetidamente cada calendário de interesse. Isso vai usar toda a sua cota muito rapidamente. Por exemplo, se o aplicativo tiver 5.000 usuários e consultar o calendário de cada usuário uma vez por minuto, será necessária 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 notificações push, o que nos permite notificar você quando algo de interesse acontece. Eles exigem mais trabalho para configuração, mas permitem um uso muito mais eficiente da sua cota e oferecem uma experiência do usuário melhor. Especifique o eventType para o qual 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 em relação às cotas "por minuto por projeto por usuário", e não ao usuário que você está personificando. Isso significa que a conta de serviço provavelmente ficará sem cota e será limitada, 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. Ele é usado apenas para cálculos de cota. Consulte Como limitar solicitações por usuário na documentação do Cloud para mais informações.

Testar o processamento do limite de cota

Para garantir que seu aplicativo possa lidar com limites de cota na prática (por exemplo, fazendo novas tentativas com retirada exponencial) e para minimizar possíveis problemas 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 apenas para testes no Console de APIs do Google e configurá-lo de maneira semelhante ao seu projeto de produção. Em seguida, defina cotas artificialmente baixas para esse projeto e observe o comportamento do aplicativo.

Preços

O uso da API Google Agenda não gera custos extras. Exceder os limites de solicitação de cota não gera cobranças extras, e sua conta não é faturada.