Fehlerbehandlung bei API Management-Richtlinien
GILT FÜR: Alle API Management-Ebenen
Indem sie ein ProxyError
-Objekt bereitstellen, können Herausgeber mit Azure API Management auf Fehlerbedingungen reagieren, die bei der Verarbeitung von Anforderungen im Proxy auftreten können. Der Zugriff auf das Objekt ProxyError
erfolgt über die Eigenschaft context.LastError und kann von Richtlinien im Richtlinienabschnitt on-error
verwendet werden. Dieser Artikel dient als Referenz für die Fehlerbehandlungsfunktionen in Azure API Management.
Fehlerbehandlung in API Management
Die Richtlinien in Azure API Management sind in die Abschnitte inbound
, backend
, outbound
und on-error
unterteilt, wie im folgenden Beispiel gezeigt.
<policies>
<inbound>
<!-- statements to be applied to the request go here -->
</inbound>
<backend>
<!-- statements to be applied before the request is
forwarded to the backend service go here -->
</backend>
<outbound>
<!-- statements to be applied to the response go here -->
</outbound>
<on-error>
<!-- statements to be applied if there is an error
condition go here -->
</on-error>
</policies>
Während der Verarbeitung einer Anforderung werden integrierte Schritte zusammen mit Richtlinien ausgeführt, die im Bereich der Anforderung liegen. Wenn ein Fehler auftritt, wechselt die Verarbeitung sofort zum Richtlinienabschnitt on-error
.
Der Richtlinienabschnitt on-error
kann in jedem Bereich verwendet werden. Zudem können API-Herausgeber benutzerdefiniertes Verhalten konfigurieren, wie etwa das Protokollieren des Fehlers in Event Hubs oder das Erstellen einer neuen Antwort, die an den Aufrufer zurückgegeben werden soll.
Hinweis
Der Abschnitt on-error
ist standardmäßig nicht in den Richtlinien vorhanden. Um einer Richtlinie den Abschnitt on-error
hinzuzufügen, navigieren Sie im Richtlinien-Editor zur gewünschten Richtlinie, und fügen Sie sie hinzu. Weitere Informationen zum Konfigurieren von Richtlinien finden Sie unter Richtlinien in API Management.
Falls kein Abschnitt on-error
vorhanden sein sollte, erhält der Aufrufer bei einer auftretenden Fehlerbedingung die HTTP-Antwortnachricht 400 oder 500.
Im On-error-Abschnitt zulässige Richtlinien
Die folgenden Richtlinien können im Richtlinienabschnitt on-error
verwendet werden.
- choose
- set-variable
- find-and-replace
- return-response
- set-header
- set-method
- set-status
- send-request
- send-one-way-request
- log-to-eventhub
- json-to-xml
- xml-to-json
- limit-concurrency
- mock-response
- retry
- trace
lastError
Wenn ein Fehler auftritt und das Steuerelement zum Richtlinienabschnitt on-error
wechselt, wird der Fehler in der Eigenschaft context.LastError gespeichert. Diese kann von Richtlinien im Abschnitt on-error
aufgerufen werden. LastError weist folgende Eigenschaften auf.
Name | Typ | Beschreibung | Erforderlich |
---|---|---|---|
Source |
Zeichenfolge | Benennt das Element, in dem der Fehler aufgetreten ist. Kann entweder der Schrittname einer Richtlinie oder einer integrierten Pipeline sein. | Ja |
Reason |
Zeichenfolge | Computerfreundlicher Fehlercode, der bei der Fehlerbehandlung verwendet werden kann. | Nein |
Message |
Zeichenfolge | Für Menschen lesbare Fehlerbeschreibung. | Ja |
Scope |
Zeichenfolge | Name des Bereichs, in dem der Fehler aufgetreten ist. Kann einer der Werte „global“, „product“, „api“ oder „operation“ sein. | Nein |
Section |
Zeichenfolge | Name des Abschnitts, in dem der Fehler aufgetreten ist. Mögliche Werte: „inbound“, „backend“, „outbound“ oder „on-error“. | Nein |
Path |
Zeichenfolge | Gibt geschachtelte Richtlinien an, z.B. „choose[3]/when[2]“. | Nein |
PolicyId |
Zeichenfolge | Sofern vom Kunden festgelegt, der Wert des Attributs id in der Richtlinie, in der der Fehler aufgetreten ist. |
Nein |
Tipp
Über „context.Response.StatusCode“ können Sie auf den Statuscode zugreifen.
Hinweis
Alle Richtlinien verfügen über ein optionales id
-Attribut, das dem Stammelement der Richtlinie hinzugefügt werden kann. Wenn dieses Attribut beim Auftreten einer Fehlerbedingung in einer Richtlinie vorhanden ist, kann der Wert des Attributs mithilfe der Eigenschaft context.LastError.PolicyId
abgerufen werden.
Vordefinierte Fehler für integrierte Schritte
Die folgenden Fehler sind für Fehlerbedingungen, die während der Auswertung der integrierten Verarbeitungsschritte auftreten können, vordefiniert.
`Source` | Bedingung | `Reason` | `Message` |
---|---|---|---|
Konfiguration | URI entspricht keiner API bzw. keinem Vorgang | OperationNotFound | Es kann keine eingehende Anforderung für einen Vorgang gefunden werden. |
authorization | Abonnementschlüssel nicht bereitgestellt | SubscriptionKeyNotFound | Der Zugriff wurde aufgrund eines fehlenden Abonnementschlüssels verweigert. Stellen Sie sicher, dass der Abonnementschlüssel beim Senden von Anforderungen an diese API enthalten ist. |
authorization | Wert des Abonnementschlüssels ungültig | SubscriptionKeyInvalid | Der Zugriff wurde aufgrund eines ungültigen Abonnementschlüssels verweigert. Stellen Sie sicher, dass Sie einen gültigen Schlüssel für ein aktives Abonnement bereitstellen. |
Mehrere | Die Downstreamverbindung (von einem Client zu einem API Management-Gateway) wurde vom Client getrennt, während die Anforderung noch ausstand. | ClientConnectionFailure | Mehrere |
Mehrere | Die Upstreamverbindung (von einem API Management-Gateway zu einem Back-End-Dienst) wurde nicht hergestellt oder wurde vom Back-End abgebrochen. | BackendConnectionFailure | Mehrere |
Mehrere | Während der Auswertung eines bestimmten Ausdrucks ist eine Laufzeitausnahme aufgetreten. | ExpressionValueEvaluationFailure | Mehrere |
Vordefinierte Fehler für Richtlinien
Die folgenden Fehler sind für Fehlerbedingungen vordefiniert, die bei der Richtlinienauswertung auftreten können.
`Source` | Bedingung | `Reason` | `Message` |
---|---|---|---|
rate-limit | Übertragungsratenlimit überschritten | RateLimitExceeded | Das Übertragungsratenlimit wurde überschritten. |
quota | Kontingent überschritten | QuotaExceeded | Das Aufrufvolumenkontigent ist erschöpft. Das Kontingent wird in xx:xx:xx aufgefüllt. –oder– Das Bandbreitenkontingent ist erschöpft. Das Kontingent wird in xx:xx:xx aufgefüllt. |
jsonp | Wert des Rückrufparameters ungültig (enthält falsche Zeichen) | CallbackParameterInvalid | Der Wert des Rückrufparameters {callback-parameter-name} ist kein gültiger JavaScript-Bezeichner. |
ip-filter | Fehler beim Analysieren der IP-Adresse des Aufrufers aus Anforderung | FailedToParseCallerIP | Fehler beim Ermitteln der IP-Adresse des Aufrufers. Der Zugriff wurde verweigert. |
ip-filter | IP-Adresse des Aufrufers nicht in Liste zulässiger IP-Adressen | CallerIpNotAllowed | Die IP-Adresse des Aufrufers {Ip-Adresse} ist nicht zulässig. Der Zugriff wurde verweigert. |
ip-filter | IP-Adresse des Aufrufers in Liste blockierter IP-Adressen | CallerIpBlocked | Die IP-Adresse des Aufrufers ist blockiert. Der Zugriff wurde verweigert. |
check-header | Erforderlicher Header nicht angegeben oder Wert fehlt | HeaderNotFound | Header {header-name} wurde nicht in der Anforderung gefunden. Der Zugriff wurde verweigert. |
check-header | Erforderlicher Header nicht angegeben oder Wert fehlt | HeaderValueNotAllowed | Der Wert {header-value} des Headers {header-name} ist nicht zulässig. Der Zugriff wurde verweigert. |
validate-jwt | JWT fehlt in Anforderung | TokenNotPresent | JWT ist nicht vorhanden. |
validate-jwt | Fehler bei der Signaturüberprüfung | TokenSignatureInvalid | <Meldung der JWT-Bibliothek>. Der Zugriff wurde verweigert. |
validate-jwt | Ungültige Zielgruppe | TokenAudienceNotAllowed | <Meldung der JWT-Bibliothek>. Der Zugriff wurde verweigert. |
validate-jwt | Ungültiger Aussteller | TokenIssuerNotAllowed | <Meldung der JWT-Bibliothek>. Der Zugriff wurde verweigert. |
validate-jwt | Token abgelaufen | TokenExpired | <Meldung der JWT-Bibliothek>. Der Zugriff wurde verweigert. |
validate-jwt | Signaturschlüssel wurde nicht von ID aufgelöst | TokenSignatureKeyNotFound | <Meldung der JWT-Bibliothek>. Der Zugriff wurde verweigert. |
validate-jwt | Erforderliche Ansprüche aus Token fehlen | TokenClaimNotFound | JWT token is missing the following claims: <c1>, <c2>, … (Dem JWT-Token fehlen die folgenden Ansprüche: c1, c2, ...) Der Zugriff wurde verweigert. |
validate-jwt | Konflikt bei Anspruchswerten | TokenClaimValueNotAllowed | Der Wert {claim-value} des Anspruchs {claim-name} ist nicht zulässig. Der Zugriff wurde verweigert. |
validate-jwt | Andere Überprüfungsfehler | JwtInvalid | <Meldung der JWT-Bibliothek> |
forward-request oder send-request | Der Statuscode und die Header der HTTP-Antwort wurden nicht innerhalb des konfigurierten Timeouts vom Back-End empfangen. | Timeout | Mehrere |
Beispiel
Das Festlegen einer API-Richtlinie auf:
<policies>
<inbound>
<base />
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
</outbound>
<on-error>
<set-header name="ErrorSource" exists-action="override">
<value>@(context.LastError.Source)</value>
</set-header>
<set-header name="ErrorReason" exists-action="override">
<value>@(context.LastError.Reason)</value>
</set-header>
<set-header name="ErrorMessage" exists-action="override">
<value>@(context.LastError.Message)</value>
</set-header>
<set-header name="ErrorScope" exists-action="override">
<value>@(context.LastError.Scope)</value>
</set-header>
<set-header name="ErrorSection" exists-action="override">
<value>@(context.LastError.Section)</value>
</set-header>
<set-header name="ErrorPath" exists-action="override">
<value>@(context.LastError.Path)</value>
</set-header>
<set-header name="ErrorPolicyId" exists-action="override">
<value>@(context.LastError.PolicyId)</value>
</set-header>
<set-header name="ErrorStatusCode" exists-action="override">
<value>@(context.Response.StatusCode.ToString())</value>
</set-header>
<base />
</on-error>
</policies>
und das Senden einer nicht autorisierten Anforderung führt zu der folgenden Antwort:
Nächste Schritte
Weitere Informationen zur Verwendung von Richtlinien finden Sie unter:
- Richtlinien in Azure API Management
- Transform and protect your API (Transformieren und Schützen von APIs)
- Unter Richtlinien für die API-Verwaltung finden Sie eine komplette Liste der Richtlinienanweisungen und der zugehörigen Einstellungen.
- API Management-Richtlinienbeispiele