API Directory: limites e cotas

Limites e cotas protegem a infraestrutura do Google de um processo automatizado que usa a API Directory de forma inadequada. Solicitações excessivas de uma API podem resultar de um erro de digitação inofensivo ou de um sistema projetado de maneira ineficiente que faz chamadas de API desnecessárias. Seja qual for a causa, bloquear o tráfego de uma origem específica quando ele atinge um determinado nível é necessário para a integridade geral do sistema do Google Workspace. Garante que as ações de um desenvolvedor não afetem negativamente a comunidade em geral.

No caso improvável de falha da sua solicitação de API, a API retornará um código de status HTTP e o motivo do erro. Além disso, o corpo da resposta contém uma descrição detalhada do que causou o erro.

A lista a seguir mostra os possíveis códigos de erro, motivos, descrições correspondentes e ações recomendadas para erros causados ao atingir limites de cota.

Código Motivo Descrição Ação recomendada
403 userRateLimitExceeded Indica que o limite da taxa de usuário foi ultrapassado. O valor padrão definido no console do Google Cloud é de 2.400 consultas por minuto por usuário e por projeto do Google Cloud. Aumente os limites por usuário na página Cotas da API Admin SDK do projeto do Google Cloud ou diminua a taxa de envio das solicitações usando a espera exponencial.
403 quotaExceeded Indica que o limite de solicitações simultâneas para uma determinada operação foi atingido. Tente novamente usando a espera exponencial. Você precisa diminuir a taxa em que envia as solicitações.
429 rateLimitExceeded Indica que o limite de solicitações simultâneas para uma determinada operação foi atingido. Tente novamente usando a espera exponencial. Reduza a taxa em que você está enviando as solicitações. Esse limite é determinado por conta do Google Workspace, não por cliente de API ou usuário. Não é possível aumentar esse limite.

Como implementar espera exponencial

Backoff exponencial é o processo em que um cliente repete periodicamente uma solicitação com falha por um período cada vez maior. É uma estratégia de gerenciamento de erros padrão para aplicativos de rede. O uso de espera exponencial aumenta a eficiência do uso da largura de banda, reduz o número de solicitações necessárias para receber uma resposta bem-sucedida e maximiza a capacidade de solicitações em ambientes simultâneos.

Veja a seguir o fluxo de implementação de backoff exponencial simples.

  1. Fazer uma solicitação para a API
  2. Receber uma resposta de erro que tem um código de erro passível de repetição
  3. Esperar 1 s + random_number_milliseconds segundos
  4. Repetir a solicitação
  5. Receber uma resposta de erro que tem um código de erro passível de repetição
  6. Esperar 2s + random_number_milliseconds segundos
  7. Repetir a solicitação
  8. Receber uma resposta de erro que tem um código de erro passível de repetição
  9. Aguarde 4s + random_number_milliseconds segundos
  10. Repetir a solicitação
  11. Receber uma resposta de erro que tem um código de erro passível de repetição
  12. Esperar 8 s + random_number_milliseconds segundos
  13. Repetir a solicitação
  14. Receber uma resposta de erro que tem um código de erro passível de repetição
  15. Esperar 16s + random_number_milliseconds segundos
  16. Repetir a solicitação
  17. Se você continuar recebendo um erro, pare e registre-o.

No fluxo acima, random_number_milliseconds é um número aleatório de milissegundos menor ou igual a 1.000. Ele é necessário para evitar determinados erros de bloqueio em algumas implementações simultâneas. É preciso redefinir o random_number_milliseconds após cada espera.

Observação: o período de espera sempre é (2 ^ n) + random_number_milliseconds, em que n é um número inteiro monotonicamente crescente, definido inicialmente como 0. O valor n é incrementado em 1 a cada iteração (a cada solicitação).

O algoritmo é definido para terminar quando n é 5. Esse limite é aplicado somente para impedir que os clientes fiquem tentando infinitamente e gera um atraso total de cerca de 32 segundos antes que uma solicitação seja considerada "um erro irrecuperável". Seu cliente da API pode implementar um número maior de tentativas, se necessário.

Limites e cotas de APIs

Categorias de limite da API Limites
Criar usuários Não é possível criar mais de 10 usuários por domínio por segundo usando a API Directory.
Grupo adicionado como participante de outro grupo Pode haver um atraso de até 10 minutos antes que os participantes do grupo filho apareçam como do grupo pai. Esse limite pode mudar dependendo da capacidade do sistema.
Dispositivos móveis

Com a API Directory, você pode executar até:

  • 20 solicitações de ação por segundo.
  • 20 solicitações de exclusão por segundo.
  • 10 solicitações GET por segundo.
  • 10 solicitações de lista por segundo.
Renomear usuários Pode levar até 10 minutos para ser propagada para todos os serviços. Antes de renomear um usuário, recomendamos que você saia dele de todas as sessões e serviços do navegador. Confira mais detalhes em Atualizar usuários.
Criar/atualizar unidades organizacionais
  • Não é possível criar/atualizar mais de uma unidade organizacional por cliente por segundo com a API Directory.
  • A hierarquia da unidade organizacional do cliente é limitada a 35 níveis de profundidade.
  • O número total de unidades organizacionais por cliente não pode exceder 40.000.
Categorias de cota da API Cotas
Dispositivos Chrome annotatedLocation, máx. de caracteres O número máximo de caracteres para as informações de localização de um dispositivo é 200.
Dispositivos Chrome notes, máx. de caracteres O número máximo de caracteres para as informações de notas de um dispositivo é 500.
Dispositivos Chrome, máximo de user caracteres O número máximo de caracteres para um nome de usuário de dispositivo é 100.
Aliases de domínio, máximo O número máximo de aliases de domínio é 20.
Grupos, descrição O número máximo de caracteres em uma descrição é 4.096.
Grupos, por conta Com uma conta da edição sem custo financeiro legada do G Suite, o número de grupos é limitado a 10. Outras edições não têm limite para o número de grupos.
Grupos, participantes por grupo Com uma conta da edição sem custo financeiro legada do G Suite, um grupo pode ter até 100 membros. Outras edições não têm limite de participantes. Veja os limites de associação a grupos por usuário em Entender as políticas e os limites do Grupos.
String de consulta maxResults A API retorna:
  • Chrome e dispositivos móveis: um padrão e no máximo 100 entradas por página.
  • Grupos e participantes de grupo: um padrão e máximo de 200 entradas por página.
  • Usuários: um padrão de 100 entradas e um máximo de 500 entradas por página.
Os recursos de alias de usuário e unidade organizacional não usam a paginação de resposta. Todos os e-mails principais do usuário são retornados em ordem alfabética, e a ordem de resposta não diferencia maiúsculas de minúsculas.
Vários domínios, número máximo de domínios permitidos em uma conta 600 (1 domínio principal + 599 domínios adicionais)
Unidade organizacional, número máximo de usuários movidos de uma só vez Podem ser movidos de 20 usuários ao mesmo tempo. Além disso, é preciso que os endereços de e-mail principais do usuário já existam na conta.
Aliases de usuário O número total de aliases permitidos para cada conta de usuário é 30.
Aliases de usuário, utilizando um alias excluído Um alias de usuário excluído pode ser usado de novo imediatamente.

Outros tipos de limites Limitações e diretrizes
Faturamento e criação de usuários Para os usuários com um plano flexível do Google Workspace, criar usuários usando essa API terá impacto monetário e vai resultar em cobranças na conta de faturamento do cliente. Por exemplo, se você tiver um plano flexível do Google Workspace, criar 10 usuários vai resultar em cobranças por 10 licenças do Google Workspace sendo postadas na sua conta, proporcionalmente a partir do momento da criação. No plano anual, você já se comprometeu a pagar por um determinado número de licenças antecipadamente e só pode criar quantos usuários quiser. Para mais informações sobre os planos de faturamento e sua conta de faturamento, consulte a Central de Ajuda para administração.
Nome e sobrenome O nome e o sobrenome podem ter no máximo 40 caracteres. Eles aceitam caracteres Unicode/UTF-8 e podem conter espaços, letras (a-z), números (0-9), traços (-), barras (/) e pontos (.). Para mais informações sobre regras de uso de caracteres, consulte a Central de Ajuda para administração.
Grupos, excluindo A exclusão de um grupo não remove as contas de usuário dos membros do grupo.
Grupos e participantes de grupos, alteração de endereço de e-mail Nesta versão da API, o endereço de e-mail de um grupo pode ser alterado antes da ativação do serviço do Google Workspace. Use o Admin Console para alterar o endereço de e-mail de um membro do grupo. Depois da mudança, a API reflete automaticamente as mudanças no endereço de e-mail.
Grupos, configurações As configurações de acesso aos grupos, as opções de compartilhamento, o monitoramento e o arquivo de discussões são gerenciados no Admin Console. Para ver mais informações sobre configurações de grupos, consulte a Central de Ajuda para administração.
Grupos, enviando mensagens Para impedir spam e abuso por e-mail, o Google limita o número de mensagens que você pode enviar de uma vez para destinatários externos. Se você enviar uma mensagem para um grupo, cada participante externo será contabilizado como um destinatário. Veja mais informações em Limites de envio de e-mails e Impedir que e-mails para usuários do Gmail sejam bloqueados ou enviados para a pasta "Spam" .
Grupos, enviando mensagens NDR Não é possível enviar ou encaminhar recibos de falha de entrega (NDRs, na sigla em inglês), também chamados de "mensagens rejeitadas", para um grupo.
Grupos criados pelos usuários, limitações Para ver os limites de grupos criados pelos usuários, consulte a Central de Ajuda para administração
Unidade organizacional, ativando/desativando serviços Use o Admin Console para gerenciar a ativação e a desativação de serviços para uma unidade organizacional.
Senhas Pode conter qualquer combinação de caracteres. É necessário usar no mínimo oito caracteres. O comprimento máximo é de 100 caracteres.
Fotos Nesta versão da API, uma foto é a foto mais recente do perfil do Google do usuário.
Nomes de usuário Os nomes de usuários podem conter letras (a-z), números (0-9), traços (-), sublinhados (_) e o Google Workspace reconhece pontos ou pontos (.). Isso não é igual ao Gmail. O nome de usuário não pode conter sinal de igual (=), colchetes (<,>) nem mais de um ponto (.) consecutivo. Para ver mais informações, consulte a Central de Ajuda para administração.
Nomes de usuário, renomeação O Google Hangouts descarta todos os convites de bate-papo lembrados após a renomeação. O usuário precisará solicitar permissão para conversar com os amigos novamente. O nome de usuário antigo é mantido como um alias de e-mail para garantir a entrega contínua de e-mails no caso de configurações de encaminhamento de e-mail e não estará disponível como um novo nome de usuário. Para acessar detalhes importantes sobre o impacto da renomeação de usuários, consulte a Central de Ajuda para admins. Use a operação Excluir o alias de um usuário para remover o alias de e-mail após a renomeação.
Usuários em vários domínios Uma conta do Google Workspace pode incluir qualquer um dos seus domínios. Em uma conta com vários domínios, os usuários de um domínio podem compartilhar serviços com usuários em outros domínios. Vários componentes de domínio são:
  • Domínio principal: o domínio principal da sua conta é o domínio do administrador que aceitou os Termos de Serviço do Google Workspace. Este domínio está no nível da conta na unidade organizacional de nível superior. Ao se inscrever em uma conta do Google Workspace, recomendamos que você use seu domínio comercial como o domínio principal e reserve os outros domínios para usos especializados, como pilotos e testes.
    • Todos os superadministradores podem gerenciar a conta completa.
    • A API não pode mudar nem mover o domínio principal da conta do Google Workspace. No entanto, a API pode renomear a conta de um usuário, alterando o endereço de e-mail de um domínio para outro.
    • Nas contas do Google Workspace, você tem 21 dias para verificar a propriedade do domínio principal. Para domínios adicionais, você precisa verificar a propriedade antes de usá-lo no endereço de e-mail principal de um usuário. Nesses casos, o período de carência de 21 dias não se aplica.
    • Nesta versão da API, as configurações do domínio principal se aplicam a todos os domínios associados à conta, exceto o acesso do usuário aos serviços do Google Workspace.
  • Domínios de conta adicionais – Depois de estabelecer seu domínio principal e configurar sua conta, você poderá adicionar seus domínios adicionais à conta. Para domínios adicionais, verifique a propriedade ao configurar este domínio e antes de usá-lo no endereço de e-mail principal de um usuário.
  • Domínio principal do usuário – O domínio usado no endereço de e-mail principal de um usuário é o domínio principal do usuário. Esse domínio pode ser qualquer um da conta, incluindo o principal.
Confira as limitações mais recentes de vários domínios em Limitações de múltiplos domínios. Isso inclui informações sobre aliases de domínio, fusão de contas etc.
Avisos, participantes do grupo GROUP_CANNOT_CONTAIN_CYCLE – A API não permite um ciclo em associações a grupos. Por exemplo, se o grupo1 for membro do grupo2, o grupo2 não poderá fazer parte do grupo1.