Diretrizes de limitação do Microsoft Graph

Os limites de controle limitam número de chamadas simultâneas para um serviço para evitar a utilização exagerada dos recursos. O Microsoft Graph foi projetado para lidar com um alto volume de solicitações. Se ocorrer um número impressionante de solicitações, a limitação ajuda a manter um desempenho ideal e a confiabilidade do serviço Microsoft Graph.

Os limites de controle variam de acordo com o cenário. Por exemplo, se você estiver executando um grande volume de gravações, a possibilidade de limitação será maior do que se você estiver apenas executando leituras.

Observação

As soluções que precisam extrair um grande volume de dados do Microsoft Graph devem usar o Microsoft Graph Data Connect em vez das APIs REST do Microsoft Graph. O Microsoft Graph Data Connect permite que as organizações extraiam dados do Microsoft 365 em massa sem estarem sujeitas a limites de limitação.

O que acontece quando a limitação ocorre?

Quando um limite de limitação é excedido, o Microsoft Graph limita quaisquer solicitações adicionais desse cliente por um período de tempo. Quando ocorre a limitação, o Microsoft Graph retorna HTTP status código 429 (solicitações demais) e as solicitações falham. Um tempo de espera sugerido é retornado no cabeçalho de resposta da solicitação com falha. O comportamento de limitação pode depender do tipo e do número de solicitações. Por exemplo, se você tiver um grande volume de solicitações, todos os tipos de solicitações serão limitados. Os limites de limite variam de acordo com o tipo de solicitação. Portanto, você pode encontrar um cenário em que as gravações são limitadas, mas as leituras ainda são permitidas.

Cenários comuns de limitação

As causas mais comuns de limitação dos clientes incluem:

• Um grande número de solicitações em todos os aplicativos em um locatário.
• Um grande número de solicitações de um aplicativo específico entre todos os locatários.

Resposta de amostra

Sempre que o limite de estrangulamento é excedido, o Microsoft Graph responde com uma resposta semelhante a esta.

HTTP/1.1 429 Too Many Requests
Content-Length: 312
Content-Type: application/json
Retry-After: 10

{
  "error": {
    "code": "TooManyRequests",
    "innerError": {
      "code": "429",
      "date": "2020-08-18T12:51:51",
      "message": "Please retry after",
      "request-id": "94fb3b52-452a-4535-a601-69e0a90e3aa2",
      "status": "429"
    },
    "message": "Please retry again later."
  }
}

Práticas recomendadas para lidar com a limitação

Estas são as práticas recomendadas para lidar com a limitação:

• Reduza o número de operações por solicitação.
• Reduza a frequência de chamadas.
• Evite novas tentativas imediatas, pois todas as solicitações se acumulam em relação aos seus limites de uso.

Ao implementar o tratamento de erros, use o código de erro HTTP 429 para detectar a limitação. A resposta com falha inclui o cabeçalho de Retry-After resposta. Fazer backup de solicitações usando o Retry-After atraso é a maneira mais rápida de se recuperar da limitação porque o Microsoft Graph continua a registrar o uso de recursos enquanto um cliente está sendo limitado.

1. Aguarde o número de segundos especificado no cabeçalho Retry-After.
2. Repita a solicitação.
3. Se a solicitação falhar novamente com um código de erro 429, você ainda estará sendo limitado. Continue a usar o atraso recomendado Retry-After e tente novamente a solicitação até que ela seja bem-sucedida.

Todos os recursos e APIs descritos nos Limites específicos do serviço fornecem um cabeçalho Retry-After, exceto quando indicado.

Para uma discussão mais ampla sobre a limitação no Microsoft Cloud, veja Padrão de Limitação.

Observação

Se nenhum cabeçalho Retry-After for fornecido pela resposta, recomendamos implementar uma política de repetição exponencial de retirada. Você também pode implementar padrões mais avançados ao criar aplicativos em grande escala.

Os SDKs do Microsoft Graph já implementam manipuladores que dependem do cabeçalho Retry-After ou padrão para uma política de repetição de retirada exponencial.

Práticas recomendadas para evitar a limitação

Padrões de programação como pesquisando continuamente um recurso para verificar se há atualizações e a verificação regular das coleções de recursos para verificar se há recursos novos ou excluídos, possuem maior propensão de levar aplicativos a serem regulados e prejudicam o desempenho geral. Em vez disso, você deve aproveitar o controle de alterações e notificações de alteração quando estiverem disponíveis.

Observação

Práticas recomendadas para descobrir arquivos e detectar alterações em escala descrevem as práticas recomendadas em detalhes.

Limitação e dosagem

O lote JSON permite que você otimize seu aplicativo combinando várias solicitações em um único objeto JSON. As solicitações em um lote são avaliadas individualmente em relação aos limites de limitação e, se qualquer solicitação exceder os limites, ela falha com um código status de 429 e um erro semelhante à resposta de exemplo anterior. O lote em si tem êxito com um código de status de 200 (OK). Várias solicitações podem ser limitadas em um único lote. Você deve tentar novamente a cada solicitação com falha no lote utilizando o valor fornecido no cabeçalho de resposta retry-after do conteúdo JSON. Você pode tentar novamente para todas as solicitações com falha em um novo lote após o valor retry-after mais longo.

Se os SDKs tentarem novamente as solicitações limitadas automaticamente quando não estiverem em lote, as solicitações limitadas que fizeram parte de um lote não serão automaticamente repetidas.

Próxima etapa

Identificar os limites de limitação para diferentes recursos do Microsoft Graph