Fout bij het verwerken van API Management-beleid
VAN TOEPASSING OP: Alle API Management-lagen
Door een ProxyError object op te geven, kunnen uitgevers van Azure API Management reageren op foutvoorwaarden, die kunnen optreden tijdens het verwerken van aanvragen. Het ProxyError object wordt geopend via de context. De eigenschap LastError en kan worden gebruikt door beleidsregels in de on-error beleidssectie. Dit artikel bevat een overzicht van de mogelijkheden voor foutafhandeling in Azure API Management.
Foutafhandeling in API Management
Beleidsregels in Azure API Management zijn onderverdeeld ininbound, backenden outboundon-error secties, zoals wordt weergegeven in het volgende voorbeeld.
<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>
Tijdens de verwerking van een aanvraag worden ingebouwde stappen uitgevoerd, samen met alle beleidsregels die binnen het bereik van de aanvraag vallen. Als er een fout optreedt, gaat de verwerking onmiddellijk naar de on-error beleidssectie.
De on-error beleidssectie kan op elk bereik worden gebruikt. API-uitgevers kunnen aangepast gedrag configureren, zoals het vastleggen van de fout bij Event Hubs of het maken van een nieuw antwoord om terug te keren naar de aanroeper.
Notitie
De on-error sectie is niet standaard aanwezig in beleidsregels. Als u de on-error sectie aan een beleid wilt toevoegen, bladert u naar het gewenste beleid in de beleidseditor en voegt u deze toe. Zie Beleid in API Management voor meer informatie over het configureren van beleidsregels.
Als er geen on-error sectie is, ontvangen bellers 400 of 500 HTTP-antwoordberichten als er een foutvoorwaarde optreedt.
Beleid dat is toegestaan bij fout
De volgende beleidsregels kunnen worden gebruikt in de on-error beleidssectie.
- Kies
- set-variable
- zoeken en vervangen
- return-response
- set-header
- set-method
- set-status
- send-request
- send-one-way-request
- log-to-eventhub
- json-to-xml
- xml-to-json
- limiet-gelijktijdigheid
- mock-response
- Opnieuw
- Trace
LastError
Wanneer er een fout optreedt en het besturingselement naar de on-error beleidssectie springt, wordt de fout opgeslagen in de context. De eigenschap LastError , die toegankelijk is voor beleidsregels in de on-error sectie. LastError heeft de volgende eigenschappen.
| Name | Type | Beschrijving | Vereist |
|---|---|---|---|
Source |
tekenreeks | Noemt het element waar de fout is opgetreden. Dit kan een beleid zijn of een ingebouwde naam voor de pijplijnstap. | Ja |
Reason |
tekenreeks | Machinevriendelijke foutcode, die kan worden gebruikt bij foutafhandeling. | Nee |
Message |
tekenreeks | Beschrijving van door mensen leesbare fouten. | Ja |
Scope |
tekenreeks | Naam van het bereik waar de fout is opgetreden en kan een van de 'global', 'product', 'api' of 'operation' zijn | Nee |
Section |
tekenreeks | Sectienaam waar de fout is opgetreden. Mogelijke waarden: 'inkomend', 'back-end', 'uitgaand' of 'on-error'. | Nee |
Path |
tekenreeks | Hiermee geeft u geneste beleid op, bijvoorbeeld 'choose[3]/when[2]'. | Nee |
PolicyId |
tekenreeks | Waarde van het id kenmerk, indien opgegeven door de klant, op het beleid waar de fout is opgetreden |
Nee |
Tip
U hebt toegang tot de statuscode via context. Response.StatusCode.
Notitie
Alle beleidsregels hebben een optioneel id kenmerk dat kan worden toegevoegd aan het hoofdelement van het beleid. Als dit kenmerk aanwezig is in een beleid wanneer er een foutvoorwaarde optreedt, kan de waarde van het kenmerk worden opgehaald met behulp van de context.LastError.PolicyId eigenschap.
Vooraf gedefinieerde fouten voor ingebouwde stappen
De volgende fouten zijn vooraf gedefinieerd voor foutvoorwaarden die kunnen optreden tijdens de evaluatie van ingebouwde verwerkingsstappen.
| Bron | Conditie | Reden | Bericht |
|---|---|---|---|
| configuratie | Uri komt niet overeen met een API of bewerking | OperationNotFound | Kan de binnenkomende aanvraag niet koppelen aan een bewerking. |
| autorisatie | Abonnementssleutel niet opgegeven | SubscriptionKeyNotFound | Toegang geweigerd vanwege ontbrekende abonnementssleutel. Zorg ervoor dat u de abonnementssleutel opneemt bij het indienen van aanvragen voor deze API. |
| autorisatie | De waarde van de abonnementssleutel is ongeldig | SubscriptionKeyInvalid | Toegang geweigerd vanwege een ongeldige abonnementssleutel. Zorg ervoor dat u een geldige sleutel opgeeft voor een actief abonnement. |
| Meerdere | Downstreamverbinding (van een client naar een API Management-gateway) is afgebroken door de client terwijl de aanvraag in behandeling was | Client Verbinding maken ionFailure | Meerdere |
| Meerdere | Upstream-verbinding (van een API Management-gateway naar een back-endservice) is niet tot stand gebracht of is afgebroken door de back-end | BackendConnectionFailure | Meerdere |
| Meerdere | Runtime-uitzondering is opgetreden tijdens de evaluatie van een bepaalde expressie | ExpressionValueEvaluationFailure | Meerdere |
Vooraf gedefinieerde fouten voor beleid
De volgende fouten zijn vooraf gedefinieerd voor foutvoorwaarden die kunnen optreden tijdens de beleidsevaluatie.
| Bron | Conditie | Reden | Bericht |
|---|---|---|---|
| frequentielimiet | Snelheidslimiet overschreden | RateLimitExceeded | Frequentielimiet wordt overschreden |
| quota | Quotum overschreden | QuotaExceeded | Volumequotum buiten bereik. Het quotum wordt aangevuld in xx:xx:xx. -of- Onvoldoende bandbreedtequotum. Het quotum wordt aangevuld in xx:xx:xx. |
| jsonp | Parameterwaarde voor callback is ongeldig (bevat verkeerde tekens) | CallbackParameterInvalid | De waarde van de callback-parameter {callback-parameter-name} is geen geldige JavaScript-id. |
| ip-filter | Kan het IP-adres van de beller niet parseren vanuit aanvraag | FailedToParseCallerIP | Kan het IP-adres voor de beller niet tot stand brengen. Toegang geweigerd. |
| ip-filter | Het IP-adres van de beller staat niet in de lijst met toegestane adressen | CallerIpNotAllowed | Het IP-adres van de beller {ip-address} is niet toegestaan. Toegang geweigerd. |
| ip-filter | Het IP-adres van de beller bevindt zich in de lijst met geblokkeerde adressen | CallerIpBlocked | Het IP-adres van de beller wordt geblokkeerd. Toegang geweigerd. |
| check-header | Vereiste header wordt niet weergegeven of de waarde ontbreekt | HeaderNotFound | De header {header-name} is niet gevonden in de aanvraag. Toegang geweigerd. |
| check-header | Vereiste header wordt niet weergegeven of de waarde ontbreekt | HeaderValueNotAllowed | De waarde {header-name} van {header-value} is niet toegestaan. Toegang geweigerd. |
| validate-jwt | Jwt-token ontbreekt in aanvraag | TokenNotPresent | JWT niet aanwezig. |
| validate-jwt | Validatie van handtekening is mislukt | TokenSignatureInvalid | <bericht uit jwt-bibliotheek>. Toegang geweigerd. |
| validate-jwt | Ongeldige doelgroep | TokenAudienceNotAllowed | <bericht uit jwt-bibliotheek>. Toegang geweigerd. |
| validate-jwt | Ongeldige verlener | TokenIssuerNotAllowed | <bericht uit jwt-bibliotheek>. Toegang geweigerd. |
| validate-jwt | Token is verlopen | TokenExpired | <bericht uit jwt-bibliotheek>. Toegang geweigerd. |
| validate-jwt | Handtekeningsleutel is niet omgezet door id | TokenSignatureKeyNotFound | <bericht uit jwt-bibliotheek>. Toegang geweigerd. |
| validate-jwt | Vereiste claims ontbreken in het token | TokenClaimNotFound | JWT-token ontbreekt de volgende claims: <c1>, <c2>, ... Toegang geweigerd. |
| validate-jwt | Claimwaarden komen niet overeen | TokenClaimValueNotAllowed | Claim {claim-name} waarde van {claim-value} is niet toegestaan. Toegang geweigerd. |
| validate-jwt | Andere validatiefouten | JwtInvalid | <bericht uit jwt-bibliotheek> |
| forward-request of send-request | Http-antwoordstatuscode en headers zijn niet ontvangen van de back-end binnen de geconfigureerde time-out | Timeout | Meerdere |
Opmerking
Een API-beleid instellen op:
<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>
en het verzenden van een niet-geautoriseerde aanvraag resulteert in het volgende antwoord:
Volgende stappen
Zie voor meer informatie over het werken met beleid:
- Beleid in API Management
- API's transformeren
- Beleidsreferentie voor een volledige lijst met beleidsinstructies en hun instellingen
- Voorbeelden van beleid