API Management ilkelerinde hata işleme

Azure API Management, bir ProxyError nesne sağlayarak yayımcıların isteklerin işlenmesi sırasında oluşabilecek hata koşullarına yanıt vermesine olanak tanır. Nesneye ProxyError bağlam üzerinden erişilir . LastError özelliği ve ilke bölümündeki ilkeler on-error tarafından kullanılabilir. Bu makalede Azure API Management'daki hata işleme özellikleri için bir başvuru sağlanır.

API Management'de hata işleme

Azure API Management ilkeleri, aşağıdaki örnekte gösterildiği gibi , backend, outboundve on-error bölümlerine ayrılmıştırinbound.

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

bir isteğin işlenmesi sırasında yerleşik adımlar, isteğin kapsamındaki tüm ilkelerle birlikte yürütülür. Bir hata oluşursa, işleme hemen ilke bölümüne atlar on-error . İlke on-error bölümü herhangi bir kapsamda kullanılabilir. API yayımcıları, hatayı olay hub'larına günlüğe kaydetme veya çağırana geri dönmek için yeni bir yanıt oluşturma gibi özel davranışları yapılandırabilir.

Not

Bölüm on-error varsayılan olarak ilkelerde mevcut değildir. Bölümü bir ilkeye eklemek on-error için, ilke düzenleyicisinde istediğiniz ilkeye göz atın ve ekleyin. İlkeleri yapılandırma hakkında daha fazla bilgi için bkz. API Management'da ilkeler.

Bölüm yoksa on-error , bir hata koşulu oluşursa arayanlar 400 veya 500 HTTP yanıt iletisi alır.

Hatada izin verilen ilkeler

İlke bölümünde aşağıdaki ilkeler on-error kullanılabilir.

LastError

Bir hata oluştuğunda ve denetim ilke bölümüne atladığında on-error , hata bağlam içinde depolanır . Bölümünde ilkeler on-error tarafından erişilebilen LastError özelliği. LastError aşağıdaki özelliklere sahiptir.

Ad Tür Açıklama Gerekli
Source string Hatanın oluştuğu öğeyi adlandırın. İlke veya yerleşik işlem hattı adım adı olabilir. Yes
Reason string Hata işlemede kullanılabilecek makine dostu hata kodu. No
Message string İnsan tarafından okunabilir hata açıklaması. Yes
Scope string Hatanın oluştuğu kapsamın adı ve "genel", "ürün", "api" veya "işlem" olabilir No
Section string Hatanın oluştuğu bölüm adı. Olası değerler: "gelen", "arka uç", "giden" veya "hatada". No
Path string İç içe ilkeyi belirtir, örneğin "choose[3]/when[2]". No
PolicyId string Hatanın id oluştuğu ilkede müşteri tarafından belirtildiyse özniteliğinin değeri No

İpucu

Durum koduna bağlam aracılığıyla erişebilirsiniz. Response.StatusCode.

Not

Tüm ilkeler, ilkenin kök öğesine eklenebilen isteğe bağlı id bir özniteliğe sahiptir. Bir hata koşulu oluştuğunda bu öznitelik bir ilkede mevcutsa özniteliğin değeri özelliği kullanılarak context.LastError.PolicyId alınabilir.

Yerleşik adımlar için önceden tanımlanmış hatalar

Aşağıdaki hatalar, yerleşik işleme adımlarının değerlendirilmesi sırasında oluşabilecek hata koşulları için önceden tanımlanmıştır.

Kaynak Koşul Nedeni İleti
yapılandırma Uri hiçbir API veya İşlemle eşleşmiyor OperationNotFound Gelen istek bir işlemle eşleştirilemiyor.
yetkilendirme Abonelik anahtarı sağlanmadı SubscriptionKeyNotFound Eksik abonelik anahtarı nedeniyle erişim reddedildi. Bu API'ye istekte bulunurken abonelik anahtarını eklediğinizden emin olun.
yetkilendirme Abonelik anahtarı değeri geçersiz SubscriptionKeyInvalid Geçersiz abonelik anahtarı nedeniyle erişim reddedildi. Etkin bir abonelik için geçerli bir anahtar sağladığıdan emin olun.
birden çok İstek beklerken aşağı akış bağlantısı (istemciden API Management ağ geçidine) istemci tarafından durduruldu ClientConnectionFailure birden çok
birden çok Yukarı akış bağlantısı (API Management ağ geçidinden arka uç hizmetine) kurulmadı veya arka uç tarafından durduruldu BackendConnectionFailure birden çok
birden çok Belirli bir ifadenin değerlendirilmesi sırasında çalışma zamanı özel durumu oluştu ExpressionValueEvaluationFailure birden çok

İlkeler için önceden tanımlanmış hatalar

İlke değerlendirmesi sırasında oluşabilecek hata koşulları için aşağıdaki hatalar önceden tanımlanmıştır.

Kaynak Koşul Nedeni İleti
hız sınırı Hız sınırı aşıldı RateLimitExceeded Hız sınırı aşıldı
kota Kota aşıldı QuotaExceeded Çağrı hacmi kotası aşıldı. Kota xx:xx:xx içinde yenilenir. -veya- Bant genişliği kotası yetersiz. Kota xx:xx:xx içinde yenilenir.
Jsonp Geri çağırma parametresi değeri geçersiz (yanlış karakterler içeriyor) CallbackParameterInvalid {callback-parameter-name} geri çağırma parametresinin değeri geçerli bir JavaScript tanımlayıcısı değil.
ip filtresi Çağıranın IP'sini istekten ayrıştıramadı FailedToParseCallerIP Çağıran için IP adresi oluşturulamadı. Erişim reddedildi.
ip filtresi Arayan IP'leri izin verilenler listesinde değil CallerIpNotAllowed Arayan IP adresine {ip-address} izin verilmiyor. Erişim reddedildi.
ip filtresi Arayan IP'leri engellenenler listesinde CallerIpBlocked Arayan IP adresi engellendi. Erişim reddedildi.
check-header Gerekli üst bilgi gösterilmedi veya değer eksik HeaderNotFound {header-name} üst bilgisi istekte bulunamadı. Erişim reddedildi.
check-header Gerekli üst bilgi gösterilmedi veya değer eksik HeaderValueNotAllowed {header-value} üst bilgi {header-name} değerine izin verilmiyor. Erişim reddedildi.
validate-jwt Jwt belirteci istekte eksik TokenNotPresent JWT yok.
validate-jwt İmza doğrulaması başarısız oldu TokenSignatureInvalid <jwt kitaplığından> ileti. Erişim reddedildi.
validate-jwt Geçersiz hedef kitle TokenAudienceNotAllowed <jwt kitaplığından> ileti. Erişim reddedildi.
validate-jwt Geçersiz veren TokenIssuerNotAllowed <jwt kitaplığından> ileti. Erişim reddedildi.
validate-jwt Belirtecin süresi doldu TokenExpired <jwt kitaplığından> ileti. Erişim reddedildi.
validate-jwt İmza anahtarı kimlikle çözümlenmedi TokenSignatureKeyNotFound <jwt kitaplığından> ileti. Erişim reddedildi.
validate-jwt Belirteçte gerekli talepler eksik TokenClaimNotFound JWT belirtecinde şu talepler eksik: <c1>, <c2>, ... Erişim reddedildi.
validate-jwt Talep değerleri uyuşmazlığı TokenClaimValueNotAllowed {claim-value} değerinin {claim-name} talebine izin verilmiyor. Erişim reddedildi.
validate-jwt Diğer doğrulama hataları JwtInvalid <jwt kitaplığından ileti>
iletme isteği veya gönderme isteği HTTP yanıt durum kodu ve üst bilgileri, yapılandırılan zaman aşımı içinde arka uçtan alınmadı Zaman aşımı birden çok

Örnek

API ilkesini şu şekilde ayarlama:

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

ve yetkisiz istek göndermek aşağıdaki yanıtla sonuçlanır:

Unauthorized error response

Sonraki adımlar

İlkelerle çalışma hakkında daha fazla bilgi için bkz: