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 inbound
backend
outbound
é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álassza ki
- set-variable
- keresés és csere
- visszatérési válasz
- set-header
- set-method
- beállítás állapota
- küldési kérelem
- egyirányú kérés küldése
- log-to-eventhub
- json-to-xml
- xml-to-json
- korlát-egyidejűség
- mock-response
- Újra
- Nyomkövetési
LastError
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, és lehet a "globális", a "termék", az "api" vagy a "művelet" | 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ályzatot ad meg, például "choose[3]/when[2]". | 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 | OperationNotFound | A bejövő kérés nem egyezik egy művelettel. |
engedélyezés | Az előfizetési kulcs nincs megadva | SubscriptionKeyNotFound | 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 | SubscriptionKeyInvalid | É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öbb | 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él Csatlakozás ionFailure | Több |
Több | 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) | BackendConnectionFailure | Több |
Több | Futásidejű kivétel történt egy adott kifejezés kiértékelése során | ExpressionValueEvaluationFailure | Több |
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 | RateLimitExceeded | Túllépte a sebességkorlátot |
kvóta | Kvóta túllépve | QuotaExceeded | 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) | CallbackParameterInvalid | A(z) {callback-parameter-name} visszahívási paraméter értéke nem érvényes JavaScript-azonosító. |
ip-filter | Nem sikerült elemezni a hívó IP-címét a kérelemből | FailedToParseCallerIP | Nem sikerült létrehozni a hívó IP-címét. A hozzáférés megtagadva. |
ip-filter | A hívó IP-címe nincs engedélyezve a listában | CallerIpNotAllowed | A hívó IP-címe ({ip-address}) nem engedélyezett. A hozzáférés megtagadva. |
ip-filter | 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 | HeaderNotFound | 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 | HeaderValueNotAllowed | A(z) {header-value} fejléc {header-name} értéke nem engedélyezett. A hozzáférés megtagadva. |
validate-jwt | A Jwt-jogkivonat hiányzik a kérelemben | TokenNotPresent | A JWT nincs jelen. |
validate-jwt | Az aláírás ellenőrzése nem sikerült | TokenSignatureInvalid | <üzenet a jwt könyvtárból>. A hozzáférés megtagadva. |
validate-jwt | Érvénytelen célközönség | TokenAudienceNotAllowed | <üzenet a jwt könyvtárból>. A hozzáférés megtagadva. |
validate-jwt | Érvénytelen kiállító | TokenIssuerNotAllowed | <üzenet a jwt könyvtárból>. A hozzáférés megtagadva. |
validate-jwt | Lejárt a jogkivonat. | TokenExpired | <üzenet a jwt könyvtárból>. A hozzáférés megtagadva. |
validate-jwt | Az aláírási kulcsot nem oldotta fel azonosító | TokenSignatureKeyNotFound | <üzenet a jwt könyvtárból>. A hozzáférés megtagadva. |
validate-jwt | A szükséges jogcímek hiányoznak a jogkivonatból | TokenClaimNotFound | JWT token hiányzik a következő jogcímek: <c1>, <c2>, ... A hozzáférés megtagadva. |
validate-jwt | A jogcímértékek nem egyeznek | TokenClaimValueNotAllowed | A(z) {claim-value} jogcím {jogcímnév} értéke nem engedélyezett. A hozzáférés megtagadva. |
validate-jwt | Egyéb érvényesítési hibák | JwtInvalid | <ü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öbb |
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:
Következő lépések
A szabályzatokkal kapcsolatos további információkért lásd:
- Szabályzatok az API Managementben
- API-k átalakítása
- Szabályzathivatkozás a szabályzatutasságok és azok beállításainak teljes listájához
- Szabályzatminták