Rozwiązywanie problemów z interfejsami REST API usługi Microsoft Fabric

Wprowadzenie

Ten artykuł pomaga zrozumieć typowe błędy zwracane przez interfejsy API REST usługi Microsoft Fabric i rozwiązywać problemy z nimi. Wyjaśnia standardowy format błędu używany przez usługę i zawiera wskazówki dotyczące rozwiązywania najczęściej spotykanych kodów stanu HTTP.

Omówienie odpowiedzi na błędy usługi Microsoft Fabric

Gdy wystąpi błąd podczas przetwarzania żądania do interfejsu API REST usługi Microsoft Fabric, usługa zwraca standardowy ErrorResponse obiekt w treści odpowiedzi.

Podczas rozwiązywania problemów zawsze przechwytuj i rejestruj element requestId, ponieważ jednoznacznie identyfikuje żądanie i jest wymagany podczas kontaktowania się z pomocą techniczną firmy Microsoft. Identyfikator żądania jest dostępny zarówno w treści odpowiedzi, jak i w nagłówkach odpowiedzi.

Ważny

  • errorCode wartości są stabilne i oparte na kontraktach.
  • Tekst czytelny dla message człowieka może ulec zmianie w czasie i nie powinien być analizowany programowo.

Schemat błędu odpowiedzi

Name Typ Description
errorCode string Stabilny identyfikator warunku błędu. Użyj tej wartości podczas implementowania logiki obsługi błędów.
message string Czytelny dla człowieka opis błędu.
moreDetails ErrorResponseDetails[] Opcjonalna lista dodatkowych szczegółów błędu.
relatedResource ErrorRelatedResource Informacje o zasobie skojarzonym z błędem, jeśli ma to zastosowanie.
requestId string Unikatowy identyfikator żądania, który zakończył się niepowodzeniem. Uwzględnij tę wartość podczas kontaktowania się z pomocą techniczną firmy Microsoft.

schemat ErrorResponseDetails

Zapewnia dodatkowy kontekst dla złożonych scenariuszy błędów.

Name Typ Description
errorCode string Stabilny identyfikator opisujący szczegóły określonego błędu.
message string Czytelne dla człowieka wyjaśnienie szczegółów błędu.
relatedResource ErrorRelatedResource Zasób skojarzony z tym konkretnym szczegółem błędu.

"ErrorRelatedResource" schema

Identyfikuje zasób związany z błędem.

Name Typ Description
resourceId string Identyfikator zasobu zaangażowanego w błąd.
resourceType string Typ zasobu (na przykład obszar roboczy, element lub pojemność).

Typowe scenariusze błędów HTTP

W poniższych sekcjach opisano typowe kody stanu HTTP zwracane przez interfejsy API REST usługi Microsoft Fabric oraz typowe główne przyczyny i zalecane rozwiązania.

Interfejs API zwraca błąd 401 — Brak autoryzacji

Odpowiedź 401 wskazuje, że żądanie nie powiodło się podczas uwierzytelniania lub weryfikacji tokenu dostępu.

Typowe główne przyczyny

Kod błędu Description Rezolucja
TokenExpired Token dostępu wygasł. Uzyskaj nowy token dostępu i ponów próbę żądania.
InsufficientScopes Token dostępu nie zawiera wymaganych zakresów. Zaktualizuj aplikację, aby zażądała wymaganych zakresów zgodnie ze specyfikacją interfejsu API lub zaktualizuj rejestrację aplikacji Microsoft Entra.

Interfejs API zwraca kod 403 – Zabronione

Odpowiedź 403 wskazuje, że obiekt wywołujący jest uwierzytelniony, ale nie ma wystarczających uprawnień do wykonania żądanej operacji na zasobie docelowym.

Typowe główne przyczyny

Kod błędu Description Rezolucja
InsufficientPrivileges Obiekt wywołujący nie ma wymaganych uprawnień dostępu do zasobu. Poproś administratora obszaru roboczego lub administratora zasobów o udzielenie wystarczających uprawnień dla wywołującego użytkownika lub jednostki usługi.

Interfejs API zwraca 404 – Nie znaleziono

Odpowiedź 404 wskazuje, że żądany lub przywołyany zasób nie istnieje lub nie jest dostępny dla wywołującego.

Uwaga

Poszczególne interfejsy API mogą definiować dodatkowe kody błędów specyficzne dla interfejsu API. Zawsze zapoznaj się ze specyfikacją interfejsu API, aby uzyskać szczegółowe informacje autorytatywne.

Typowe główne przyczyny

Kod błędu Description Rezolucja
WorkspaceNotFound Nie można odnaleźć określonego obszaru roboczego. Sprawdź, czy podano prawidłowy identyfikator obiektu obszaru roboczego.
EntityNotFound Nie można odnaleźć żądanego zasobu. Upewnij się, że podano prawidłowy identyfikator zasobu. Brakująca jednostka jest identyfikowana w relatedResource polu odpowiedzi o błędzie.

Interfejs API zwraca kod 429 — zbyt wiele żądań

Odpowiedź 429 oznacza, że żądanie zostało ograniczone z powodu limitu szybkości. Microsoft 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.

Typowe główne przyczyny

Kod błędu Description Rezolucja
RequestBlocked Szybkość żądań przekroczyła limity ograniczania przepustowości usługi. Przed ponowieniu próby poczekaj czas trwania określony w nagłówku Retry-After . Zobacz Obsługa ograniczania szybkości w aplikacji.
CapacityLimitExceeded Moc obliczeniowa (jednostki wydajności) wykorzystana w ramach Twojej pojemności przekroczyła limity zakupionej jednostki SKU usługi Fabric. Proszę ponowić żądanie później. Zobacz Obsługiwanie ograniczania przepustowości.

Ograniczanie szybkości (RequestBlocked)

Błąd RequestBlocked wskazuje, że szybkość żądania przekroczyła limity ograniczania przepustowości usługi.

  • Ograniczanie przepływności jest stosowane na podstawie tożsamości dzwoniącego.
  • Limity przepustowości są zwykle oceniane w okresach minutowych.

Informacje o chronometrażu ponawiania prób

W przypadku ograniczania szybkości informacje o ponawianiu są udostępniane w dwóch lokalizacjach:

  • Treść odpowiedzi (message)
    Przykład:
    "Request is blocked by the upstream service until: 12/24/2025 17:02:20 (UTC)"

  • Retry-After Nagłówek odpowiedzi HTTP
    Określa liczbę sekund, przez które klient musi czekać przed ponowną próbą.

Zawsze preferuj Retry-After nagłówek podczas implementowania logiki ponawiania prób.

Obsługa ograniczania szybkości w aplikacji

Aplikacje powinny:

  • Wykrywanie odpowiedzi HTTP 429.
  • Przeanalizuj i uhonoruj Retry-After nagłówek.
  • Zastosuj ograniczone zasady ponawiania, takie jak wycofywanie wykładnicze z zakłóceniami w scenariuszach o dużej skali.
  • Unikaj nieskończonych pętli ponawiania prób.

Zmniejsza prawdopodobieństwo ograniczenia szybkości

  • Używaj operacji zbiorczych i wsadowych, jeśli są dostępne.
  • Preferuj interfejsy API listy zamiast powtarzających się żądań pojedynczego zasobu.
  • Buforowanie często używanych danych, zwłaszcza metadanych, które zmieniają się rzadko.
  • Unikaj wzrostów ruchu , dystrybuując żądania równomiernie w czasie.

Przekroczono limit pojemności (CapacityLimitExceeded)

Błąd CapacityLimitExceeded wskazuje, że moc obliczeniowa (jednostki pojemności) zużyta w ramach Twojej pojemności przekroczyła limity zakupionego SKU usługi Fabric. W przeciwieństwie do limitowania szybkości to dławienie nie jest spowodowane liczbą wywołań interfejsu API wykonywanych przez konkretnego wywołującego; odzwierciedla ono całkowite zużycie mocy obliczeniowej we wszystkich obciążeniach na tej pojemności.

Przykładowa treść odpowiedzi:

"Your organization's Fabric compute capacity has exceeded its limits. Try again later."

Obsługa ograniczania przepustowości

Ponieważ to ograniczanie zależy od całkowitego zużycia zasobów obliczeniowych w Twojej jednostce pojemności, a nie od indywidualnego tempa żądań, nagłówek Retry-After nie ma zastosowania, a natychmiastowe ponowienie próby prawdopodobnie nie zakończy się powodzeniem, dopóki zużycie zasobów obliczeniowych tej jednostki pojemności nie spadnie z powrotem do poziomu mieszczącego się w jej limitach. Aplikacje powinny:

  • Ponów żądanie później, stosując ograniczoną strategię ponawiania z wykładniczo rosnącym odstępem między próbami.
  • Jeśli błąd nadal występuje, 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.

Podsumowanie

Tworzenie niezawodnych integracji z interfejsami API REST usługi Microsoft Fabric wymaga niezawodnej obsługi błędów i wydajnych wzorców żądań. Zrozumienie odpowiedzi na błędy, honorowanie sygnałów ograniczania przepustowości i optymalizowanie wzorców żądań umożliwia tworzenie odpornych aplikacji.

Treści powiązane

Aby uzyskać dodatkowe pytania lub wskazówki społeczności, zobacz Społeczność usługi Microsoft Fabric

  • Last updated on