Problembehandlung bei Microsoft Fabric-REST-APIs

Einleitung

Dieser Artikel hilft Ihnen, häufige Fehler zu verstehen und zu beheben, die von Microsoft Fabric-REST-APIs zurückgegeben werden. Es wird das standardfehlerformat erläutert, das vom Dienst verwendet wird, und enthält Anleitungen zum Auflösen der am häufigsten gefundenen HTTP-Statuscodes.

Grundlegendes zu Microsoft Fabric-Fehlerantworten

Wenn beim Verarbeiten einer Anforderung an die Microsoft Fabric-REST-API ein Fehler auftritt, gibt der Dienst ein Standardobjekt ErrorResponse im Antworttext zurück.

Bei der Problembehandlung erfassen und protokollieren Sie immer die requestIdAnforderung, da sie die Anforderung eindeutig identifiziert und beim Kontaktieren des Microsoft-Supports erforderlich ist. Die Anforderungs-ID ist sowohl im Antworttext als auch in den Antwortheadern verfügbar.

Wichtig

  • errorCode Werte sind stabil und vertragsbasiert.
  • Der lesbare message Text kann sich im Laufe der Zeit ändern und sollte nicht programmgesteuert analysiert werden.

ErrorResponse-Schema

Name Typ Description
errorCode string Ein stabiler Bezeichner für die Fehlerbedingung. Verwenden Sie diesen Wert bei der Implementierung der Fehlerbehandlungslogik.
message string Eine für Menschen lesbare Beschreibung des Fehlers.
moreDetails ErrorResponseDetails[] Optionale Liste zusätzlicher Fehlerdetails.
relatedResource ErrorRelatedResource Informationen zur Ressource, die dem Fehler zugeordnet ist, falls zutreffend.
requestId string Der eindeutige Bezeichner der fehlgeschlagenen Anforderung. Schließen Sie diesen Wert ein, wenn Sie sich an den Microsoft-Support wenden.

ErrorResponseDetails-Schema

Stellt zusätzlichen Kontext für komplexe Fehlerszenarien bereit.

Name Typ Description
errorCode string Ein stabiler Bezeichner, der die spezifischen Fehlerdetails beschreibt.
message string Eine für Menschen lesbare Erklärung des Fehlerdetails.
relatedResource ErrorRelatedResource Die Ressource, die diesem spezifischen Fehlerdetails zugeordnet ist.

ErrorbezogenesRessourcenSchema

Identifiziert die Ressource, die an dem Fehler beteiligt ist.

Name Typ Description
resourceId string Die ID der Ressource, die an dem Fehler beteiligt ist.
resourceType string Der Typ der Ressource (z. B. Arbeitsbereich, Element oder Kapazität).

Häufige HTTP-Fehlerszenarien

In den folgenden Abschnitten werden allgemeine HTTP-Statuscodes beschrieben, die von Microsoft Fabric-REST-APIs zurückgegeben werden, zusammen mit typischen Ursachen und empfohlenen Lösungen.

API gibt 401 zurück – Nicht autorisiert

Eine 401-Antwort gibt an, dass die Anforderung während der Authentifizierungs- oder Zugriffstokenüberprüfung fehlgeschlagen ist.

Häufige Grundursachen

Fehlercode Description Beschluss
TokenExpired Das Zugriffstoken ist abgelaufen. Erwerben Sie ein neues Zugriffstoken, und wiederholen Sie die Anforderung.
InsufficientScopes Das Zugriffstoken enthält nicht die erforderlichen Bereiche. Aktualisieren Sie die Anwendung so, dass die erforderlichen Bereiche gemäß der API-Spezifikation angefordert werden, oder aktualisieren Sie die Microsoft Entra Anwendungsregistrierung.

API gibt 403 – Verboten zurück.

Eine 403-Antwort gibt an, dass der Aufrufer authentifiziert ist, aber nicht über ausreichende Berechtigungen zum Ausführen des angeforderten Vorgangs für die Zielressource verfügt.

Häufige Grundursachen

Fehlercode Description Beschluss
InsufficientPrivileges Der Aufrufer verfügt nicht über die erforderlichen Berechtigungen für den Zugriff auf die Ressource. Bitten Sie einen Arbeitsbereichs- oder Ressourcenadministrator, dem aufrufenden Benutzer oder Dienstprinzipal ausreichende Berechtigungen zu erteilen.

API gibt 404 zurück – Nicht gefunden

Eine 404-Antwort gibt an, dass eine angeforderte oder referenzierte Ressource nicht vorhanden ist oder für den Aufrufer nicht zugänglich ist.

Hinweis

Einzelne APIs können zusätzliche API-spezifische Fehlercodes definieren. Verweisen Sie immer auf die API-Spezifikation für autoritative Details.

Häufige Grundursachen

Fehlercode Description Beschluss
WorkspaceNotFound Der angegebene Arbeitsbereich konnte nicht gefunden werden. Stellen Sie sicher, dass die richtige Arbeitsbereichsobjekt-ID angegeben wurde.
EntityNotFound Die angeforderte Ressource konnte nicht gefunden werden. Vergewissern Sie sich, dass die richtige Ressourcen-ID angegeben wurde. Die fehlende Entität wird im relatedResource Feld der Fehlerantwort identifiziert.

API gibt 429 zurück – zu viele Anforderungen

Eine 429-Antwort bedeutet, dass die Anfrage gedrosselt wurde. Microsoft Fabric gibt aus zwei unterschiedlichen Gründen einen 429-Statuscode zurück, der jeweils durch einen anderen errorCode Im Antworttext identifiziert wird.

Häufige Grundursachen

Fehlercode Description Beschluss
RequestBlocked Die Anforderungsrate hat die Drosselungsgrenzen des Dienstes überschritten. Warten Sie auf die in der Retry-After Kopfzeile angegebene Dauer, bevor Sie den Vorgang wiederholen. Siehe Ratenbegrenzung in Ihrer Anwendung handhaben.
CapacityLimitExceeded Die für Ihre Kapazität verbrauchten Recheneinheiten (Kapazitätseinheiten) haben die Grenzwerte der erworbenen Fabric-SKU überschritten. Versuchen Sie die Anforderung später erneut. Siehe Umgang mit der Kapazitätsdrosselung.

Ratenbegrenzung (RequestBlocked)

Ein RequestBlocked Fehler gibt an, dass die Anforderungsrate die Einschränkungsgrenzwerte des Diensts überschritten hat.

  • Die Drosselung wird pro Anruferidentität erzwungen.
  • Ratenlimits werden in der Regel über einminütige Fenster ausgewertet.

Informationen zur Wiederholungszeitplanung

Wenn die Rate begrenzt wird, werden Wiederholungsinformationen an zwei Stellen bereitgestellt:

  • Antworttext (message)
    Beispiel:
    "Request is blocked by the upstream service until: 12/24/2025 17:02:20 (UTC)"

  • Retry-After HTTP-Antwortheader
    Gibt die Anzahl der Sekunden an, die der Client warten muss, bevor der Vorgang erneut ausgeführt wird.

Bevorzugen Sie immer den Retry-After Header bei der Implementierung der Wiederholungslogik.

Ratenbegrenzung in Ihrer Anwendung handhaben

Anwendungen sollten:

  • Http 429-Antworten erkennen.
  • Analysieren und berücksichtigen Sie die Retry-After Kopfzeile.
  • Wenden Sie eine gebundene Wiederholungsrichtlinie an, z. B. exponentielles Backoff mit Jitter für Szenarien mit hoher Skalierung.
  • Vermeiden Sie endlose Wiederholungsschleifen.

Verringern der Wahrscheinlichkeit einer Zinsbegrenzung

  • Verwenden Sie Massen- und Batchvorgänge , wenn verfügbar.
  • Bevorzugen Sie Listen-APIs gegenüber wiederholten Einzelressourcenanforderungen.
  • Zwischenspeichern häufig zugegriffener Daten, insbesondere Metadaten, die sich selten ändern.
  • Vermeiden Sie Datenverkehrsbrüche , indem Sie Anforderungen gleichmäßig über die Zeit verteilen.

Kapazitätslimit überschritten (CapacityLimitExceeded)

Ein CapacityLimitExceeded-Fehler weist darauf hin, dass der auf Ihrer Kapazität verbrauchte Compute-Wert (Kapazitätseinheiten) die Grenzen der erworbenen Fabric-SKU überschritten hat. Im Gegensatz zur Ratenbegrenzung wird diese Drosselung nicht durch die Anzahl der API-Aufrufe verursacht, die ein bestimmter Aufrufer tätigt; sie spiegelt die gesamte verbrauchte Rechenkapazität über alle Workloads auf der Kapazität hinweg wider.

Beispiel für Antworttext:

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

Umgang mit der Kapazitätsdrosselung

Da diese Drosselung von der insgesamt auf Ihrer Kapazität verbrauchten Rechenleistung abhängt und nicht von Ihrer individuellen Anfragerate, ist der Header Retry-After hier nicht zutreffend, und ein sofortiger erneuter Versuch wird voraussichtlich keinen Erfolg haben, bis die Rechenauslastung der Kapazität wieder innerhalb ihrer Grenzwerte liegt. Anwendungen sollten:

  • Wiederholen Sie die Anforderung später mithilfe einer gebundenen Wiederholungsrichtlinie mit exponentiellem Backoff.
  • Wenn der Fehler weiterhin besteht, sollten Sie eine vertikale oder horizontale Skalierung Ihrer Fabric-Kapazität in Betracht ziehen.

Weitere Informationen zu Kapazitätseinheiten, SKUs und dazu, wie Fabric Kapazität verbraucht wird, finden Sie unter Planen der Kapazitätsgröße.

Zusammenfassung

Das Erstellen zuverlässiger Integrationen mit Microsoft Fabric-REST-APIs erfordert eine robuste Fehlerbehandlung und effiziente Anforderungsmuster. Indem Sie Fehlerantworten verstehen, Drosselungssignale berücksichtigen und Anforderungsmuster optimieren, können Sie robuste Anwendungen erstellen.

Verwandte Inhalte

Weitere Fragen oder Anleitungen zur Community finden Sie in der Microsoft Fabric Community

  • Last updated on