Felhantering i API Management-principer
GÄLLER FÖR: Alla API Management-nivåer
Genom att tillhandahålla ett ProxyError objekt tillåter Azure API Management utgivare att svara på felvillkor som kan inträffa under bearbetningen av begäranden. Objektet ProxyError nås via kontexten . Egenskapen LastError och kan användas av principer i principavsnittet on-error . Den här artikeln innehåller en referens för felhanteringsfunktionerna i Azure API Management.
Felhantering i API Management
Principer i Azure API Management är indelade i inbound, backend, outboundoch on-error avsnitt som visas i följande exempel.
<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>
Under bearbetningen av en begäran körs inbyggda steg tillsammans med alla principer som finns i omfånget för begäran. Om ett fel inträffar hoppar bearbetningen omedelbart till principavsnittet on-error .
Principavsnittet on-error kan användas i valfritt omfång. API-utgivare kan konfigurera anpassade beteenden som att logga felet till händelsehubbar eller skapa ett nytt svar för att återgå till anroparen.
Kommentar
Avsnittet on-error finns inte i principer som standard. Om du vill lägga till avsnittet i on-error en princip bläddrar du till önskad princip i principredigeraren och lägger till den. Mer information om hur du konfigurerar principer finns i Principer i API Management.
Om det inte finns något on-error avsnitt får anropare 400 eller 500 HTTP-svarsmeddelanden om ett feltillstånd inträffar.
Principer som tillåts i on-error
Följande principer kan användas i principavsnittet on-error .
- Välja
- set-variable
- find-and-replace
- return-response
- set-header
- set-method
- set-status
- send-request
- send-one-way-request
- log-to-eventhub
- json-to-xml
- xml-to-json
- limit-concurrency
- mock-response
- Igen
- Spåra
LastError
När ett fel inträffar och kontrollen hoppar till on-error principavsnittet lagras felet i kontexten. Egenskapen LastError , som kan nås av principer i avsnittet on-error . LastError har följande egenskaper.
| Namn | Type | Beskrivning | Obligatoriskt |
|---|---|---|---|
Source |
sträng | Namnger elementet där felet inträffade. Kan vara antingen en princip eller ett inbyggt pipelinestegnamn. | Ja |
Reason |
sträng | Maskinanpassad felkod som kan användas vid felhantering. | Nej |
Message |
sträng | Beskrivning av fel som kan läsas av människor. | Ja |
Scope |
sträng | Namn på omfånget där felet inträffade och kan vara ett av "global", "product", "api" eller "operation" | Nej |
Section |
sträng | Avsnittsnamn där felet uppstod. Möjliga värden: "inkommande", "serverdel", "utgående" eller "on-error". | Nej |
Path |
sträng | Anger kapslad princip, till exempel "choose[3]/when[2]". | Nej |
PolicyId |
sträng | Värdet för id attributet, om det anges av kunden, för principen där felet inträffade |
Nej |
Dricks
Du kan komma åt statuskoden via kontext. Response.StatusCode.
Kommentar
Alla principer har ett valfritt id attribut som kan läggas till i principens rotelement. Om det här attributet finns i en princip när ett feltillstånd inträffar kan värdet för attributet hämtas med hjälp av context.LastError.PolicyId egenskapen .
Fördefinierade fel för inbyggda steg
Följande fel är fördefinierade för feltillstånd som kan inträffa under utvärderingen av inbyggda bearbetningssteg.
| Källa | Villkor | Anledning | Meddelande |
|---|---|---|---|
| konfiguration | Uri matchar inte något API eller någon åtgärd | OperationNotFound | Det går inte att matcha inkommande begäran till en åtgärd. |
| auktorisering | Prenumerationsnyckeln har inte angetts | SubscriptionKeyNotFound | Åtkomst nekad på grund av att prenumerationsnyckeln saknas. Se till att inkludera prenumerationsnyckeln när du gör begäranden till det här API:et. |
| auktorisering | Värdet för prenumerationsnyckeln är ogiltigt | SubscriptionKeyInvalid | Åtkomst nekad på grund av ogiltig prenumerationsnyckel. Se till att ange en giltig nyckel för en aktiv prenumeration. |
| Flera | Nedströmsanslutning (från en klient till en API Management-gateway) avbröts av klienten medan begäran var väntande | Klient Anslut ionFailure | Flera |
| Flera | Uppströmsanslutning (från en API Management-gateway till en serverdelstjänst) upprättades inte eller avbröts av serverdelen | BackendConnectionFailure | Flera |
| Flera | Körningsund undantag hade inträffat under utvärderingen av ett visst uttryck | ExpressionValueEvaluationFailure | Flera |
Fördefinierade fel för principer
Följande fel är fördefinierade för feltillstånd som kan inträffa under principutvärderingen.
| Källa | Villkor | Anledning | Meddelande |
|---|---|---|---|
| hastighetsgräns | Hastighetsgränsen har överskridits | RateLimitExceededed | Hastighetsgränsen har överskridits |
| kvot | Kvoten har överskridits | QuotaExceeded | Slut på kvot för samtalsvolym. Kvoten fylls på i xx:xx:xx. -or- Slut på bandbreddskvot. Kvoten fylls på i xx:xx:xx. |
| Jsonp | Värdet för motringningsparametern är ogiltigt (innehåller fel tecken) | CallbackParameterInvalid | Värdet för motringningsparametern {callback-parameter-name} är inte en giltig JavaScript-identifierare. |
| ip-filter | Det gick inte att parsa anroparens IP-adress från begäran | FailedToParseCallerIP | Det gick inte att upprätta IP-adressen för anroparen. Åtkomst nekad. |
| ip-filter | Anroparens IP-adress finns inte i listan över tillåtna | CallerIpNotAllowed | Anroparens IP-adress {ip-address} är inte tillåten. Åtkomst nekad. |
| ip-filter | Uppringarens IP-adress finns i en lista över blockerade | CallerIpBlocked | Anroparens IP-adress blockeras. Åtkomst nekad. |
| check-header | Obligatoriskt huvud visas inte eller så saknas värdet | HeaderNotFound | Det gick inte att hitta rubriken {header-name} i begäran. Åtkomst nekad. |
| check-header | Obligatoriskt huvud visas inte eller så saknas värdet | HeaderValueNotAllowed | Rubrik {header-name} värde för {header-value} tillåts inte. Åtkomst nekad. |
| validate-jwt | Jwt-token saknas i begäran | TokenNotPresent | JWT finns inte. |
| validate-jwt | Signaturverifieringen misslyckades | TokenSignatureInvalid | <meddelande från jwt-biblioteket>. Åtkomst nekad. |
| validate-jwt | Ogiltig målgrupp | TokenAudienceNotAllowed | <meddelande från jwt-biblioteket>. Åtkomst nekad. |
| validate-jwt | Ogiltig utfärdare | TokenIssuerNotAllowed | <meddelande från jwt-biblioteket>. Åtkomst nekad. |
| validate-jwt | Token har upphört att gälla | TokenExpired | <meddelande från jwt-biblioteket>. Åtkomst nekad. |
| validate-jwt | Signaturnyckeln löstes inte av ID | TokenSignatureKeyNotFound | <meddelande från jwt-biblioteket>. Åtkomst nekad. |
| validate-jwt | Nödvändiga anspråk saknas från token | TokenClaimNotFound | JWT-token saknar följande anspråk: <c1>, <c2>, ... Åtkomst nekad. |
| validate-jwt | Matchningsfel för anspråksvärden | TokenClaimValueNotAllowed | Anspråksvärdet {claim-name} för {claim-value} tillåts inte. Åtkomst nekad. |
| validate-jwt | Andra valideringsfel | JwtInvalid | <meddelande från jwt-biblioteket> |
| forward-request eller send-request | HTTP-svarsstatuskod och huvuden togs inte emot från serverdelen inom den konfigurerade tidsgränsen | Timeout | Flera |
Exempel
Ange en API-princip till:
<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>
och att skicka en obehörig begäran resulterar i följande svar:
Nästa steg
Mer information om hur du arbetar med principer finns i:
- Principer i API Management
- Transformera API:er
- Principreferens för en fullständig lista över principinstruktioner och deras inställningar
- Principexempel