Foutafhandeling in API-beheerbeleid

VAN TOEPASSING OP: Alle API Management-niveaus

Door een ProxyError-object op te geven, kunnen uitgevers Azure API Management reageren op foutvoorwaarden, die kunnen optreden tijdens het verwerken van aanvragen. Het ProxyError object wordt geopend via de context.LastError eigenschap. Beleidsregels in de on-error beleidssectie kunnen het ProxyError object gebruiken. 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 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 beleidsectie kan op elk niveau worden gebruikt. API-uitgevers kunnen aangepast gedrag configureren, zoals het vastleggen van de fout voor Azure 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.

Toegestane beleid bij een fout

De volgende beleidsregels kunnen worden gebruikt in de on-error beleidssectie.

LaatsteFout

Wanneer er een fout optreedt en de regeling naar de on-error beleidssectie springt, wordt de fout opgeslagen in de eigenschap context.LastError. Beleidsregels in de on-error sectie hebben toegang tot context.LastError. LastError heeft de volgende eigenschappen.

Naam Typologie Beschrijving Vereist
Source tekenreeks Naam van het element waar de fout is opgetreden. Dit kan een beleid of een ingebouwde pijplijnstapnaam zijn. 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. Nee
Section tekenreeks Sectienaam waar de fout is opgetreden. Mogelijke waarden: inbound, backend, , outboundof on-error. Nee
Path tekenreeks Geeft de geneste beleidsstructuur aan, bijvoorbeeld choose[3]\\when[2]. Meerdere exemplaren van een genest beleid worden geïndexeerd vanaf 1. Nee
PolicyId tekenreeks Waarde van het id kenmerk, indien opgegeven door de klant, op het beleid waar de fout is opgetreden Nee

Aanbeveling

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, kunt u de waarde van het kenmerk ophalen 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 OperatieNietGevonden Kan de binnenkomende aanvraag niet koppelen aan een bewerking.
autorisatie Abonnementssleutel niet opgegeven SubscriptionSleutelNietGevonden (SubscriptionKeyNotFound) Toegang geweigerd vanwege ontbrekende abonnementssleutel. Zorg ervoor dat u de abonnementssleutel opneemt bij het indienen van aanvragen voor deze API.
autorisatie De abonnementssleutelwaarde is ongeldig SubscriptionKeyInvalid Toegang geweigerd vanwege een ongeldige abonnementssleutel. Zorg ervoor dat u een geldige sleutel opgeeft voor een actief abonnement.
veelvoud De client heeft een downstreamverbinding (van een client naar een API Management-gateway) afgebroken terwijl de aanvraag in behandeling was Klantverbindingfout veelvoud
veelvoud De back-end is afgebroken of kon geen upstream-verbinding tot stand brengen (van een API Management-gateway naar een back-endservice) Back-end Verbindingsfout veelvoud
veelvoud Runtime-uitzondering is opgetreden tijdens de evaluatie van een bepaalde expressie Mislukt bij evaluatie van expressiewaarde veelvoud

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 Verzoeklimiet overschreden Frequentielimiet wordt overschreden
quotum Quotum overschreden Quota overschreden Volumequotum voor gesprekken overschreden. Het quotum wordt aangevuld in xx:xx:xx. Geen bandbreedtequotum meer. Het quotum wordt aangevuld in xx:xx:xx.
jsonp Parameterwaarde voor callback is ongeldig (bevat verkeerde tekens) CallbackparameterOngeldig 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 Kon Oproep IP-adres Niet Parseren 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 Oproeper-IP niet toegestaan 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 Oproeper-IP-geblokkeerd Het IP-adres van de beller wordt geblokkeerd. Toegang geweigerd.
controlekop Vereiste header wordt niet weergegeven of de waarde ontbreekt HeaderNietGevonden De header {header-name} is niet gevonden in de aanvraag. Toegang geweigerd.
controlekop Vereiste header wordt niet weergegeven of de waarde ontbreekt HeaderwaardeNietToegestaan De header {header-name} met de waarde {header-value} is niet toegestaan. Toegang geweigerd.
JWT valideren JSON Web Token (JWT) ontbreekt in aanvraag TokenNietAanwezig JWT niet aanwezig.
JWT valideren Validatie van handtekening is mislukt Tokenhandtekening ongeldig <bericht uit jwt-bibliotheek>. Toegang geweigerd.
JWT valideren Ongeldige doelgroep Tokenpubliek Niet Toegestaan <bericht uit jwt-bibliotheek>. Toegang geweigerd.
JWT valideren Ongeldige uitgever TokenverstrekkerNietToegestaan <bericht uit jwt-bibliotheek>. Toegang geweigerd.
JWT valideren Token is verlopen Token Verlopen <bericht uit jwt-bibliotheek>. Toegang geweigerd.
JWT valideren Sleutel voor digitale handtekening kon niet worden opgelost via ID TokenSignatureSleutelNietGevonden <bericht uit jwt-bibliotheek>. Toegang geweigerd.
JWT valideren Vereiste claims ontbreken in het token TokenClaimNietGevonden JWT ontbreekt de volgende claims: <c1>, <c2>, ... Toegang geweigerd.
JWT valideren Claimwaarden komen niet overeen TokenClaimWaardeNietToegestaan Claim {claim-name} de waarde van {claim-value} is niet toegestaan. Toegang geweigerd.
JWT valideren Andere validatiefouten JwtInvalid <bericht uit jwt-bibliotheek>
doorstuurverzoek of verzendverzoek Http-antwoordstatuscode en headers zijn niet ontvangen van de back-end binnen de geconfigureerde time-out Onderbreking veelvoud

Voorbeeld

Stel een API-beleid in op de volgende waarde:

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

Het verzenden van een niet-geautoriseerde aanvraag resulteert in het volgende antwoord:

Schermopname van het antwoord op het voorbeeld, dat een foutbericht bevat.

Gerelateerde inhoud

Zie voor meer informatie over het werken met beleid:

  • Last updated on