Obsługa błędów w zasadach usługi API Management
DOTYCZY: Wszystkie warstwy usługi API Management
ProxyError Udostępniając obiekt, usługa Azure API Management umożliwia wydawcom reagowanie na warunki błędów, które mogą wystąpić podczas przetwarzania żądań. Obiekt ProxyError jest uzyskiwany za pośrednictwem kontekstu. Właściwość LastError i może być używana przez zasady w on-error sekcji zasad. Ten artykuł zawiera informacje dotyczące możliwości obsługi błędów w usłudze Azure API Management.
Obsługa błędów w usłudze API Management
Zasady w usłudze Azure API Management są podzielone na inboundsekcje , backend, outboundi on-error , jak pokazano w poniższym przykładzie.
<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>
Podczas przetwarzania żądania wykonywane są wbudowane kroki wraz z wszelkimi zasadami, które są w zakresie żądania. Jeśli wystąpi błąd, przetwarzanie natychmiast przejdzie do on-error sekcji zasad.
Sekcja on-error zasad może być używana w dowolnym zakresie. Wydawcy interfejsu API mogą konfigurować niestandardowe zachowanie, takie jak rejestrowanie błędu w centrach zdarzeń lub tworzenie nowej odpowiedzi w celu powrotu do obiektu wywołującego.
Uwaga
Sekcja on-error nie jest domyślnie obecna w zasadach. Aby dodać sekcję on-error do zasad, przejdź do żądanych zasad w edytorze zasad i dodaj ją. Aby uzyskać więcej informacji na temat konfigurowania zasad, zobacz Zasady w usłudze API Management.
Jeśli nie ma on-error sekcji, osoby wywołujące otrzymają 400 lub 500 komunikatów odpowiedzi HTTP, jeśli wystąpi warunek błędu.
Zasady dozwolone w przypadku błędów
Poniższe zasady można użyć w on-error sekcji zasad.
- Wybierz
- set-variable
- find-and-replace
- return-response
- set-header
- set-method
- set-status
- send-request
- send-one-way-request
- log-to-eventhub
- Plik json-to-xml
- xml-to-json
- limit współbieżność
- pozorna odpowiedź
- Ponów próbę
- Śledzenia
LastError
Gdy wystąpi błąd i kontrolka przejdzie do on-error sekcji zasad, błąd jest przechowywany w kontekście. Właściwość LastError , do której można uzyskać dostęp za pomocą zasad w on-error sekcji . LastError ma następujące właściwości.
| Nazwisko | Pisz | Opis | Wymagania |
|---|---|---|---|
Source |
string | Nazywa element, w którym wystąpił błąd. Może to być zasada lub wbudowana nazwa kroku potoku. | Tak |
Reason |
string | Przyjazny dla maszyny kod błędu, który może być używany w obsłudze błędów. | Nie. |
Message |
string | Opis błędu czytelnego dla człowieka. | Tak |
Scope |
string | Nazwa zakresu, w którym wystąpił błąd i może być jedną z "globalnych", "product", "api" lub "operation" | Nie. |
Section |
string | Nazwa sekcji, w której wystąpił błąd. Możliwe wartości: "przychodzące", "backend", "outbound" lub "on-error". | Nie. |
Path |
string | Określa zasady zagnieżdżone, na przykład "wybierz[3]/when[2]". | Nie. |
PolicyId |
string | Wartość atrybutu id , jeśli zostanie określony przez klienta, w zasadach, w których wystąpił błąd |
Nie. |
Napiwek
Możesz uzyskać dostęp do kodu stanu za pomocą kontekstu. Response.StatusCode.
Uwaga
Wszystkie zasady mają opcjonalny id atrybut, który można dodać do elementu głównego zasad. Jeśli ten atrybut znajduje się w zasadach w przypadku wystąpienia warunku błędu, wartość atrybutu context.LastError.PolicyId można pobrać przy użyciu właściwości .
Wstępnie zdefiniowane błędy dla wbudowanych kroków
Następujące błędy są wstępnie zdefiniowane dla warunków błędów, które mogą wystąpić podczas oceny wbudowanych kroków przetwarzania.
| Źródło | Stan | Przyczyna | Komunikat |
|---|---|---|---|
| konfiguracja | Identyfikator URI nie jest zgodny z żadnym interfejsem API ani operacją | OperationNotFound | Nie można dopasować żądania przychodzącego do operacji. |
| autoryzacja | Nie podano klucza subskrypcji | SubscriptionKeyNotFound | Odmowa dostępu z powodu braku klucza subskrypcji. Pamiętaj, aby uwzględnić klucz subskrypcji podczas podejmowania żądań do tego interfejsu API. |
| autoryzacja | Wartość klucza subskrypcji jest nieprawidłowa | SubscriptionKeyInvalid | Odmowa dostępu z powodu nieprawidłowego klucza subskrypcji. Pamiętaj, aby podać prawidłowy klucz dla aktywnej subskrypcji. |
| wiele | Połączenie podrzędne (z klienta do bramy usługi API Management) zostało przerwane przez klienta, gdy żądanie było oczekujące | Klient Połączenie ionFailure | wiele |
| wiele | Połączenie nadrzędne (z bramy usługi API Management do usługi zaplecza) nie zostało ustanowione lub zostało przerwane przez zaplecze | BackendConnectionFailure | wiele |
| wiele | Wystąpił wyjątek środowiska uruchomieniowego podczas obliczania określonego wyrażenia | ExpressionValueEvaluationFailure | wiele |
Wstępnie zdefiniowane błędy zasad
Następujące błędy są wstępnie zdefiniowane dla warunków błędów, które mogą wystąpić podczas oceny zasad.
| Źródło | Stan | Przyczyna | Komunikat |
|---|---|---|---|
| limit szybkości | Przekroczono limit szybkości | RateLimitExceeded | Przekroczono limit szybkości |
| limit przydziału | Przekroczono limit przydziału | QuotaExceeded | Poza limitem woluminu wywołania. Limit przydziału zostanie uzupełniony w xx:xx:xx. -or- Brak limitu przydziału przepustowości. Limit przydziału zostanie uzupełniony w xx:xx:xx. |
| Jsonp | Wartość parametru wywołania zwrotnego jest nieprawidłowa (zawiera nieprawidłowe znaki) | CallbackParameterInvalid | Wartość parametru wywołania zwrotnego {callback-parameter-name} nie jest prawidłowym identyfikatorem języka JavaScript. |
| ip-filter | Nie można przeanalizować adresu IP obiektu wywołującego z żądania | FailedToParseCallerIP | Nie można ustanowić adresu IP dla elementu wywołującego. Odmowa dostępu. |
| ip-filter | Adres IP elementu wywołującego nie znajduje się na liście dozwolonych | CallerIpNotAllowed | Adres IP obiektu wywołującego {adres IP} jest niedozwolony. Odmowa dostępu. |
| ip-filter | Adres IP elementu wywołującego znajduje się na liście zablokowanych | CallerIpBlocked | Adres IP wywołującego jest zablokowany. Odmowa dostępu. |
| check-header | Brak wymaganego nagłówka lub brak wartości | HeaderNotFound | Nie można odnaleźć nagłówka {header-name} w żądaniu. Odmowa dostępu. |
| check-header | Brak wymaganego nagłówka lub brak wartości | HeaderValueNotAllowed | Wartość nagłówka {header-name} {header-value} jest niedozwolona. Odmowa dostępu. |
| validate-jwt | Brak tokenu Jwt w żądaniu | TokenNotPresent | JWT nie istnieje. |
| validate-jwt | Sprawdzanie poprawności podpisu nie powiodło się | TokenSignatureInvalid | <komunikat z biblioteki> jwt. Odmowa dostępu. |
| validate-jwt | Nieprawidłowi odbiorcy | TokenAudienceNotAllowed | <komunikat z biblioteki> jwt. Odmowa dostępu. |
| validate-jwt | Nieprawidłowy wystawca | TokenIssuerNotAllowed | <komunikat z biblioteki> jwt. Odmowa dostępu. |
| validate-jwt | Token wygasł | TokenExpired | <komunikat z biblioteki> jwt. Odmowa dostępu. |
| validate-jwt | Klucz podpisu nie został rozpoznany przez identyfikator | TokenSignatureKeyNotFound | <komunikat z biblioteki> jwt. Odmowa dostępu. |
| validate-jwt | Brak wymaganych oświadczeń w tokenie | TokenClaimNotFound | Brak tokenu JWT: <c1>, <c2>, ... Odmowa dostępu. |
| validate-jwt | Niezgodność wartości oświadczeń | TokenClaimValueNotAllowed | Oświadczenie {claim-name} wartość {claim-value} jest niedozwolona. Odmowa dostępu. |
| validate-jwt | Inne błędy walidacji | JwtInvalid | <komunikat z biblioteki jwt> |
| prześlij żądanie dalej lub wyślij żądanie | Kod stanu odpowiedzi HTTP i nagłówki nie zostały odebrane z zaplecza w ramach skonfigurowanego limitu czasu | Timeout | wiele |
Przykład
Ustawianie zasad interfejsu API na:
<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>
wysłanie nieautoryzowanego żądania spowoduje następującą odpowiedź:
Następne kroki
Aby uzyskać więcej informacji na temat pracy z zasadami, zobacz:
- Zasady w usłudze API Management
- Przekształcanie interfejsów API
- Dokumentacja zasad dla pełnej listy instrukcji zasad i ich ustawień
- Przykłady zasad