Udostępnij za pośrednictwem


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.

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ź:

Nieautoryzowana odpowiedź o błędzie

Następne kroki

Aby uzyskać więcej informacji na temat pracy z zasadami, zobacz: