Zpracování chyb v zásadách služby API Management

  • Článek

PLATÍ PRO: Všechny úrovně služby API Management

Díky poskytnutí objektu ProxyError umožňuje Azure API Management vydavatelům reagovat na chybové stavy, ke kterým může dojít během zpracování požadavků. K ProxyError objektu se přistupuje prostřednictvím kontextu. Vlastnost LastError a je možné ji použít zásadami v on-error části zásady. Tento článek obsahuje referenční informace o možnostech zpracování chyb ve službě Azure API Management.

Zpracování chyb ve službě API Management

Zásady ve službě Azure API Management jsou rozdělené na inboundoddíly a backendoutboundon-error oddíly, jak je znázorněno v následujícím příkladu.

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

Během zpracování požadavku se spustí předdefinované kroky spolu se všemi zásadami, které jsou v rozsahu požadavku. Pokud dojde k chybě, zpracování okamžitě přeskočí do on-error části zásady. Oddíl on-error zásad lze použít v libovolném rozsahu. Vydavatelé rozhraní API můžou nakonfigurovat vlastní chování, jako je protokolování chyby do center událostí nebo vytvoření nové odpovědi, která se vrátí volajícímu.

Poznámka:

Oddíl on-error ve výchozím nastavení není v zásadách. Pokud chcete přidat on-error oddíl do zásady, přejděte v editoru zásad na požadovanou zásadu a přidejte ji. Další informace o konfiguraci zásad najdete v tématu Zásady ve službě API Management.

Pokud neexistuje žádný on-error oddíl, volající obdrží 400 nebo 500 zpráv odpovědi HTTP, pokud dojde k chybovému stavu.

Zásady povolené v zapnuté chybě

V části zásady je možné použít on-error následující zásady.

LastError

Pokud dojde k chybě a řízení přeskočí do oddílu on-error zásad, chyba se uloží v kontextu. Vlastnost LastError , ke které můžou přistupovat zásady v on-error této části. LastError má následující vlastnosti.

Name Typ Popis Povinní účastníci
Source string Pojmenuje prvek, ve kterém došlo k chybě. Může to být zásada nebo předdefinovaný název kroku kanálu. Ano
Reason string Strojově přívětivý kód chyby, který se dá použít při zpracování chyb. No
Message string Popis chyby čitelné člověkem Ano
Scope string Název oboru, ve kterém došlo k chybě, a může se jednat o jeden z "globálních", "product", "api" nebo "operation" No
Section string Název oddílu, kde došlo k chybě. Možné hodnoty: "příchozí", "backend", "odchozí" nebo "on-error". No
Path string Určuje vnořené zásady, například "choose[3]/when[2]". No
PolicyId string Hodnota atributu id , pokud je určena zákazníkem, v zásadách, kde došlo k chybě No

Tip

Ke stavovém kódu se dostanete prostřednictvím kontextu. Response.StatusCode.

Poznámka:

Všechny zásady mají volitelný id atribut, který lze přidat do kořenového prvku zásady. Pokud se tento atribut nachází v zásadě v případě chybového stavu, lze hodnotu atributu context.LastError.PolicyId načíst pomocí vlastnosti.

Předdefinované chyby pro předdefinované kroky

Následující chyby jsou předdefinované pro chybové stavy, ke kterým může dojít během vyhodnocení předdefinovaných kroků zpracování.

Source Podmínka Důvod Zpráva
konfigurace Identifikátor URI se neshoduje s žádným rozhraním API nebo operací. OperationNotFound Příchozí požadavek nelze shodovat s operací.
autorizace Nezadávaná klíč předplatného SubscriptionKeyNotFound Přístup byl odepřen kvůli chybějícímu klíči předplatného. Při provádění požadavků na toto rozhraní API nezapomeňte zahrnout klíč předplatného.
autorizace Hodnota klíče předplatného je neplatná. SubscriptionKeyInvalid Přístup byl odepřen kvůli neplatnému klíči předplatného. Nezapomeňte zadat platný klíč pro aktivní předplatné.
vícenásobné Podřízené připojení (z klienta k bráně služby API Management) bylo klientem přerušeno během čekání na vyřízení požadavku. Klient Připojení ionFailure vícenásobné
vícenásobné Nadřazené připojení (z brány služby API Management k back-endové službě) nebylo vytvořeno nebo bylo přerušeno back-endem. Chyba připojení back-endu vícenásobné
vícenásobné Během vyhodnocení konkrétního výrazu došlo k výjimce za běhu. ExpressionValueEvaluationFailure vícenásobné

Předdefinované chyby pro zásady

Následující chyby jsou předdefinované pro chybové stavy, ke kterým může dojít během vyhodnocování zásad.

Source Podmínka Důvod Zpráva
limit rychlosti Překročení limitu rychlosti RateLimitExceededed Překročení limitu rychlosti
Kvóta Překročení kvóty QuotaExceeded Překročení kvóty volání. Kvóta bude doplněna v xx:xx:xx. -nebo- Mimo kvótu šířky pásma. Kvóta bude doplněna v xx:xx:xx.
Jsonp Hodnota parametru zpětného volání je neplatná (obsahuje nesprávné znaky) CallbackParameterInvalid Hodnota parametru zpětného volání {callback-parameter-name} není platný identifikátor JavaScriptu.
ip-filter Nepodařilo se analyzovat IP adresu volajícího z požadavku. FailedToParseCallerIP Nepodařilo se navázat IP adresu volajícího. Přístup se odepřel.
ip-filter IP adresa volajícího není v seznamu povolených CallerIpNotAllowed IP adresa volajícího {ip-adresa} není povolená. Přístup se odepřel.
ip-filter IP adresa volajícího je v seznamu blokovaných CallerIpBlocked IP adresa volajícího je zablokovaná. Přístup se odepřel.
check-header Chybí požadovaná hlavička nebo chybí hodnota. HeaderNotFound Hlavička {header-name} nebyla v požadavku nalezena. Přístup se odepřel.
check-header Chybí požadovaná hlavička nebo chybí hodnota. HeaderValueNotAllowed Hodnota záhlaví {header-name} pro {header-value} není povolená. Přístup se odepřel.
validate-jwt V požadavku chybí token Jwt TokenNotPresent JWT neexistuje.
validate-jwt Ověření podpisu se nezdařilo. TokenSignatureInvalid <zpráva z knihovny> jwt. Přístup se odepřel.
validate-jwt Neplatná cílová skupina TokenAudienceNotAllowed <zpráva z knihovny> jwt. Přístup se odepřel.
validate-jwt Neplatný vystavitel TokenIssuerNotAllowed <zpráva z knihovny> jwt. Přístup se odepřel.
validate-jwt Vypršela platnost tokenu. TokenExpired <zpráva z knihovny> jwt. Přístup se odepřel.
validate-jwt Klíč podpisu se nepřeložil podle ID. TokenSignatureKeyNotFound <zpráva z knihovny> jwt. Přístup se odepřel.
validate-jwt V tokenu chybí požadované deklarace identity. TokenClaimNotFound Token JWT chybí následující deklarace identity: <c1>, <c2>, ... Přístup se odepřel.
validate-jwt Neshoda hodnot deklarací identity TokenClaimValueNotAllowed Deklarací identity {název_deklarace} není povolená hodnota {claim-value}. Přístup se odepřel.
validate-jwt Další chyby ověřování JwtInvalid <message from jwt library>
forward-request or send-request Stavový kód odpovědi HTTP a hlavičky nebyly přijaty z back-endu v rámci nakonfigurovaného časového limitu. Timeout vícenásobné

Příklad

Nastavení zásad rozhraní 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>

a odeslání neoprávněného požadavku způsobí následující odpověď:

Neautorizovaná chybová odpověď

Další kroky

Další informace o práci se zásadami najdete tady: