Limitação no Microsoft Fabric

O Microsoft Fabric utiliza a limitação para manter o desempenho e a fiabilidade do serviço quando as cargas de trabalho excedem a capacidade ou os limites de pedidos da API REST. Este artigo explica como funciona a limitação de taxa, como interpretar respostas HTTP 429 e como conceber aplicações que gerem eficazmente as quotas da API do Fabric.

Limites de quotas de API

A Microsoft Fabric está a introduzir a Quota Unificada de APIs REST para as suas APIs REST. Neste modelo, os pedidos à API são regulados por quotas ao nível da identidade, aplicadas por Utilizador ou Service Principal.

O objetivo é uma experiência consistente e previsível de limitação para os grupos de APIs governados, em automação, CI/CD e cenários orientados por agentes.

Anteriormente, cada API Microsoft Fabric REST aplicava as suas próprias regras independentes de limitação, o que frequentemente resultava em comportamentos inconsistentes entre endpoints. Como resultado, era difícil prever quando uma carga de trabalho poderia ser limitada, especialmente em cenários de automação que interagiam com múltiplas APIs e estavam sujeitos a diferentes limites.

Com a introdução da API Quota, o Fabric está a evoluir para uma abordagem mais consistente e baseada em identidade. O consumo de APIs é agora governado por uma quota unificada que é aplicada por identidade, proporcionando um modelo de limitação mais claro e previsível entre as APIs Fabric. No entanto, é importante salientar que alguns limites de limitação individuais específicos de cada API podem continuar a aplicar-se, para além da quota global das APIs.

Quando uma página de referência de API documenta uma quota, trate esse limite específico do endpoint como autoritativo para essa API. Se uma página de referência da API não indicar uma quota numérica, conceba a sua aplicação para lidar com respostas 429, respeitando Retry-After, efetuando um número limitado de novas tentativas e evitando picos de pedidos.

Como Funciona o Modelo de Quotas

Cada identidade — seja um utilizador ou um principal de serviço — recebe vários buckets de quotas independentes que governam diferentes categorias de tráfego API. Quando a identidade envia um pedido, este é avaliado em relação à quota da categoria API utilizada.

Existem três Quotas Unificadas:

1. Quota Unificada para APIs de Plataforma — dedicada a APIs de Plataforma.
2. Quota Unificada para APIs do Agendador de Tarefas — dedicada às APIs do Agendador de Tarefas.
3. Quota unificada para APIs de operações de longa duração — dedicada às APIs de operações de longa duração.

Como estas quotas são independentes, a atividade numa categoria não consome quotas de outra categoria. Por exemplo, um principal de serviço poderia consumir toda a sua Cota Unificada para APIs do Agendador de Tarefas sem afetar a sua Cota Unificada de APIs de Plataforma. Esta separação garante que cargas de trabalho de alto volume em áreas especializadas da API não afetam as operações gerais da API e permite um comportamento de redução de velocidade mais previsível entre diferentes tipos de pedidos.

Aplicação da API

A quota das APIs é aplicada por identidade, o que significa que cada utilizador, principal de serviço ou identidade gerida recebe a sua própria quota independente. As quotas nunca são partilhadas entre identidades, e todas as APIs Fabric elegíveis consomem de um bucket de quotas comum associado a essa identidade.

Como resultado, a utilização da API por uma identidade não tem impacto em nenhuma outra identidade. Por exemplo, um principal de serviço muito utilizado pode esgotar a sua própria quota de APIs sem afetar as quotas de outros utilizadores ou aplicações.

Da mesma forma, se uma identidade atingir o limite da sua quota e for limitada, essa limitação aplica-se apenas a essa identidade, enquanto outras identidades continuam a operar normalmente. Este isolamento proporciona um consumo de API mais previsível e gerível entre cargas de trabalho.

Hierarquia de aplicação das quotas

Cada pedido de API começa com uma identidade — seja uma conta de utilizador ou um principal de serviço. Quando essa identidade chama uma API Fabric, o pedido consome primeiro capacidade da quota das APIs partilhadas, que é aplicada por identidade e não por API. Esta quota atua como um mecanismo centralizado de limitação que é partilhado entre todas as APIs participantes, garantindo que uma única identidade não possa exceder a sua taxa de pedido alocada.

Depois de a solicitação ser avaliada em função da quota partilhada das APIs, também são aplicados os limites de limitação de taxa específicos de cada API. Estes limites são independentes da quota partilhada e podem existir apenas para certas APIs. Como resultado, um pedido deve satisfazer tanto a quota das APIs ao nível de identidade como quaisquer limites individuais de API aplicáveis para ser processado com sucesso.

Em termos práticos, a quota de APIs partilhadas proporciona uma experiência consistente de limitação entre APIs, enquanto os limites individuais das APIs continuam a proteger serviços específicos que requerem salvaguardas adicionais. Uma chamada API pode, portanto, ser limitada porque a identidade esgotou a sua quota partilhada ou porque atingiu o limite de um determinado endpoint da API.

Conceitos-chave:

• Fiscalização baseada em identidade: A quota é acompanhada separadamente para cada utilizador ou principal de serviço.
• Partilhado entre APIs: Os pedidos a diferentes APIs consomem do mesmo conjunto partilhado de quotas das APIs.
• Apenas limitação: A Quota da API controla as taxas de pedido, mas não afeta a autorização ou as permissões.
• Aplicação dupla: Tanto a quota de APIs partilhadas como quaisquer limites específicos da API são avaliados para cada pedido.
• O limite mais restritivo vence: Um pedido é limitado quando a quota partilhada ou um limite específico da API aplicável é ultrapassado.

Como é consumida a quota

Cada pedido de API consome quota do bucket de quotas da API da identidade chamante. Todos os pedidos feitos por essa identidade contam para a mesma quota partilhada, independentemente da API chamada.

Período de quotas e renovação

A quota de APIs é aplicada usando uma janela fixa de 60 segundos. A reserva da cota é reabastecida de uma só vez quando a janela atual termina. A quota não é reposta gradualmente durante esse período.

Exemplo de Cronologia

Second 0   → Quota window begins. Bucket is full (300 requests available).
Second 1   → 300 requests are made. Bucket is exhausted.
             Additional requests receive HTTP 429 (Too Many Requests).

Seconds 2-59 → All additional requests continue to receive HTTP 429.
               No quota is restored during the window.

Second 60  → New quota window begins.
             Bucket is fully replenished (300 requests available).
             Requests are accepted again.

Implicações práticas

• São permitidas rajadas de pedidos no início de um período, mas isso pode fazer com que a identidade fique sujeita a limitação de débito durante o restante desse período.
• Distribuir os pedidos de forma uniforme ao longo do período de 60 segundos ajuda a evitar a limitação.
• Respeite sempre o cabeçalho de resposta Retry-After. Indica quanto tempo esperar antes de tentar novamente um pedido limitado.

Detalhes do limite de taxa por API

Embora o Microsoft Fabric forneça categorias unificadas de limitação e conceitos de quotas partilhadas, os limites reais de taxa podem variar consoante a API. Consulta sempre a secção de limites de estrangulamento da API específica que estás a chamar.

Mensagem de limitação

Quando ocorre limitação, o Fabric devolve um código de estado HTTP 429 (Demasiados pedidos). O Fabric devolve um código de estado 429 por duas razões distintas, cada uma identificada por um diferente errorCode no corpo da resposta:

• Limite de taxa excedido (RequestBlocked)
• Limite de capacidade excedido (CapacityLimitExceeded)

Inspecione o valor errorCode na resposta para determinar que condição ocorreu e como responder.

Limite de taxa ultrapassado (RequestBlocked)

Quando um utilizador envia muitos pedidos que excedem um limite pré-determinado durante uma janela de tempo, o Fabric limita os pedidos adicionais desse utilizador por um curto período.

Neste caso, o Fabric devolve um código de estado HTTP 429 (Demasiados pedidos) com um Retry-After cabeçalho HTTP na resposta, indicando quantos segundos a aplicação que chama deve esperar antes de tentar novamente a chamada. O corpo da resposta utiliza o código de erro RequestBlocked:

{
    "errorCode": "RequestBlocked",
    "message": "Request is blocked by the upstream service until: 2/18/2026 10:45:04 PM (UTC)"
}

Quando receber este erro, aguarde a duração especificada no Retry-After cabeçalho antes de tentar novamente o pedido.

A captura de ecrã seguinte mostra um exemplo de resposta, sugerindo que o utilizador espera 55 segundos antes de tentar novamente a chamada.

Limite de capacidade ultrapassado (CapacityLimitExceeded)

O Fabric também devolve um código de estado HTTP 429 (Demasiados pedidos) quando a capacidade do Fabric da sua organização ultrapassou os seus limites. Ao contrário da limitação de velocidade, esta limitação não é causada pelo número de chamadas de API que um chamador específico faz. Em vez disso, ocorre quando as unidades de computação (capacidade) consumidas na sua capacidade excedem os limites do SKU Fabric adquirido. O corpo da resposta utiliza o código de erro CapacityLimitExceeded:

{
    "errorCode": "CapacityLimitExceeded",
    "message": "Your organization's Fabric compute capacity has exceeded its limits. Try again later."
}

Quando receber este erro, tente novamente o pedido mais tarde. Como esta limitação depende do total de recursos de computação consumidos na sua capacidade, e não da sua taxa individual de pedidos, é pouco provável que tentar novamente de imediato tenha êxito até que o consumo de recursos de computação da capacidade volte a situar-se dentro dos respetivos limites. Se encontrares este erro frequentemente, considera aumentar ou ampliar a capacidade do Fabric. Para mais informações sobre unidades de capacidade, SKUs e como a capacidade de Fabric é consumida, consulte Planeie o tamanho da sua capacidade.

Considerações e limitações

Todos os administradores do Fabric e API pública central podem ser limitados.

Tenha estas considerações em mente ao desenhar aplicações que chamam APIs Fabric REST:

• São aplicadas quotas para a identidade do chamador e a API a ser chamada. Identidades separadas não partilham necessariamente o mesmo contador de pedidos, mas cada chamador deve seguir os limites documentados para a API.
• Muitos limites de taxa são avaliados ao longo de janelas de um minuto. Se exceder um limite, aguarde o valor Retry-After antes de enviar mais pedidos.
• A limitação de capacidade é diferente da limitação da taxa de pedidos. CapacityLimitExceededindica que a capacidade do Fabric está sobrecarregada, não que o chamador tenha excedido uma quota de API por minuto.
• É pouco provável que voltar a tentar imediatamente após um erro de limitação de capacidade tenha êxito. Utilize uma política limitada de novas tentativas e investigue a utilização da capacidade se o erro persistir.
• Para integrações de alto volume, prefira operações de lista, em massa ou em lote quando estiverem disponíveis, armazene em cache metadados que mudam raramente e espalhe os pedidos de forma uniforme ao longo do tempo.
• Para APIs que suportam paginação, use tokens de continuação em vez de fazer consultas amplas repetidas desde o início.

Perguntas frequentes

Como é que sei se atingi uma quota de API ou um limite de capacidade?

Verifique o errorCode no corpo da resposta 429. RequestBlocked significa que a taxa de pedido excedeu os limites de limitação do serviço. CapacityLimitExceededsignifica que o cálculo consumido na capacidade do Fabric excedeu os limites do SKU adquirido.

Quando é que a minha quota é reposta?

Muitos limites de taxa da API Fabric REST são avaliados ao longo de janelas de um minuto. Se a resposta incluir um Retry-After cabeçalho, use esse valor como o tempo de espera autoritativo antes de tentar novamente.

Posso verificar a minha quota restante de API antes de fazer um pedido?

As respostas da API REST do Fabric não fornecem um contador geral de quotas restantes para todas as APIs. Constrói clientes para que possam detetar respostas 429, respeitar Retry-Aftere reduzir o volume de pedidos quando ocorrer limitação.

Como posso reduzir a hipótese de ser limitado?

Use operações em massa e em lote quando disponíveis, prefira APIs de listas em vez de muitas chamadas de recurso único, armazene em cache metadados frequentemente acedidos e evite surtos repentinos de tráfego. Em caso de limitação persistente da capacidade, use a aplicação Microsoft Fabric Capacity Metrics para identificar as capacidades e as cargas de trabalho sobrecarregadas.

Devo tentar novamente todas as respostas 429 da mesma forma?

No. Para RequestBlocked, aguarde o cabeçalho Retry-After e, em seguida, tente novamente com uma política de repetição com limites. Para CapacityLimitExceeded, volte a tentar mais tarde com retrocesso exponencial e investigue a utilização da capacidade se o problema persistir.

Conteúdo relacionado

• Usando as APIs REST do Microsoft Fabric
• Escopos
• Resolução de Problemas das APIs REST do Microsoft Fabric
• Planeie o tamanho da sua capacidade
• Compreenda a limitação da capacidade do Fabric
• Aplicativo Microsoft Fabric Capacity Metrics