Hibakezelés az API Management-szabályzatokban

A KÖVETKEZŐRE VONATKOZIK: Minden API Management-szint

Egy objektum biztosításával ProxyError az Azure API Management lehetővé teszi, hogy a közzétevők válaszoljanak a kérések feldolgozása során esetlegesen előforduló hibafeltételekre. Az ProxyError objektum a környezeten keresztül érhető el. LastError tulajdonság, amelyet a on-error szabályzatszakasz szabályzatai használhatnak. Ez a cikk az Azure API Management hibakezelési képességeire vonatkozó hivatkozást tartalmaz.

Hibakezelés az API Managementben

Az Azure API Management szabályzatai az alábbi példában láthatóak szerint szakaszokra inboundbackendoutboundés on-error szakaszokra vannak osztva.

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

A kérés feldolgozása során a rendszer végrehajtja a beépített lépéseket a kérés hatókörébe tartozó szabályzatokkal együtt. Hiba esetén a feldolgozás azonnal a on-error szabályzatszakaszra ugrik. A on-error szabályzatszakasz bármely hatókörben használható. Az API-közzétevők egyéni viselkedést konfigurálhatnak, például naplózhatják a hibát az eseményközpontokban, vagy új választ hozhatnak létre a hívónak való visszatéréshez.

Feljegyzés

A on-error szakasz alapértelmezés szerint nem szerepel a szabályzatokban. Ha hozzá szeretné adni a on-error szakaszt egy szabályzathoz, keresse meg a kívánt szabályzatot a szabályzatszerkesztőben, és adja hozzá. A szabályzatok konfigurálásáról további információt az API Management szabályzatai című témakörben talál.

Ha nincs on-error szakasz, a hívók 400 vagy 500 HTTP-válaszüzenetet kapnak, ha hibaállapot lép fel.

Hiba esetén engedélyezett szabályzatok

A szabályzatszakaszban az on-error alábbi szabályzatok használhatók.

• választ
• set-variable
• keresés és csere
• visszatérési válasz
• set-header
• beállítási-módszer
• beállítás állapota
• küldési kérelem
• egyirányú kérés küldése
• naplózás az eseményközpontba
• json-to-xml
• xml-to-json
• korlát-egyidejűség
• mock-response
• Újra
• nyom

Utolsó hiba

Ha hiba történik, és a vezérlés a on-error szabályzatszakaszra ugrik, a hiba a környezetben lesz tárolva . LastError tulajdonság, amely a szakaszban lévő on-error szabályzatok által érhető el. A LastError a következő tulajdonságokkal rendelkezik.

Név	Típus	Leírás	Kötelező
Source	húr	Annak az elemnek a neve, ahol a hiba történt. Lehet szabályzat vagy beépített folyamatlépés neve.	Igen
Reason	húr	Gépbarát hibakód, amely a hibakezelésben használható.	Nem
Message	húr	Emberi olvasásra alkalmas hibaleírás.	Igen
Scope	húr	Annak a hatókörnek a neve, ahol a hiba történt.	Nem
Section	húr	A szakasz neve, ahol hiba történt. Lehetséges értékek: "bejövő", "háttérrendszer", "kimenő" vagy "hiba".	Nem
Path	húr	Beágyazott szabályzathierarchiát ad meg, például "choose[3]\when[2]". A beágyazott szabályzatok több példánya indexelve van 1-ből.	Nem
PolicyId	húr	id Az attribútum értéke, ha az ügyfél megadja, azon a szabályzaton, ahol hiba történt	Nem

Tipp.

Az állapotkódot a környezeten keresztül érheti el. Response.StatusCode.

Feljegyzés

Minden házirend rendelkezik egy választható id attribútummal, amely hozzáadható a szabályzat gyökéreleméhez. Ha ez az attribútum hibaállapot esetén jelen van egy szabályzatban, az attribútum értéke lekérhető a context.LastError.PolicyId tulajdonság használatával.

Előre definiált hibák a beépített lépésekhez

A beépített feldolgozási lépések kiértékelése során előforduló hibafeltételek esetében a következő hibák előre vannak definiálva.

Forrás	Feltétel	Ok	Üzenet
konfiguráció	Az Uri nem egyezik semmilyen API-val vagy művelettel	MűveletNemTalálható	A bejövő kérés nem egyezik egy művelettel.
engedélyezés	Az előfizetési kulcs nincs megadva	ElőfizetésiKulcsNemTalálható	A hozzáférés a hiányzó előfizetési kulcs miatt megtagadva. Az API-ra irányuló kérések során mindenképpen adja meg az előfizetési kulcsot.
engedélyezés	Az előfizetéskulcs értéke érvénytelen	Előfizetési kulcs érvénytelen	Érvénytelen előfizetési kulcs miatt a hozzáférés megtagadva. Győződjön meg arról, hogy érvényes kulcsot ad meg egy aktív előfizetéshez.
többszörös	Az ügyfél megszakította az alsóbb rétegbeli kapcsolatot (egy ügyfél és egy API Management-átjáró között), miközben a kérés függőben volt	Ügyfélkapcsolati hiba	többszörös
többszörös	A háttérrendszer nem létesített vagy megszakított felsőbb rétegbeli kapcsolatot (API Management-átjáróról háttérszolgáltatásra)	Háttérkapcsolati Hiba	többszörös
többszörös	Futásidejű kivétel történt egy adott kifejezés kiértékelése során	Kifejezésiérték-értékelési hiba	többszörös

Előre definiált hibák szabályzatokhoz

Az alábbi hibák előre definiálva vannak a szabályzat kiértékelése során esetlegesen előforduló hibafeltételekhez.

Forrás	Feltétel	Ok	Üzenet
sebességkorlát	Túllépte a sebességkorlátot	Sebességkorlát túllépve	Túllépte a sebességkorlátot
kvóta	Kvóta túllépve	Kvóta túllépve	A csomagba foglalt lebeszélhető percek elfogytak. A kvóta xx:xx:xx formátumban lesz feltöltve. -or- Kifogyott a sávszélesség-kvóta. A kvóta xx:xx:xx formátumban lesz feltöltve.
jsonp	A visszahívási paraméter értéke érvénytelen (hibás karaktereket tartalmaz)	Érvénytelen visszahívási paraméter	A(z) {callback-parameter-name} visszahívási paraméter értéke nem érvényes JavaScript-azonosító.
IP-szűrő	Nem sikerült elemezni a hívó IP-címét a kérelemből	Nem sikerült elemezni a hívó IP-címét	Nem sikerült létrehozni a hívó IP-címét. A hozzáférés megtagadva.
IP-szűrő	A hívó IP-címe nincs engedélyezve a listában	Hívó IP nem engedélyezett	A hívó IP-címe ({ip-address}) nem engedélyezett. A hozzáférés megtagadva.
IP-szűrő	A hívó IP-címe letiltott listában van	CallerIpBlocked	A hívó IP-címe le van tiltva. A hozzáférés megtagadva.
check-header	A szükséges fejléc nem jelenik meg, vagy hiányzik az érték	HeaderNemTalálható	A(z) {header-name} fejléc nem található a kérelemben. A hozzáférés megtagadva.
check-header	A szükséges fejléc nem jelenik meg, vagy hiányzik az érték	A mezőérték nem engedélyezett	A(z) {header-value} fejléc {header-name} értéke nem engedélyezett. A hozzáférés megtagadva.
JWT érvényesítése	A JWT hiányzik a kérelemben	TokenNemTalálható	A JWT nincs jelen.
JWT érvényesítése	Az aláírás ellenőrzése nem sikerült	Tokentaláláírásérvénytelen	<üzenet a jwt könyvtárból>. A hozzáférés megtagadva.
JWT érvényesítése	Érvénytelen célközönség	Közönség Hiba – Token Nem Engedélyezett	<üzenet a jwt könyvtárból>. A hozzáférés megtagadva.
JWT érvényesítése	Érvénytelen kiállító	Tokenkibocsátó nem engedélyezett	<üzenet a jwt könyvtárból>. A hozzáférés megtagadva.
JWT érvényesítése	Lejárt a jogkivonat.	Token lejárt	<üzenet a jwt könyvtárból>. A hozzáférés megtagadva.
JWT érvényesítése	Az aláírási kulcsot nem oldotta fel azonosító	Aláíráskulcs nem található	<üzenet a jwt könyvtárból>. A hozzáférés megtagadva.
JWT érvényesítése	A szükséges jogcímek hiányoznak a jogkivonatból	JelölésNemTalálható	A JWT-ből hiányoznak a következő jogcímek: <c1>, <c2>, ... A hozzáférés megtagadva.
JWT érvényesítése	A jogcímértékek nem egyeznek	TokenIgényÉrtékNemEngedélyezett	A(z) {claim-value} jogcím {jogcímnév} értéke nem engedélyezett. A hozzáférés megtagadva.
JWT érvényesítése	Egyéb érvényesítési hibák	JwtÉrvénytelen	<üzenet a jwt könyvtárból>
forward-request vagy send-request	A HTTP-válasz állapotkódja és fejlécei nem érkeztek meg a háttérrendszerből a konfigurált időtúllépésen belül	Időkorlát	többszörös

Példa

API-szabályzat beállítása a következőre:

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

és a jogosulatlan kérés elküldése a következő választ eredményezi:

Kapcsolódó tartalom

A szabályzatok használatával kapcsolatos további információkért lásd:

• Oktatóanyag: AZ API átalakítása és védelme
• Szabályzathivatkozás a szabályzatutasságok és azok beállításainak teljes listájához
• Házirend-kifejezések
• Házirendek beállítása vagy szerkesztése
• Szabályzatkonfigurációk újrafelhasználása
• Szabályzatrészletek adattára
• Házirend-játszótér adattára
• Azure API Management policy toolkit
• A Copilot segítségével szabályzatokat hozhat létre, magyarázhat el és háríthat el hibákat.