Zpracování chyb v zásadách služby API Management
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.
- Zvolte
- set-variable
- find-and-replace
- return-response
- set-header
- set-method
- set-status
- send-request
- odeslání jednosměrné žádosti
- log-to-eventhub
- json-to-xml
- xml-to-json
- limit-concurrency
- mock-response
- Opakovat
- Trasování
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ěď:
Další kroky
Další informace o práci se zásadami najdete tady:
- Zásady ve službě API Management
- Transformovat rozhraní API
- Referenční informace o zásadách pro úplný seznam prohlášení o zásadách a jejich nastavení
- Ukázky zásad