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

  • Článek
  • 4 min ke čtení

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

Zpracování chyb v API Management

Zásady v Azure API Management jsou rozdělené na inboundoddíly , backend, outbounda on-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í žádosti se předdefinované kroky provádějí spolu se všemi zásadami, které jsou v rozsahu žádosti. Pokud dojde k chybě, zpracování okamžitě přejde do on-error části zásad. 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 centra událostí nebo vytvoření nové odpovědi, která se vrátí volajícímu.

Poznámka

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

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

Zásady povolené v chybě

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

LastError

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

Název Typ Popis Povinné
Source řetězec Pojmenuje prvek, u kterého došlo k chybě. Může to být buď zásada, nebo předdefinovaný název kroku kanálu. Yes
Reason řetězec Strojově popisný kód chyby, který se dá použít při zpracování chyb. No
Message řetězec Popis chyby čitelné pro člověka Yes
Scope řetězec Název oboru, ve kterém došlo k chybě, a může být jedním z "globálních", "produktů", "api" nebo "operace". No
Section řetězec Název oddílu, kde došlo k chybě Možné hodnoty: "příchozí", "back-end", "odchozí" nebo "on-error". No
Path řetězec Určuje vnořené zásady, například "choose[3]/when[2]". No
PolicyId řetězec Hodnota atributu id , pokud je zadán zákazníkem, v zásadě, kde došlo k chybě No

Tip

Stavový kód můžete získat přístup 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ě, pokud dojde k chybovému 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é podmínky, ke kterým může dojít během vyhodnocení předdefinovaných kroků zpracování.

Zdroj Podmínka Důvod Zpráva
konfigurace Identifikátor URI neodpovídá žádnému rozhraní API ani operaci. OperationNotFound Příchozí požadavek nelze shodovat s operací.
autorizace Klíč předplatného se nezadá 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é.
multiple Podřízené připojení (z klienta k bráně API Management) bylo přerušeno klientem během čekání na vyřízení požadavku. ClientConnectionFailure multiple
multiple Nadřazené připojení (z brány API Management k back-endové službě) nebylo vytvořeno nebo bylo přerušeno back-endem. Chyba připojení back-endu multiple
multiple Během vyhodnocení konkrétního výrazu došlo k výjimce modulu runtime. ExpressionValueEvaluationFailure multiple

Předdefinované chyby pro zásady

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

Zdroj Podmínka Důvod Zpráva
limit rychlosti Překročení limitu rychlosti RateLimitExceeded Překročení limitu rychlosti
kvóta Překročení kvóty KvótaExceeded Překročení kvóty volání. Kvóta bude doplněna v xx:xx:xx. -or- 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 Nepovedlo 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-address} 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 hodnota HeaderNotFound Hlavička {header-name} nebyla v požadavku nalezena. Přístup se odepřel.
check-header Chybí požadovaná hlavička nebo hodnota HeaderValueNotAllowed Hlavička {header-name} hodnoty {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 Deklarace hodnoty {claim-name} {claim-value} není povolená. Přístup se odepřel.
validate-jwt Další chyby ověření JwtInvalid <zpráva z knihovny jwt>
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. Časový limit multiple

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í neautorizované žádosti způsobí následující odpověď:

Unauthorized error response

Další kroky

Další informace o práci se zásadami najdete v tématech: