Ograniczanie przepustowości w Microsoft Fabric

Microsoft Fabric używa ograniczania przepustowości, aby zachować wydajność i niezawodność usługi, gdy obciążenia przekraczają limity wydajności lub żądań interfejsu API REST. W tym artykule wyjaśniono, jak działa ograniczanie przepustowości, jak interpretować odpowiedzi HTTP 429 oraz jak projektować aplikacje obsługujące przydziały interfejsu API Fabric.

Limity użycia interfejsu API

Microsoft Fabric wprowadza ujednolicony limit dla interfejsów API REST dla swoich interfejsów API REST. W ramach tego modelu żądania API podlegają limitom na poziomie tożsamości, egzekwowanym dla każdego użytkownika lub Service Principal.

Celem jest spójny i przewidywalny mechanizm ograniczania przepustowości dla zarządzanych grup interfejsów API w scenariuszach automatyzacji, CI/CD i z użyciem agentów.

Wcześniej każdy interfejs API REST Microsoft Fabric wymuszał własne niezależne reguły ograniczania przepustowości, które często powodowały niespójne zachowanie między punktami końcowymi. W rezultacie trudno było przewidzieć, kiedy obciążenie może zostać ograniczone, zwłaszcza w przypadku scenariuszy automatyzacji, które współdziałały z wieloma interfejsami API i były objęte różnymi limitami.

Wraz z wprowadzeniem limitu przydziału interfejsów API Fabric przechodzi do bardziej spójnego podejścia opartego na tożsamościach. Korzystanie z interfejsu API podlega teraz jednolitemu limitowi egzekwowanemu dla każdej tożsamości, co zapewnia bardziej przejrzysty i przewidywalny model ograniczania liczby żądań w interfejsach API platformy Fabric. Należy jednak pamiętać, że niektóre limity ograniczania specyficzne dla poszczególnych interfejsów API mogą nadal mieć zastosowanie oprócz ogólnego limitu przydziału interfejsów API.

Gdy strona referencyjna interfejsu API dokumentuje limit przydziału, traktuj ten limit specyficzny dla punktu końcowego jako autorytatywny dla tego interfejsu API. Jeśli strona referencyjna interfejsu API nie wyświetla limitu przydziału liczbowego, zaprojektuj aplikację tak, aby obsługiwała odpowiedzi 429, honorując Retry-After, stosując ograniczone ponawianie prób i unikając serii.

Jak działa model limitu przydziału

Każdej tożsamości — użytkownikowi lub jednostce usługi — przypisuje się wiele niezależnych pul limitów, które regulują różne kategorie ruchu API. Gdy tożsamość wysyła żądanie, jest ono sprawdzane pod kątem limitu dla używanej kategorii interfejsu API.

Są trzy ujednolicone limity:

1. Ujednolicony limit przydziału dla interfejsów API platformy — przeznaczony dla interfejsów API platformy.
2. Ujednolicony limit dla interfejsów API harmonogramu zadań — dedykowany interfejsom API harmonogramu zadań.
3. Wspólny limit dla interfejsów API operacji długotrwałych — przeznaczony dla interfejsów API operacji długotrwałych.

Ponieważ te przydziały są niezależne, działanie w jednej kategorii nie zużywa limitu przydziału z innej kategorii. Na przykład nazwana jednostka usługi może wykorzystać cały przyznany jej ujednolicony limit dla interfejsów API harmonogramu zadań, nie wpływając przy tym na dostępny ujednolicony limit dla interfejsów API platformy. To rozdzielenie zapewnia, że zadania o dużym wolumenie w wyspecjalizowanych obszarach API nie wpływają na ogólne operacje API, i umożliwia bardziej przewidywalne mechanizmy ograniczania przepustowości dla różnych typów żądań.

Egzekwowanie interfejsu API

Limit przydziału interfejsów API jest wymuszany dla poszczególnych tożsamości, co oznacza, że każdy użytkownik, jednostka usługi lub tożsamość zarządzana otrzymuje własną niezależną alokację przydziału. Limity przydziału nigdy nie są współdzielone między tożsamościami, a wszystkie interfejsy API Fabric objęte tym limitem korzystają ze wspólnej puli limitu skojarzonej z daną tożsamością.

W związku z tym użycie interfejsu API przez jedną tożsamość nie ma wpływu na żadną inną tożsamość. Na przykład intensywnie używana jednostka usługi może wyczerpać własny limit przydziału interfejsów API bez wpływu na limity przydziału innych użytkowników lub aplikacji.

Podobnie, jeśli tożsamość osiągnie swój limit przydziału i zostanie objęta ograniczaniem, to ograniczanie dotyczy tylko tej tożsamości, podczas gdy inne tożsamości nadal działają normalnie. Ta izolacja zapewnia bardziej przewidywalne i łatwiejsze do zarządzania korzystanie z interfejsu API w różnych obciążeniach roboczych.

Hierarchia egzekwowania limitów przydziału

Każde żądanie interfejsu API rozpoczyna się od tożsamości — konta użytkownika lub jednostki usługi. Gdy ta tożsamość wywołuje interfejs API Fabric, żądanie najpierw zużywa pojemność z udostępnionego limitu przydziału interfejsów API, który jest wymuszany na tożsamość, a nie na interfejs API. Ten limit działa jako scentralizowany mechanizm ograniczania przepustowości, współdzielony przez wszystkie uczestniczące interfejsy API, zapewniając, że jeden identyfikator nie może przekroczyć przydzielonego limitu szybkości żądań.

Po sprawdzeniu żądania pod kątem współdzielonego limitu przydziału interfejsów API stosowane są również limity ograniczania przepustowości specyficzne dla danego interfejsu API. Te limity są niezależne od udostępnionego limitu przydziału i mogą istnieć tylko dla niektórych interfejsów API. W związku z tym, aby żądanie mogło zostać pomyślnie przetworzone, musi spełniać zarówno limity interfejsów API na poziomie tożsamości, jak i wszystkie mające zastosowanie limity poszczególnych interfejsów API.

W praktyce współdzielony limit przydziału dla interfejsów API zapewnia spójny mechanizm ograniczania przepustowości we wszystkich interfejsach API, podczas gdy limity poszczególnych interfejsów API nadal chronią określone usługi wymagające dodatkowych zabezpieczeń. W związku z tym wywołanie interfejsu API może zostać ograniczone albo dlatego, że dana tożsamość wyczerpała swój współdzielony limit, albo dlatego, że osiągnęła limit konkretnego punktu końcowego interfejsu API.

Kluczowe pojęcia:

• Wymuszanie na podstawie tożsamości: limit jest monitorowany oddzielnie dla każdego użytkownika lub podmiotu usługi.
• Współdzielone przez interfejsy API: żądania do różnych interfejsów API korzystają z tej samej puli limitów interfejsów API.
• Dotyczy wyłącznie ograniczania szybkości: limit API kontroluje częstotliwość żądań, ale nie wpływa na autoryzację ani uprawnienia.
• Podwójne egzekwowanie limitów: przy każdym żądaniu sprawdzany jest zarówno współdzielony limit Quota dla interfejsów API, jak i wszelkie limity specyficzne dla danego interfejsu API.
• Obowiązuje najbardziej restrykcyjny limit: żądanie podlega ograniczeniu, gdy zostanie przekroczony limit współdzielonego przydziału lub obowiązujący limit właściwy dla danego interfejsu API.

Jak jest używany limit przydziału

Każde żądanie interfejsu API zużywa limit z zasobnika limitu interfejsów API tożsamości wywołującej. Wszystkie żądania wysyłane przez tę tożsamość wliczają się do tego samego współdzielonego limitu, niezależnie od tego, które API jest wywoływane.

Okno limitu i odnowienie

Limit API jest egzekwowany w stałym 60-sekundowym oknie czasowym. Pula limitu jest uzupełniana w całości po zakończeniu bieżącego okna. Limit nie odnawia się stopniowo w trakcie tego okna.

Przykład osi czasu

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.

Praktyczne implikacje

• Wysyłanie serii żądań na początku okna czasowego jest dozwolone, ale może skutkować ograniczeniem liczby żądań dla tej tożsamości przez pozostałą część tego okna.
• Równomierne dystrybuowanie żądań w ciągu 60 sekund pomaga uniknąć ograniczania przepustowości.
• Zawsze uwzględniaj nagłówek odpowiedzi Retry-After. Wskazuje, jak długo należy czekać przed ponowieniem próby wysłania żądania ograniczonego przez limit.

Szczegóły limitu szybkości według interfejsu API

Chociaż Microsoft Fabric zapewnia ujednolicone kategorie ograniczania przepustowości i pojęcia dotyczące przydziału współużytkowanego, rzeczywiste limity szybkości mogą się różnić w zależności od interfejsu API. Zawsze sprawdzaj sekcję Ograniczenia przepustowości dla interfejsu API, który wywołujesz.

Komunikat dotyczący ograniczania przepustowości

Gdy występuje ograniczanie przepustowości, Fabric zwraca kod stanu HTTP 429 (Zbyt wiele żądań). Fabric zwraca kod stanu 429 z dwóch odrębnych powodów, z których każda jest identyfikowana przez inną errorCode w treści odpowiedzi:

• Przekroczono limit szybkości (RequestBlocked)
• Przekroczono limit pojemności (CapacityLimitExceeded)

errorCode Sprawdź wartość w odpowiedzi, aby określić, który warunek wystąpił i jak reagować.

Przekroczono limit szybkości (RequestBlocked)

Gdy użytkownik wysyła wiele żądań przekraczających wstępnie określony limit w przedziale czasu, Fabric ogranicza dalsze żądania od tego użytkownika przez krótki czas.

W takim przypadku Fabric zwraca kod stanu HTTP 429 (zbyt wiele żądań) z nagłówkiem Retry-After HTTP w odpowiedzi, wskazując, ile sekund aplikacja wywołująca powinna czekać przed ponowieniu próby wywołania. Treść odpowiedzi używa kodu błędu RequestBlocked :

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

Po wyświetleniu tego błędu poczekaj na czas określony w nagłówku Retry-After przed ponowieniu próby żądania.

Poniższy zrzut ekranu przedstawia przykład odpowiedzi, sugerując, że użytkownik czeka 55 sekund przed ponowieniu próby wywołania.

Przekroczono limit pojemności (CapacityLimitExceeded)

Fabric zwraca również kod stanu HTTP 429 (zbyt wiele żądań), gdy pojemność Fabric organizacji przekroczyła limity. W przeciwieństwie do ograniczania liczby żądań to ograniczenie nie jest spowodowane liczbą wywołań interfejsu API wykonywanych przez konkretnego wywołującego. Zamiast tego dochodzi do tego, gdy moc obliczeniowa (jednostki pojemności) zużywana przez Twoją pojemność przekracza limity zakupionej jednostki SKU usługi Fabric. Treść odpowiedzi używa kodu błędu CapacityLimitExceeded :

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

Po wyświetleniu tego błędu spróbuj ponownie później wykonać żądanie. Ponieważ to ograniczanie zależy od całkowitego zużycia mocy obliczeniowej przez pojemność, a nie od częstotliwości wysyłania własnych żądań, natychmiastowe ponowienie próby raczej się nie powiedzie, dopóki zużycie mocy obliczeniowej tej pojemności nie wróci do poziomu mieszczącego się w limitach. Jeśli ten błąd występuje często, rozważ skalowanie w górę lub wszerz pojemności usługi Fabric. Aby uzyskać więcej informacji o jednostkach pojemności, jednostkach SKU i sposobie korzystania z pojemności Fabric, zobacz Planowanie rozmiaru pojemności.

Zagadnienia i ograniczenia

Każdy administrator usługi Fabric i każdy podstawowy publiczny interfejs API może podlegać ograniczaniu przepustowości.

Należy pamiętać o tych zagadnieniach podczas projektowania aplikacji wywołujących interfejsy API REST Fabric:

• Limity są egzekwowane dla tożsamości wywołującego i wywoływanego interfejsu API. Oddzielne tożsamości nie muszą współdzielić tego samego licznika żądań, ale każdy wywołujący nadal musi przestrzegać udokumentowanych limitów dla interfejsu API.
• Wiele limitów szybkości jest ocenianych w ciągu jednego okna. Jeśli przekroczysz limit, poczekaj na wartość Retry-After przed wysłaniem kolejnych żądań.
• Ograniczanie pojemności różni się od ograniczania szybkości żądań. CapacityLimitExceeded wskazuje, że pojemność usługi Fabric jest przeciążona, a nie to, że wywołujący przekroczył limit wywołań interfejsu API na minutę.
• Natychmiastowe ponowienie próby po wystąpieniu błędu ograniczenia przepustowości z powodu limitu pojemności prawdopodobnie się nie powiedzie. Użyj ograniczonej strategii ponawiania prób i sprawdź wykorzystanie pojemności, jeśli błąd będzie się powtarzać.
• W przypadku integracji o dużym wolumenie preferuj operacje listowania, zbiorcze lub wsadowe, gdy są dostępne, buforuj metadane, które zmieniają się rzadko, i rozkładaj żądania równomiernie w czasie.
• W przypadku interfejsów API obsługujących stronicowanie należy używać tokenów kontynuacji zamiast wielokrotnie wysyłać szerokie zapytania od samego początku.

Często zadawane pytania

Skąd mam wiedzieć, czy osiągnąłem limit API czy limit pojemności?

Sprawdź element errorCode w treści odpowiedzi 429. RequestBlocked oznacza, że szybkość żądań przekroczyła limity ograniczania przepustowości usługi. CapacityLimitExceeded oznacza, że zasoby obliczeniowe wykorzystane przez pojemność Fabric przekroczyły limity zakupionego SKU.

Kiedy mój limit się resetuje?

Wiele limitów interfejsu API REST usługi Fabric jest ocenianych w jednominutowych oknach. Jeśli odpowiedź zawiera Retry-After nagłówek, użyj tej wartości jako autorytatywnego czasu oczekiwania przed ponowną próbą.

Czy mogę sprawdzić pozostały limit przydziału interfejsu API przed złożeniem żądania?

Odpowiedzi interfejsu Fabric REST API nie udostępniają ogólnego licznika pozostałego limitu we wszystkich interfejsach API. Skompiluj klientów, aby mogli wykrywać 429 odpowiedzi, honorować Retry-Afteri zmniejszać wolumin żądań podczas ograniczania przepustowości.

Jak mogę zmniejszyć ryzyko ograniczenia przepustowości?

Używaj operacji zbiorczych i wsadowych, jeśli są dostępne, preferuj interfejsy API list zamiast wielu wywołań dotyczących pojedynczych zasobów, buforuj często wykorzystywane metadane i unikaj nagłych skoków ruchu. W przypadku utrzymującego się ograniczania przepustowości pojemności użyj aplikacji Microsoft Fabric Capacity Metrics, aby zidentyfikować przeciążone pojemności i obciążenia robocze.

Czy należy ponowić próbę co 429 odpowiedzi w taki sam sposób?

No. W przypadku RequestBlocked zaczekaj na nagłówek Retry-After, a następnie spróbuj ponownie z zastosowaniem ograniczonej strategii ponawiania. W przypadku CapacityLimitExceeded ponów próbę później, stosując wykładniczo wydłużane odstępy między próbami, i sprawdź stopień wykorzystania pojemności, jeśli problem nadal będzie występować.

Powiązana zawartość

• Korzystanie z interfejsów API REST usługi Microsoft Fabric
• Zakresy
• Rozwiązywanie problemów z interfejsami API REST Microsoft Fabric
• Planowanie rozmiaru pojemności
• Omówienie ograniczania wydajności Fabric
• Aplikacja Microsoft Fabric Capacity Metrics