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 sznurek Nazywa element, w którym wystąpił błąd. Może to być zasada lub wbudowana nazwa kroku potoku. Tak
Reason sznurek Przyjazny dla maszyny kod błędu, który może być używany w obsłudze błędów. Nie.
Message sznurek Opis błędu czytelnego dla człowieka. Tak
Scope sznurek Nazwa zakresu, w którym wystąpił błąd. Nie.
Section sznurek Nazwa sekcji, w której wystąpił błąd. Możliwe wartości: "przychodzące", "backend", "outbound" lub "on-error". Nie.
Path sznurek Określa hierarchię zasad zagnieżdżonych, na przykład "choose[3]\when[2]". Wiele wystąpień zagnieżdżonych zasad jest indeksowanych z 1. Nie.
PolicyId sznurek 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ą OperacjaNieZnaleziona Nie można dopasować żądania przychodzącego do operacji.
autoryzacja Nie podano klucza subskrypcji KluczSubskrypcjiNieZnaleziony 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 NieprawidłowyKluczSubskrypcji 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 AwariaPołączeniaKlienta 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 Błąd połączenia z backendem wiele
wiele Wystąpił wyjątek środowiska uruchomieniowego podczas obliczania określonego wyrażenia Niepowodzenie oceny wartości wyrażenia 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 Przekroczono limit częstotliwości Przekroczono limit szybkości
limit przydziału Przekroczono limit przydziału Przekroczono limit 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.
Filtr IP Nie można przeanalizować adresu IP obiektu wywołującego z żądania Nie udało się przeanalizować adresu IP dzwoniącego Nie można ustanowić adresu IP dla elementu wywołującego. Odmowa dostępu.
Filtr IP Adres IP elementu wywołującego nie znajduje się na liście dozwolonych AdresIPDzwoniącegoNiedozwolony Adres IP obiektu wywołującego {adres IP} jest niedozwolony. Odmowa dostępu.
Filtr IP Adres IP elementu wywołującego znajduje się na liście zablokowanych AdresIPDzwoniącegoZablokowany Adres IP wywołującego jest zablokowany. Odmowa dostępu.
sprawdź nagłówek Brak wymaganego nagłówka lub brak wartości NagłówekNieZnaleziony Nie można odnaleźć nagłówka {header-name} w żądaniu. Odmowa dostępu.
sprawdź nagłówek Brak wymaganego nagłówka lub brak wartości WartośćNagłówkaNiedozwolona Wartość nagłówka {header-name} {header-value} jest niedozwolona. Odmowa dostępu.
weryfikuj JWT Brak tokenu JWT w żądaniu TokenNotPresent JWT nie istnieje.
weryfikuj JWT Sprawdzanie poprawności podpisu nie powiodło się NieprawidłowyPodpisTokena <komunikat z biblioteki> jwt. Odmowa dostępu.
weryfikuj JWT Nieprawidłowi odbiorcy TokenAudienceNotAllowed <komunikat z biblioteki> jwt. Odmowa dostępu.
weryfikuj JWT Nieprawidłowy wystawca WystawcaTokenuNiedozwolony <komunikat z biblioteki> jwt. Odmowa dostępu.
weryfikuj JWT Token wygasł Token wygasł <komunikat z biblioteki> jwt. Odmowa dostępu.
weryfikuj JWT Klucz podpisu nie został rozpoznany przez identyfikator TokenSignatureKeyNotFound <komunikat z biblioteki> jwt. Odmowa dostępu.
weryfikuj JWT Brak wymaganych oświadczeń w tokenie Nie znaleziono roszczenia tokenu Brak następujących oświadczeń JWT: <c1>, <c2>, ... Odmowa dostępu.
weryfikuj JWT Niezgodność wartości oświadczeń NiedozwolonaWartośćŻądaniaTokenu Oświadczenie {claim-name} wartość {claim-value} jest niedozwolona. Odmowa dostępu.
weryfikuj 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 Przerwa czasowa 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

Powiązana zawartość

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