Limites da API de proteção de serviço

Para garantir a disponibilidade e o desempenho consistentes para todos, o sistema aplica limites à forma como as APIs são usadas. Esses limites detectam quando os aplicativos cliente fazem demandas extraordinárias nos recursos do servidor.

Esses limites não afetam usuários normais de clientes interativos. Eles afetam apenas os aplicativos cliente que executam um volume extraordinário de solicitações de API. Esses limites protegem a plataforma Microsoft Dataverse contra aumentos aleatórios e inesperados em volumes de solicitação que ameaçam sua disponibilidade e desempenho.

Quando um aplicativo cliente faz solicitações extraordinariamente exigentes, o Dataverse segue o padrão comum para serviços online. Ele retorna um erro que indica que muitas solicitações foram recebidas.

• Com a API Web, o Dataverse retorna um erro 429 Too Many Requests.
• Com o SDK do Dataverse para .NET, você obtém um erro OrganizationServiceFault com um dos três códigos de erro específicos.

Saiba mais sobre os erros de limite da API de proteção de serviço

Impacto nos aplicativos cliente

Os aplicativos cliente são responsáveis por gerenciar erros de limite da API de proteção de serviço. A forma como você gerencia esse erro depende da natureza do aplicativo.

Aplicativos cliente interativos

Os limites de proteção de serviço são altos o suficiente para que seja raro para um indivíduo que usa um aplicativo cliente interativo encontrá-los durante o uso normal. No entanto, é possível quando o aplicativo cliente permite operações em massa. Os desenvolvedores de aplicativos cliente devem estar cientes de como os limites da API de proteção de serviço são impostos e criar a interface do usuário para reduzir o potencial para que os usuários enviem solicitações extremamente exigentes para o servidor. Mesmo quando eles fazem isso, eles ainda devem esperar que erros de limite da API de proteção de serviço possam ocorrer e estar preparados para lidar com eles.

Os desenvolvedores de aplicativos cliente não devem simplesmente lançar o erro para exibir a mensagem para o usuário. A mensagem de erro não se destina aos usuários finais. Saiba mais sobre estratégias específicas para tentar novamente as operações.

Aplicativos de integração de dados

Os aplicativos projetados para carregar dados no Dataverse ou executar atualizações em massa devem gerenciar erros de limite da API de proteção de serviço. Esses aplicativos priorizam a taxa de transferência para que possam concluir seu trabalho no período mínimo de tempo. Esses aplicativos devem ter uma estratégia para repetir operações. Há várias estratégias que podem ser aplicadas para obter a taxa de transferência máxima. Saiba como maximizar a taxa de transferência.

Aplicativos do portal

Os aplicativos de portal costumam enviar solicitações de usuários anônimos por meio de uma conta principal de serviço. Como os limites da API de proteção de serviço são baseados por usuário, os aplicativos do portal podem atingir os limites da API de proteção de serviço com base na quantidade de tráfego que o portal experimenta. Assim como os aplicativos cliente interativos, não exiba erros de limite da API de proteção de serviço para o usuário final do portal. A interface do usuário do portal deve desabilitar novas solicitações e exibir uma mensagem informando que o servidor está ocupado. A mensagem pode incluir o momento em que o aplicativo pode começar a aceitar novas solicitações, calculado usando a duração Retry-After retornada com erro.

Impacto nos plug-ins e nas atividades de fluxo de trabalho personalizadas

Plug-ins e atividades de fluxo de trabalho personalizadas aplicam lógica de negócios acionada por solicitações de entrada. Os limites de proteção de serviço não se aplicam a operações de dados originadas de plug-ins e atividades personalizadas de fluxo de trabalho. Plug-ins e atividades personalizadas de fluxo de trabalho são executados no serviço de área restrita isolada. As operações do Dataverse invocadas no serviço sandbox não usam os endpoints de API públicos.

Se o aplicativo executar operações que disparam a lógica personalizada, o número de solicitações enviadas por plug-ins ou atividades de fluxo de trabalho personalizadas não conta para os limites da API de proteção de serviço. No entanto, o tempo extra de computação que essas operações contribuem é adicionado à solicitação inicial que as disparou. Esse tempo de computação faz parte dos limites da API de proteção de serviço. Saiba como o sistema impõe limites de API de Proteção de Serviço.

Repetir operações

Quando ocorre um erro de limite de API de proteção de serviço, ele fornece um valor que indica a duração antes que novas solicitações do usuário possam ser processadas.

• Quando um erro 429 é retornado da API Web, a resposta inclui um cabeçalho Retry-After com número de segundos.
• Com o SDK para .NET, um valor TimeSpan é retornado na OrganizationServiceFaultcoleção .ErrorDetails com a chave Retry-After.

A duração do Retry-After

A Retry-After duração depende da natureza das operações enviadas no período anterior de 5 minutos. Quanto mais exigentes forem as solicitações, mais tempo levará para o servidor se recuperar.

Hoje, devido à maneira como os limites são avaliados, você pode esperar exceder o número de solicitações e os limites de tempo de execução por um período de 5 minutos antes que os limites da API de proteção de serviço entrem em vigor. No entanto, exceder o número de solicitações simultâneas retorna um erro imediatamente. Se o aplicativo continuar a enviar essas solicitações exigentes, a duração será estendida para minimizar o impacto sobre os recursos compartilhados. Esta extensão faz com que o tempo de espera após cada repetição seja maior, o que significa que seu aplicativo experimenta períodos mais longos de inatividade enquanto aguarda. Esse comportamento pode mudar no futuro.

Quando possível, tente obter uma taxa consistente começando com um número menor de solicitações e aumentando gradualmente até começar a atingir os limites da API de proteção de serviço. Depois disso, permita que o servidor informe quantas solicitações ele pode lidar em um período de 5 minutos. Manter o número máximo de solicitações limitado durante o período de 5 minutos e aumentá-lo gradualmente mantém o tempo de espera de repetição baixo, otimizando o desempenho total e minimizando os picos de uso de recursos do servidor.

Tentativa de aplicativo interativo

Se o cliente for um aplicativo interativo, exiba uma mensagem informando que o servidor está ocupado enquanto você tenta novamente a solicitação feita pelo usuário. Talvez você queira fornecer uma opção para o usuário cancelar a operação. Não permita que os usuários enviem mais solicitações até que a solicitação anterior enviada seja concluída.

Repetição de aplicativo não interativo

Se o cliente não for interativo, aguarde a duração passar antes de enviar a solicitação novamente. Para pausar a execução da tarefa atual, use Task.Delay ou métodos equivalentes.

Como tentar novamente

A seção a seguir descreve como repetir aplicativos .NET usando o SDK do Dataverse para .NET ou API Web:

SDK para .NET

Se você estiver usando o SDK para .NET, utilize as classes PowerPlatform.Dataverse.Client.ServiceClient ou Xrm.Tooling.Connector.CrmServiceClient. Essas classes implementam os métodos IOrganizationService e podem gerenciar todos os erros de limite da API de proteção de serviço retornados.

Começando com versões após a 9.0.2.16 (maio de 2019) do Xrm.Tooling.Connector, o cliente pausa e reenvia a solicitação automaticamente após o Retry-After período de duração.

Se seu aplicativo atualmente usa as classes Xrm.Sdk.Client.OrganizationServiceProxy ou Xrm.Sdk.WebServiceClient.OrganizationWebProxyClient de baixo nível, substitua essas classes pela ServiceClient classe ou CrmServiceClient pela classe. A OrganizationServiceProxy classe foi preterida.

Mais informações:

• Crie aplicativos cliente windows usando as ferramentas XRM.
• Substituição do tipo de autenticação do Office365 e da classe OrganizationServiceProxy para se conectar ao Dataverse

Web API

Se você estiver usando a API Web com uma biblioteca de clientes, poderá achar que ela dá suporte ao comportamento de repetição esperado para 429 erros. Verifique com o editor da biblioteca de clientes.

Se você estiver usando o PowerShell, o parâmetro MaximumRetryCountInvoke-RestMethod cmdlet do PowerShell especifica quantas vezes o PowerShell tenta novamente uma solicitação quando um código de falha está entre 400 e 599, inclusive ou 304 é recebido. Isso significa que o PowerShell reexecuta os erros 429 de proteção de serviço do Dataverse quando você inclui um valor para esse parâmetro. Saiba mais sobre como gerenciar limites de proteção de serviço do Dataverse usando o PowerShell.

Se você escreveu sua própria biblioteca, poderá incluir comportamentos semelhantes ao incluído neste código de exemplo para uma biblioteca de classes webAPIService auxiliar (C#).

/// <summary>
/// Specifies the Retry policies
/// </summary>
/// <param name="config">Configuration data for the service</param>
/// <returns></returns>
static IAsyncPolicy<HttpResponseMessage> GetRetryPolicy(Config config)
{
    return HttpPolicyExtensions
      .HandleTransientHttpError()
      .OrResult(httpResponseMessage => httpResponseMessage.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
      .WaitAndRetryAsync(
         retryCount: config.MaxRetries,
         sleepDurationProvider: (count, response, context) =>
         {
            int seconds;
            HttpResponseHeaders headers = response.Result.Headers;

            if (headers.Contains("Retry-After"))
            {
               seconds = int.Parse(headers.GetValues("Retry-After").FirstOrDefault());
            }
            else
            {
               seconds = (int)Math.Pow(2, count);
            }
            return TimeSpan.FromSeconds(seconds);
         },
         onRetryAsync: (_, _, _, _) => { return Task.CompletedTask; }
      );
}

Este exemplo usa o Polly, uma biblioteca de resiliência do .NET e tratamento de falhas transitórias que permite que os desenvolvedores expressem políticas como Retry, Circuit Breaker, Timeout, Isolamento de Compartimento e Fallback de maneira fluente e thread-safe.

Os cabeçalhos da resposta HTTP

Se você estiver usando solicitações HTTP com a API Web, poderá acompanhar os valores de limite restantes usando os seguintes cabeçalhos de resposta HTTP:

Header	Descrição do valor
x-ms-ratelimit-burst-remaining-xrm-requests	O número restante de solicitações para essa conexão
x-ms-ratelimit-time-remaining-xrm-requests	A duração combinada restante para todas as conexões usando a mesma conta de usuário

Não dependa desses valores para controlar quantas solicitações você envia. Eles são destinados a fins de depuração. Se você estiver removendo o cookie de afinidade, esses valores serão redefinidos quando você se conectar a um servidor diferente.

Como o sistema impõe limites de API de Proteção de Serviço

Dois dos limites da API de proteção de serviço usam uma janela deslizante de cinco minutos (300 segundos). Se um dos limites exceder os 300 segundos anteriores, o sistema retornará um erro de limite de API de proteção de serviço em solicitações subsequentes. Esse erro protege o serviço até que a duração do Retry-After termine.

O sistema avalia os limites da API de proteção de serviço para cada usuário. Cada usuário autenticado tem um limite independente. O sistema limita somente as contas de usuário que fazem exigências extraordinárias. Outros usuários não enfrentam nenhum impacto.

O sistema impõe limites de API de proteção de serviço com base em três facetas:

• O número de solicitações enviadas por um usuário.
• O tempo de execução combinado que o sistema requer para processar solicitações enviadas por um usuário.
• O número de solicitações simultâneas enviadas por um usuário.

Se o sistema aplicasse o limite apenas ao número de solicitações que um usuário envia, seria possível contorná-lo. O sistema adiciona as outras facetas para combater essas tentativas. Por exemplo:

• Você pode enviar menos solicitações agrupando-as em operações em lote.
  • O limite de tempo de execução combinado contraria esse limite.
• Em vez de enviar solicitações individualmente em sequência, você pode enviar um grande número de solicitações simultâneas antes que os limites da API de proteção de serviço sejam impostos.
  • O limite de solicitação simultânea contraria esse limite.

Cada servidor Web que seu ambiente disponibiliza impõe esses limites de forma independente. A maioria dos ambientes tem mais de um servidor Web. Os ambientes de avaliação alocam apenas um único servidor Web. Vários fatores determinam o número real de servidores Web que seu ambiente disponibiliza. O Dataverse fornece esses fatores como parte do serviço gerenciado. Um dos fatores é quantas licenças de usuário você compra.

A tabela a seguir descreve os limites padrão da API de proteção de serviço que o sistema impõe por servidor Web:

Medida	Description	Limite por servidor Web
Número de solicitações	O número cumulativo de solicitações que o usuário faz.	6.000 dentro da janela deslizante de cinco minutos
Tempo de execução	O tempo de execução combinado de todas as solicitações que o usuário faz.	20 minutos (1.200 segundos) dentro da janela deslizante de cinco minutos
Número de solicitações simultâneas	O número de solicitações simultâneas que o usuário faz.	52 ou superior

Importante

Esses limites podem mudar e podem variar entre ambientes diferentes. Esses números representam valores padrão e fornecem uma ideia de quais valores você pode esperar.

Erros de limite da API de proteção de serviço

Esta seção descreve os três tipos de erros de limite da API de proteção de serviço que o sistema pode retornar. Também descreve fatores que causam esses erros e possíveis estratégias de mitigação.

• O código de erro é o valor de erro numérico que o SDK para .NET OrganizationServiceFaultretornaErrorDetails .
• O código Hex é o valor de erro hexadecimal retornado pela API Web.

Número de solicitações

Esse limite conta o número total de solicitações durante o período anterior de 300 segundos.

Código do erro	Código hexadecimal	Message
-2147015902	0x80072322	Number of requests exceeded the limit of 6000 over time window of 300 seconds.

Um usuário típico de um aplicativo interativo não envia 1.200 solicitações por minuto para exceder esse limite, a menos que o aplicativo permita que os usuários executem operações em massa.

Por exemplo, se uma exibição de lista habilitar a seleção de 250 registros por vez e permitir que um usuário execute alguma operação em todos esses registros, o usuário precisará executar essa operação 24 vezes em um período de 300 segundos. O usuário precisa concluir a operação em cada lista dentro de 12,5 segundos.

Se seu aplicativo fornecer essa funcionalidade, considere algumas das seguintes estratégias:

• Diminua o número total de registros que os usuários podem selecionar em uma lista. Se o número de itens exibidos em uma lista for reduzido para 50, o usuário precisará executar essa operação 120 vezes em 300 segundos. O usuário deve concluir a operação em cada lista dentro de 2,5 segundos.
• Combine as operações selecionadas em um lote. Um lote pode conter até 1.000 operações e evita o limite de número de solicitações. No entanto, você precisa estar preparado para o limite de tempo de execução.

Tempo de execução

Esse limite controla o tempo de execução combinado de solicitações de entrada durante o período anterior de 300 segundos.

Código do erro	Código hexadecimal	Message
-2147015903	0x80072321	Combined execution time of incoming requests exceeded limit of 1,200,000 milliseconds over time window of 300 seconds. Decrease number of concurrent requests or reduce the duration of requests and try again later.

Algumas operações exigem mais recursos do que outras. Operações em lote, importação de soluções e consultas altamente complexas podem ser muito exigentes. Essas operações também podem ser executadas simultaneamente em solicitações simultâneas. Portanto, dentro da janela de 5 minutos, você pode solicitar operações que exijam mais de 20 minutos de tempo de computação combinado.

Você pode encontrar esse limite ao usar estratégias que envolvem operações em lotes e solicitações simultâneas para evitar o limite de número de solicitações.

Solicitações simultâneas

Esse limite controla o número de solicitações simultâneas.

Código do erro	Código hexadecimal	Message
-2147015898	0x80072326	Number of concurrent requests exceeded the limit of 52.

Os aplicativos cliente não se limitam a enviar solicitações individuais sequencialmente. O cliente pode aplicar padrões de programação paralelos ou vários métodos para enviar várias solicitações simultaneamente. O servidor pode detectar quando está respondendo a várias solicitações do mesmo usuário simultaneamente. Se esse número de solicitações simultâneas for excedido, o servidor gerará esse erro. O limite pode ser maior que 52 em alguns casos.

O envio de solicitações simultâneas pode ser uma parte fundamental de uma estratégia para maximizar a taxa de transferência, mas é importante mantê-la sob controle. Quando você usa Programação Paralela no .NET, o grau padrão de paralelismo depende do número de núcleos de CPU no servidor que executa o código. Ele não deve exceder o limite. Você pode definir a Propriedade ParallelOptions.MaxDegreeOfParallelism para definir um número máximo de tarefas simultâneas.

Saiba mais sobre como enviar solicitações paralelas.

Como maximizar a taxa de transferência

Quando você tiver um aplicativo que deve priorizar a taxa de transferência para mover a maioria dos dados no período mais curto, aplique as estratégias a seguir.

Deixe o servidor informar quanto ele pode suportar

Não tente calcular quantas solicitações enviar por vez. Cada ambiente pode ser diferente. Aumente gradualmente a taxa com que você envia solicitações até começar a atingir os limites e, em seguida, dependa do limite da API Retry-After de proteção de serviço para informar quando enviar mais. Esse valor mantém sua taxa de transferência total no nível mais alto possível.

Usar vários threads

O limite maior no número de threads simultâneos é algo que seu aplicativo pode usar para ter uma melhoria significativa no desempenho. Essa melhoria será verdadeira se suas operações individuais forem relativamente rápidas. Dependendo da natureza dos dados que você está processando, talvez seja necessário ajustar o número de threads para obter a taxa de transferência ideal. Saiba mais sobre como enviar solicitações em paralelo.

Evitar lotes grandes

Envio em lote refere-se ao envio de várias operações em uma única solicitação.

A maioria dos cenários é mais rápida ao enviar solicitações individuais com um alto grau de paralelismo. Se você achar que o tamanho do lote pode melhorar o desempenho, comece com um lote pequeno de 10 e aumente a concorrência até começar a obter erros de limites de proteção da API do serviço, que você repetirá.

Com o SDK para .NET, essa abordagem significa usar ExecuteMultipleRequest, o que normalmente permite enviar até 1.000 operações em uma solicitação. O principal benefício que essa abordagem oferece é que ela reduz a quantidade total de carga XML que deve ser enviada pela transmissão. Essa abordagem fornece algum benefício de desempenho quando a latência de rede é um problema. Para limites de proteção de serviço, aumenta o tempo total de execução por solicitação. Lotes de tamanho maior aumentam a chance de você encontrar limites de tempo de execução em vez de limites no número de solicitações.

No passado, ExecuteMultiple as operações eram limitadas a apenas duas de cada vez devido ao impacto no desempenho que esse limite poderia ter. Esse limite não é mais o caso, pois os limites da API de tempo de execução da proteção de serviço tornaram esse limite redundante.

Ao usar a API Web, a carga JSON menor enviada pela rede para solicitações individuais significa que a latência de rede não é um problema. Saiba mais sobre como executar operações em lote usando a API Web.

Observação

As operações em lote não são uma estratégia válida para ignorar os limites de direitos. Os limites da API de proteção de serviço e os limites de direitos são avaliados separadamente. Os limites de direito são baseados em operações CRUD e acumulam-se, estejam ou não incluídos em uma operação em lote. Saiba mais sobre os limites de direitos.

Estratégias para gerenciar os limites da API de proteção de serviço

Esta seção descreve maneiras de criar seus clientes e sistemas para evitar erros de limite de API de proteção de serviço. Talvez você também queira considerar como gerenciar suas licenças para reduzir o impacto.

Atualizar seu aplicativo cliente

O Dataverse impõe limites da API de Proteção de Serviço desde 2018. No entanto, muitos aplicativos cliente foram desenvolvidos antes que esses limites existissem. Esses clientes não esperam esses erros e não podem lidar com os erros corretamente. Atualize esses aplicativos e aplique os padrões às operações de repetição descritas anteriormente.

Avançar para a integração em tempo real

O ponto principal dos limites da API de proteção de serviço é suavizar o impacto de solicitações altamente exigentes que ocorrem em um curto período de tempo. Se os processos comerciais atuais dependerem de grandes trabalhos periódicos noturnos, semanais ou mensais que tentam processar grandes quantidades de dados em um curto período de tempo, considere como você pode habilitar uma estratégia de integração de dados em tempo real. Se você puder se afastar de processos que exigem operações altamente exigentes, poderá reduzir o impacto que os limites de proteção do serviço têm.

Perguntas frequentes

Esta seção inclui perguntas frequentes. Se você tiver perguntas que não foram respondidas, poste-as usando o botão Comentários na parte inferior desta página para enviar comentários sobre essa página.

Estou usando um aplicativo ETL que licenciei. Como faço para obter a taxa de transferência ideal?

Trabalhe com o fornecedor do aplicativo ETL para saber quais configurações aplicar. Verifique se você está usando uma versão do produto que dá suporte ao comportamento de Retry-After.

Esses limites se aplicam à pesquisa do Dataverse?

Não. A pesquisa nativa do Dataverse usa uma API diferente (api/search em vez de api/data) e tem regras diferentes. Quando você usa a API de pesquisa do Dataverse, há um limite de limitação de uma solicitação por segundo para cada usuário.

Saiba mais sobre os Limites de Proteção do Serviço de Pesquisa do Dataverse.

Como esses limites se aplicam a quantas solicitações um usuário tem direito a cada dia?

Esses limites não estão relacionados aos limites de direitos. Saiba mais sobre os limites de direitos.

Os limites são aplicados de forma diferente aos usuários do aplicativo?

Não. O sistema aplica os mesmos limites a todos os usuários.

Consulte também

Administrar o Power Platform/Licenciamento e gerenciamento de licenças/Limites e alocações de solicitações
Visão geral dos limites de API do Dataverse
Usar a API Web do Dataverse
Usar o SDK do Dataverse para .NET