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 , 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 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çin
- set-variable
- bul ve değiştir
- return-response
- set-header
- set-method
- set-status
- istek gönder
- send-one-way-request
- log-to-eventhub
- json-to-xml
- xml-to-json
- sınır eşzamanlılığı
- sahte yanıt
- Yeni -den deneme
- Izleme
LastError
Bir hata oluştuğunda ve denetim ilke bölümüne atladığındaon-error, hata bağlam içinde depolanır. Bölümdeki ilkeler on-error tarafından erişilebilen LastError ö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. | Yes |
Reason |
Dize | Hata işlemede kullanılabilecek makine dostu hata kodu. | Hayır |
Message |
Dize | İnsan tarafından okunabilen hata açıklaması. | Yes |
Scope |
Dize | Hatanın oluştuğu kapsamın adı ve "genel", "ürün", "api" veya "işlem" olabilir | 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 ilkeyi belirtir, örneğin "choose[3]/when[2]". | 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.
| Source | 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 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 | client Bağlan ionFailure | birden çok |
| birden çok | Yukarı akış bağlantısı (API Management ağ geçidinden arka uç hizmetine) kurulamadı 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.
| Source | 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-filter | Arayan IP'sini istekten ayrıştırılamadı | FailedToParseCallerIP | Arayan için IP adresi oluşturulamadı. Erişim reddedildi. |
| ip-filter | Arayan IP'leri izin verilenler listesinde değil | CallerIpNotAllowed | Arayan IP adresine {ip-address} izin verilmiyor. Erişim reddedildi. |
| ip-filter | 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 | İstekte {header-name} üst bilgisi 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ı | Timeout | 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:
Sonraki adımlar
İlkelerle çalışma hakkında daha fazla bilgi için bkz: