API Management ilkelerinde hata işleme

UYGULANANLAR: Tüm API Management katmanları

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. ProxyError Nesneye 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'taki hata işleme özellikleri için bir başvuru sağlanır.

API Management'ta hata işleme

Azure API Management'taki ilkeler, aşağıdaki örnekte gösterildiği gibi , inbound, backendve outbound bölümlerine ayrılmıştıron-error.

<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 on-error eklemek 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'ta 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

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

• seçmek
• set-variable
• bul ve değiştir
• return-response
• başlık-ayarla
• set-method
• set-status
• istek gönder
• tek-yönlü-talep-gönder
• Event Hub'a kaydet
• json-to-xml
• xml-to-json
• sınır eşzamanlılığı
• sahte yanıt
• Yeni -den deneme
• iz

Son Hata

Bir hata oluştuğunda ve denetim ilke bölümüne atladığındaon-error, hata bağlam içinde özelliği. LastError aşağıdaki özelliklere sahiptir.

Adı	Tür	Açıklama	Gerekli
Source	Dize	Hatanın oluştuğu öğeyi adlandırın. İlke veya yerleşik işlem hattı adımı adı olabilir.	Evet
Reason	Dize	Hata işlemede kullanılabilecek makine dostu hata kodu.	Hayır
Message	Dize	İnsan tarafından okunabilen hata açıklaması.	Evet
Scope	Dize	Hatanın oluştuğu kapsamın adı.	Hayır
Section	Dize	Hatanın oluştuğu bölüm adı. Olası değerler: "gelen", "arka uç", "giden" veya "hatada".	Hayır
Path	Dize	İç içe ilke hiyerarşisini belirtir, örneğin "choose[3]\when[2]". İç içe bir ilkenin birden çok örneği 1'den dizine eklenir.	Hayır
PolicyId	Dize	Hatanın id oluştuğu ilkede müşteri tarafından belirtilirse özniteliğinin değeri	Hayır

İpucu

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

Not

Tüm ilkelerin, ilkenin kök öğesine eklenebilen isteğe bağlı id bir özniteliği vardır. 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	İşlemBulunamadı	Gelen istek bir işlemle eşleştirilemiyor.
yetkilendirme	Abonelik anahtarı sağlanmadı	AbonelikAnahtarıBulunamadı	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 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	İstemci Bağlantı Hatası	birden çok
birden çok	Yukarı akış bağlantısı (API Management ağ geçidinden arka uç hizmetine) kurulamadı veya arka uç tarafından durduruldu	Arka Uç Bağlantı Hatası	birden çok
birden çok	Belirli bir ifadenin değerlendirilmesi sırasında çalışma zamanı özel durumu oluştu	İfade Değeri Değerlendirme Başarısızlığı	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ı	Oran Limiti Aşıldı	Hız sınırı aşıldı
kota	Kota aşıldı	Kota Aşıldı	Ç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)	Geri Arama Parametresi Geçersiz	{callback-parameter-name} geri çağırma parametresinin değeri geçerli bir JavaScript tanımlayıcısı değil.
IP filtresi	Arayan IP'sini istekten ayrıştırılamadı	Çağrı Yapanın IP'si Ayrıştırılamadı	Arayan için IP adresi oluşturulamadı. Erişim reddedildi.
IP filtresi	Arayan IP'leri izin verilenler listesinde değil	Çağrıcı IP'sine İzin Verilmiyor	Arayan IP adresine {ip-address} izin verilmiyor. Erişim reddedildi.
IP filtresi	Arayan IP'leri engellenenler listesinde	Çağıranın IP'si Engellendi	Arayan IP adresi engellendi. Erişim reddedildi.
başlığı kontrol et	Gerekli üst bilgi gösterilmedi veya değer eksik	HeaderNotFound	İstekte {header-name} üst bilgisi bulunamadı. Erişim reddedildi.
başlığı kontrol et	Gerekli üst bilgi gösterilmedi veya değer eksik	BaşlıkDeğeriYasak	{header-value} üst bilgi {header-name} değerine izin verilmiyor. Erişim reddedildi.
jwt'yi doğrula	JWT istekte eksik	BelirteçBulunamadı	JWT yok.
jwt'yi doğrula	İmza doğrulaması başarısız oldu	Jeton İmzası Geçersiz	<jwt kitaplığından> ileti. Erişim reddedildi.
jwt'yi doğrula	Geçersiz hedef kitle	Jeton İzleyicisi İzin Verilmiyor	<jwt kitaplığından> ileti. Erişim reddedildi.
jwt'yi doğrula	Geçersiz veren	JetonVericiİzinVerilmedi	<jwt kitaplığından> ileti. Erişim reddedildi.
jwt'yi doğrula	Belirtecin süresi doldu	Jeton Süresi Doldu	<jwt kitaplığından> ileti. Erişim reddedildi.
jwt'yi doğrula	İmza anahtarı kimlikle çözümlenmedi	Jeton İmza Anahtarı Bulunamadı	<jwt kitaplığından> ileti. Erişim reddedildi.
jwt'yi doğrula	Belirteçte gerekli talepler eksik	JetonTalebiBulunamadı	JWT'de şu talepler eksik: <c1>, <c2>, ... Erişim reddedildi.
jwt'yi doğrula	Talep değerleri uyuşmazlığı	JetonTalepDeğeriİzinVerilmez	{claim-value} değerinin {claim-name} talebine izin verilmiyor. Erişim reddedildi.
jwt'yi doğrula	Diğer doğrulama hataları	JWT Geçersiz	<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ıta neden olur:

İlgili içerik

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

• Öğretici: API'nizi dönüştürme ve koruma
• İlke deyimlerinin ve ayarlarının tam listesi için ilke başvurusu
• İlke ifadeleri
• İlkeleri ayarlama veya düzenleme
• İlke yapılandırmalarını yeniden kullanma
• İlke kod parçacıkları deposu
• İlke oyun alanı deposu
• Azure API Management ilke araç seti
• Politikalar oluşturmak, açıklamak ve sorun gidermek için Copilot yardımı alın