Hataları işleme

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi

API proxy'leri uygulamalardan gelen isteklere hizmet verirken birçok hata durumu ortaya çıkabilir. Örneğin, API proxy'leri arka uç hizmetleriyle iletişim kurarken ağ sorunlarıyla karşılaşabilir, uygulamalar süresi dolmuş kimlik bilgileri sunabilir, istek mesajları yanlış biçimlendirilmiş olabilir vb.

İstemci uygulaması API proxy'sini çağırdıktan sonra hata oluşursa istemciye bir hata mesajı döndürülür. Varsayılan olarak istemci, ayrıntı veya rehberlik içermeyen genellikle şifreli bir hata mesajı alır. Ancak, varsayılan hata mesajlarını daha kullanışlı özel mesajlarla değiştirmek ve hatta ek HTTP üst bilgileri gibi öğelerle zenginleştirmek isterseniz Edge'de özel hata işlemeyi ayarlamanız gerekir.

Özel hata işleme, hata meydana geldiğinde mesaj kaydı gibi işlevler eklemenize de olanak tanır.

API proxy'lerinizde özel hata işlemeden bahsetmeden önce hataların nasıl oluştuğunu ve API proxy'lerinin bunlara nasıl tepki verdiğini anlamanız önemlidir.

Videolar

Hata giderme hakkında daha fazla bilgi edinmek için aşağıdaki videoları izleyin.

Hatalar nasıl oluşur?

İlk olarak hataların nasıl ortaya çıktığını ele alacağız. Hataların nasıl oluştuğunu bilmek, özel hata işlemeyi uygulamak istediğiniz farklı durumlar için plan yapmanıza yardımcı olur.

Otomatik hatalar

Bir API proxy'si aşağıdaki durumlarda otomatik olarak hata bildirir:

• Politika hata verir. Örneğin, bir API çağrısı süresi dolmuş bir anahtar gönderirse VerifyAPIKey politikası otomatik olarak hata bildirir ya da API çağrılarının sayısı belirli bir sınırı aşarsa Kota politikası veya SpikeArrest politikası hata verir. (Politikaların bildirebileceği hata türleri için Politika hatası referansı bölümüne bakın).
• API proxy mesaj akışında yönlendirme hatası gibi bir sorun vardır.
• Protokol düzeyindeki hatalar, TLS/SSL hataları veya kullanılamayan bir hedef hizmetten kaynaklanan HTTP hatası gibi bir arka uç hatası vardır.
• Bellek yetersiz istisnası gibi sistem düzeyinde bir hata vardır.

Bu hatalarla ilgili daha fazla bilgi için bu konudaki Hata sınıflandırması bölümüne bakın.

Özel hatalar

Otomatik hatanın olmadığı durumlarda, örneğin bir yanıt "unavailable " kelimesini içeriyorsa veya HTTP durum kodu 201'den büyükse özel bir hata vermek isteyebilirsiniz. Bunu yapmak için API proxy akışında uygun yere bir PromoteFault politikası ekleyin.

API proxy akışına diğer tüm politikalarda olduğu gibi PromoteFault politikası ekleyebilirsiniz. Aşağıdaki proxy yapılandırma örneğinde Raise-Fault-1 politikası TargetEndpoint yanıtına eklenmiştir. Hedef hizmetten gelen yanıtta "unavailable" (kullanılamıyor) kelimesi varsa TeachFault politikası yürütülür ve bir hata verir.

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
    </Step>
  </Response>

Bu, özel hatalar oluşturabileceğinizi göstermek içindir. GrowFault politikası, FaultRules ile yerlerde ParentFault politikasının karşılaştırması bölümünde daha ayrıntılı olarak açıklanmıştır.

Daha fazla örnek için Apigee Topluluk Forumları'ndaki şu yayınlara bakın:

• PromoteFault'ta JavaScript değişkenlerine referans verme

Hata oluştuğunda API proxy'leri ne yapar?

Bir proxy hata verdiğinde neler olacağı aşağıda açıklanmaktadır.

Proxy ardışık düzeninden çık

Bir API proxy'si, nasıl gerçekleştiğine bakılmaksızın hatayla karşılaştığında normal akış ardışık düzeninden çıkar, bir hata durumu girer ve istemci uygulamasına bir hata mesajı döndürür. API proxy'si hata durumuna girdikten sonra tekrar normal akış ardışık düzenine işlemeyi geri alamaz.

Örneğin, bir API proxy'sinin ProxyEndpoint isteğinde aşağıdaki sırada politikaları olduğunu varsayalım:

1. API Anahtarını Doğrulama
2. Kota
3. JSON'dan XML'e

API anahtarı doğrulaması sırasında hata oluşursa API proxy'si hata durumuna geçer. Kota ve JSON'den XML'e yönelik politikalar yürütülmez, proxy TargetEndpoint'e ilerlemez ve istemci uygulamasına bir hata mesajı döndürülür.

FaultRules olup olmadığını kontrol edin

Hata durumunda API proxy'leri, istemci uygulamasına varsayılan hata mesajı döndürmeden önce API proxy yapılandırmasında aşağıdakilerin olup olmadığını da (sırayla) kontrol eder:

1. Tanımladığınız belirli koşullara göre özel hata mesajlarını (ve diğer politikaları) tetikleme mantığını içeren <FaultRules> bölümü.
2. Aşağıdaki durumlarda varsayılan hata mesajını tetikleyen bir <DefaultFaultRule> bölümü:
   • <FaultRules> tanımlanmadı.
   • Mevcut <FaultRules> yürütülmesin.
   • <AlwaysEnforce> öğesi true olarak ayarlandı.

Özetle, API proxy'si size özel bir hata mesajı döndürmeniz ve başka mantığı tetiklemeniz için fırsat sunar. Proxy bu bölümlerin ikisini de bulamıyorsa veya bölümler mevcut olmasına rağmen herhangi bir özel hata tetiklenmediyse proxy, Edge tarafından oluşturulan kendi varsayılan mesajını gönderir.

Basit hata giderme örneği

API proxy'sine yapılan bir çağrının gerekli API anahtarını içermediği basit bir örnekle başlayalım. Varsayılan olarak istemci uygulamasına döndürülen yanıt aşağıda verilmiştir:

HTTP/1.1 401 Unauthorized
Date: Wed, 20 Jul 2016 19:19:32 GMT
Content-Type: application/json
Content-Length: 150
Connection: keep-alive
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

API kullanıcılarınız hata mesajını anlayabilir, ancak anlayamayabilirler. Ayrıca, birçok varsayılan hata daha hafiftir ve çözülmesi daha zordur.

Bir API geliştiricisi olarak, ister bir iOS uygulaması geliştiricisi ister kendi hata mesajı biçimi gereksinimleri olan dahili bir test grubu olsun, bu mesajı sonuçta hata mesajını alacak kişinin ihtiyaçlarını karşılayacak şekilde değiştirmek sizin sorumluluğunuzdadır.

Bu hatayı işlemek için nasıl özel hata mesajı oluşturabileceğinizle ilgili temel bir örneği aşağıda bulabilirsiniz. Bunun için 1) özel mesajı tanımlayan bir politika ve 2) proxy hata durumuna geçtiğinde politikayı yürüten bir FaultRule gerekir.

1. Özel mesajı tanımlayan bir politika oluşturun

Öncelikle, özel hata mesajını tanımlayan bir politika oluşturun. Yük belirleyen assignMessage politikası gibi herhangi bir türde politika ile durum kodu ve neden ifadesi gibi isteğe bağlı HTTP üstbilgilerini kullanabilirsiniz. İleti Atama seçeneği bunun için idealdir. Bu sayede mesaj yükünü kontrol edebilir, farklı bir HTTP durum kodu ayarlayabilir, farklı bir HTTP neden ifadesi ayarlayabilir ve HTTP üstbilgileri ekleyebilirsiniz.

Politikayı API proxy'sindeki herhangi bir akışa eklemeyin. Bunun proxy paketinde mevcut olması yeterlidir. Bunu yönetim kullanıcı arayüzü proxy düzenleyicisinde yapmak için Geliştirme sekmesine gidin ve Gezinme bölmesinde Politikalar çubuğundaki + simgesini tıklayın.

Bu sayede, API proxy'sindeki bir akışa politika eklemeden politika oluşturabilirsiniz. Herhangi bir akışa bağlı olmayan politikalar, önceki resimde gösterilen API anahtarı mesaj politikasının yanında gösterildiği gibi, Politikalar listesinde "ayrıldı" simgesiyle işaretlenir.

Aşağıda, aşağıdakileri yapan bir assignMessage politikası örneği verilmiştir:

• Bir JSON iletisi döndürür.
• Bir HTTP durum kodu (sadece sahip olduğunuz esnekliği göstermek için var olmayan bariz bir durum kodu olan 911) ayarlar. Durum kodu, HTTP üstbilgisinde görüntülenir.
• Bir HTTP neden ifadesi ayarlar (bu eksik API anahtarı hatası için varsayılan "Yetkisiz" neden ifadesini değiştirmek üzere). Neden ifadesi, HTTP başlığında, durum kodunun yanında görünür.
• invalidKey adlı yeni bir HTTP üst bilgisi oluşturur ve doldurur.

<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message">
    <DisplayName>Invalid key message</DisplayName>
    <Set>
        <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload>
        <StatusCode>911</StatusCode>
        <ReasonPhrase>Rejected by API Key Emergency Services</ReasonPhrase>
    </Set>
    <Add>
        <Headers>
            <Header name="invalidKey">Invalid API key! Call the cops!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Bu politika yürütüldüğünde, istemci uygulamaya verilen yanıt aşağıdaki gibi görünür. Bunu daha önce gösterilen varsayılan yanıtla karşılaştırın.

HTTP/1.1 911 Rejected by API Key Emergency Services
Date: Wed, 20 Jul 2016 18:42:36 GMT
Content-Type: application/json
Content-Length: 35
Connection: keep-alive
invalidKey: Invalid API key! Call the cops!
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"Citizen":"Where's your API key? I don't see it as a query parameter."}

Evet, biraz tuhaf bir soru ama size nelerin mümkün olduğunu gösteriyor. Mesajı alan geliştirici, en azından artık bir API anahtarını sorgu parametresi olarak eklemeyi unuttuğunun farkında.

Peki bu politika nasıl uygulanır? Bir sonraki bölümde gösterilir.

2. Politikayı tetikleyecek <FaultRule>'ı oluşturun

Proxy yapılandırmasının <ProxyEndpoint> veya <TargetEndpoint> bölümlerinde, bir veya daha fazla ayrı <FaultRule> bölümü içeren bir <FaultRules> XML bloğu ekleyeceksiniz. Her FaultRule, ele almak istediğiniz farklı bir hatayı temsil eder. Bu basit örnekte, size onun neleri içerdiğini göstermek için yalnızca bir FaultRule kullanacağız.

Ayrıca, FaultKurallarınızın hiçbiri yürütülmezse özel bir genel hata mesajı sağlamak için <DefaultFaultRule> eklemeniz gerekir.

Örnek

<ProxyEndpoint name="default">
...
    <FaultRules>
       <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Önemli noktalar:

• FaultRules, ProxyEndpoint'te tanımlanır. Bu önemlidir. Daha sonra, ProxyEndpoint ve TargetEndpoint öğelerine FaultRules yerleştirme hakkında daha fazla bilgi edinin.
• <Name> - Uygulanacak politikanın adı. Ad, önceki politika örneğinde gösterildiği gibi, politikanın üst öğedeki name özelliğinden gelir.

• <Condition>: Edge koşulu değerlendirir ve politikayı yalnızca koşul doğruysa yürütür. Doğru olarak değerlendirilen birden fazla FaultRules varsa Edge, doğru olan ilk kuralı yürütür. (Önemli: FaultRules'un değerlendirilme sırası, yukarıdan aşağıya veya aşağıdan yukarıya doğru, TargetEndpoint ve ProxyEndpoint değerleri arasında farklılık gösterir. Birden Fazla FaultKural ve yürütme mantığı bölümünde açıklanmıştır.) Bir koşul eklemezseniz FaultRule otomatik olarak doğru olur. Ancak bu, en iyi uygulamalardan biri değildir. Her FaultRule'ın kendi koşulu olmalıdır.

• <DefaultFaultRule> - Özel bir FaultRule yürütülmezse <DefaultFaultRule> yürütülür ve Edge tarafından oluşturulan şifreli varsayılan mesaj yerine daha genel bir özel mesaj gönderilir. <DefaultFaultRule> bir <Condition> etiketi de içerebilir. Ancak çoğu durumda bu koda dahil edilmezsiniz çünkü son çare olarak ne olursa olsun yürütülmesini istersiniz.

  DefaultFaultRule genellikle beklenmedik hatalar için genel bir hata mesajı döndürmek için kullanılır. Teknik destek için iletişim bilgilerini içeren bir mesaj buna örnek olarak verilebilir. Bu varsayılan yanıtın ikili amacı, geliştirici dostu bilgiler sağlamak ve sistemin güvenliğini ihlal etmek için kullanılabilecek arka uç URL'lerini veya diğer bilgileri karartmaktır.

Çoklu FaultRules ve yürütme mantığı

Basit hata işleme örneği bölümünde tek bir FaultRule ve koşulun basit bir örneğini kullandık. Gerçek dünyada oluşabilecek bir API projesinde oluşabilecek tüm olası hatalarla birlikte, hem <ProxyEndpoint> hem de <TargetEndpoint> uygulamanızda muhtemelen birden fazla FaultRules ve birDefaultFaultRule bulunur. Bununla birlikte, API proxy'si hata durumuna girdiğinde yalnızca bir FaultRule yürütülür.

Bu bölümde Edge'in FaultRules'u işlerken kullandığı mantık açıklanmaktadır. Bu mantık, yürütülmek için tek bir FaultRule'a ulaşmadan, bunların FaultRule'ı tetiklendiğinde "iç" Adım koşullarının nasıl ele alınacağına kadar geçerlidir. Bu bölümde ayrıca, <ProxyEndpoint> ve <TargetEndpoint> içinde FaultKuralların ne zaman tanımlanacağı açıklanmakta ve FaultRules ile arasındaki ilişki açıklanmaktadır.

FaultRules yürütme

Kısaca, Edge'in API proxy'si hata durumuna geçtiği durumlarda kullandığı mantığı aşağıda görebilirsiniz. ProxyEndpoint'teki FaultRules değerlendirmesi ile TargetEndpoint'teki FaultRules değerlendirmesi arasında küçük bir fark olduğunu unutmayın.

1. Edge, hatanın oluştuğu yere bağlı olarak FaultRules'u ProxyEndpoint veya TargetEndpoint'te değerlendirir:
   • ProxyEndpoint: Edge, yapılandırma XML'sinde bottom <FaultRule> ile başlar ve her bir <FaultRule> öğesinin <Condition>'ini ("iç" <Step> koşulları değil, "dış" koşulu) değerlendirerek yukarıya doğru ilerler.
   • TargetEndpoint: Edge, yapılandırma XML'sinde üst <FaultRule> ile başlar ve her bir <FaultRule> öğesinin <Condition> değerini ("iç" <Step> koşulları değil, "dış" koşul) değerlendirerek aşağı doğru ilerler.
2. Koşulu doğru olan ilk FaultRule'ı yürütür. Bir FaultRule koşulu yoksa varsayılan olarak doğru değerini alır.
   • Bir FaultRule yürütüldüğünde, FaultRule içindeki tüm adımlar, XML yapılandırmasında yukarıdan aşağıya, sırayla değerlendirilir. Koşul içermeyen adımlar otomatik olarak yürütülür (politikalar yürütülür) ve "doğru" olarak değerlendirilen bir <Condition> içeren adımlar yürütülür ("yanlış" olarak değerlendirilen koşullar yürütülmez).

   • Bir FaultRule yürütülürse ancak FaultRule'daki hiçbir Adım yürütülmezse (koşulları "false" olarak değerlendirildiği için) yürütülürse Edge tarafından oluşturulan varsayılan hata mesajı istemci uygulamasına döndürülür. Edge bir FaultRule'ı zaten yürüttüğü için <DefaultFaultRule> yürütülmez.

3. Herhangi bir FaultRule yürütülmezse Edge (mevcutsa) <DefaultFaultRule> politikasını yürütür.

Satır içi yorum örnekleri aşağıda verilmiştir.

ProxyEndpoint yürütme

ProxyEndpoint FaultRules'un değerlendirmesi aşağıdan yukarıya doğru yapılır. Bu nedenle, aşağıdaki örnekte yer alan son FaultRule'dan okumaya başlayın ve ilerlemeye devam edin. En son defaultFaultRule'a bakın.

<ProxyEndpoint name="default">
...
    <FaultRules>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just below this got
     executed (bottom-to-top evaluation in a ProxyEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 1. Because this is the ProxyEndpoint, Edge looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not 
     throw a FailedToResolveAPIKey error. Edge moves UP to check
     the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

TargetEndpoint yürütme

TargetEndpoint FaultRules'un değerlendirmesi yukarıdan aşağıya doğru yapılır. Bu nedenle, aşağıdaki örnekte ilk FaultRule'dan okumaya başlayın ve ilerlemeye devam edin. En son defaultFaultRule'a bakın.

<TargetEndpoint name="default">
...
    <FaultRules>
<!-- 1. Because this is the TargetEndpoint, Edge looks at this FaultRule
     first. Let's say this FaultRule is FALSE. 
     A policy did not throw a FailedToResolveAPIKey error. 
     Edge moves down to the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
        <FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just above this got
     executed (top-to-bottom evaluation in a TargetEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Hata kuralı sırası

Önceki örnekte görebileceğiniz gibi, FaultRules'u yerleştirdiğiniz sıra, hatanın ProxyEndpoint'te mi, TargetEndpoint'te mi meydana geldiğine bağlı olarak önemlidir.

Örneğin:

Dahil edilecek politikalar

FaultRule'daki politikaları Adımlara yerleştirerek yürütebilirsiniz. Örneğin, istemci uygulamasına gelen yanıtı biçimlendirmek için bir AssignmentMessage politikası yürütebilir, ardından MessageLogging politikasını kullanarak bir mesaj kaydedebilirsiniz. Politikalar, belirlediğiniz sırada yürütülür (XML'de yukarıdan aşağıya).

Hata kuralları YALNIZCA bir hata durumunda tetiklenir (ContinueOnError hakkında)

Başlık kendimizi tekrar ediyormuş gibi görünebiliriz. Ancak API proxy'sinin hata durumuna girmesine veya hata durumu girmemesine neden olan bir proxy hatasıyla ilgili olarak dikkat edilmesi gereken belirli bir nokta vardır: politikadaki continueOnError özelliği.

Özet: API proxy'si, <FaultRules> ve <DefaultFaultRule> değerlerini yalnızca proxy bir hata durumu girdiyse değerlendirir. Diğer bir deyişle, bir FaultRule koşulu doğru olarak değerlendirilse bile, proxy hata durumunda değilse bu koşul tetiklenmeyecek.

Ancak, ortaya çıkan bir hata ve proxy'nin hata durumu girmemesiyle ilgili bir örneği burada bulabilirsiniz. Herhangi bir politikada, üst öğede continueOnError adlı bir özellik ayarlayabilirsiniz. Bu özellik, politika başarısız olursa proxy'nin hata durumu girip girmeyeceğini belirlediğinden hata işleme açısından çok önemlidir. Çoğu durumda, politika başarısız olursa ve özel hata işleme süreci tetiklenir, proxy'yi hata durumuna geçiren varsayılan continueOnError="false" değerini korumak istersiniz. Bununla birlikte, continueOnError="true" durumunda (örneğin, bir Hizmet Çağrısı'nın proxy yürütülmesini durdurmasını istemiyorsanız) bu politika başarısız olursa proxy hata durumuna geçmez ve proxy, FaultRules'unuza bakmaz.

continueOnError="true" sırasındaki günlük kaydı hataları hakkında bilgi edinmek için Mevcut akıştaki politika hatalarını işleme bölümüne bakın.

FaultRules nerede tanımlanır: ProxyEndpoint veya TargetEndpoint

API proxy'sinde hatayla karşılaşıldığında hata, <ProxyEndpoint> (istemci uygulamasından istek veya istemci uygulamasına yanıt verme) ya da <TargetEndpoint> (hedef hizmetten gelen istek veya yanıt) içinde meydana gelir. Bu hatanın ortaya çıktığı her yerde Edge, FaultRules için arama yapar.

Örneğin, hedef sunucu yoksa (HTTP durum kodu 503) API proxy'si, <TargetEndpoint> yanıtında hata durumuna geçer ve normal API proxy akışı <ProxyEndpoint>'a devam etmez. Yalnızca <ProxyEndpoint> içinde tanımlanmış FaultRules varsa bunlar bu hatayı işlemez.

Bir örnek daha verelim. <ProxyEndpoint> yanıtındaki bir PromoteFault politikası hata tetiklerse <TargetEndpoint> içindeki bir FaultRule yürütülmez.

FaultRules ile PromoteFault politikası karşılaştırması

Hata kuralları ve ParentFault politikası, ilk bakışta hata işlemenin alternatif yolları gibi görünebilir ve bazı açılardan bu doğrudur. Ama aynı zamanda birlikte çalışırlar. Bu bölümde, ikisi arasındaki ilişki açıklanmaktadır. Bu ilişkiyi anlamanız, özellikle her ikisini de kullanmak istiyorsanız hata işleme yöntemini tasarlamanıza yardımcı olacaktır.

Özet olarak:

• Hata kuralları, API proxy'si hata durumuna girdiğinde her zaman değerlendirilir.

• RaiseFault politikası, API proxy'sini başka şekilde hata olmayacağı durumlarda hata durumuna getirmenin bir yoludur.

  Örneğin, hedef hizmetten gelen yanıttaki HTTP durum kodu 200'den büyükse hata bildirmek istiyorsanız yanıt akışınıza bir PromoteFault politikası eklersiniz. URL şuna benzer olacaktır:

  <TargetEndpoint name="default">
      <PreFlow name="PreFlow">
  ...
          <Response>
              <Step>
                  <Name>Raise-Fault-1</Name>
  <!-- If the condition is true, the Raise-Fault-1 policy gets executed -->
                  <Condition>(response.status.code GreaterThan "200")</Condition>
              </Step>
          </Response> 
  

  riseFault politikası da istemci uygulamasına bir hata mesajı gönderir.

Bir GrowFault politikası, proxy'yi hata durumuna geçirerek bir FaultRule yürüten bir hatayı tetiklediğinde ne olur? Burada işler biraz karışabilir. YükseltFault politikası hata mesajı döndürür ve bir FaultRule tetiklenip hata mesajı döndürürse istemci uygulamasına ne döndürülür?

• FaultRule veyaDefaultFaultRule, PromoteFault politikasından sonra yürütüldüğü için FaultRule yanıt verileri kazanır.
• GrowFault politika yanıt verileri (durum kodu, neden ifadesi veya mesaj yükü), bu veriler FaultRule veya defaultFaultRule tarafından ayarlanmazsa kullanılır.
• Hem {6/}Fault politikası hem de FaultRule özel HTTP üst bilgileri eklerse her ikisi de yanıta dahil edilir. Yinelenen başlık adları birden çok değere sahip üstbilgi oluşturur.

GrowFault politikası ile FaultRule politikası tarafından ayarlanana ve istemci uygulamasına nelerin döndürüldüğüne dair bir örneği burada bulabilirsiniz. Örnekler, en iyi uygulamalar için değil, kısa olması için tasarlanmıştır.

Status Code: 468
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: woops,gremlins

Status Code: [none] 
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: gremlins

Status Code: 468
Reason Phrase: Can't do that
Payload: {"DOH!":"Try again."}
Header: 
  errorNote: woops

Bina koşulları

Koşullar, FaultRule yürütmenin anahtarıdır. FaultRule koşullarını, koşullu akışlar veya liftFault koşulları gibi Edge'deki diğer koşullarla aynı şekilde oluşturursunuz.

Bu bölümün geri kalanını bağlam içinde göstermek için, bir dış FaultRule koşuluna ve bir iç Adım koşuluna sahip örnek bir hata kuralı aşağıda verilmiştir.

<FaultRule name="invalid_key_rule">
    <Step>
        <Name>invalid-key-message</Name>
        <Condition>(oauthV2.Verify-API-Key-1.failed = true)</Condition>
    </Step>
    <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
</FaultRule>

Politika hatalarına özel değişkenler

Bir politika hata verdiğinde fault.name ve {policy_namespace}.{policy_name}.failed değişkenleri kullanılabilir.

fault.name

Bir politika başarısız olduğunda, fault.name değişkenini kullanarak bir koşuldaki hatayı yakalayın. Örneğin:

<Condition>(fault.name = "policy_error_name")</Condition>

Hata adı, varsayılan hata mesajında görünür. Örneğin, aşağıdaki örnekte hata adı FailedToResolveAPIKey şeklindedir. Bu durumda, fault.name adlı bir akış değişkeni FailedToResolveAPIKey değerine ayarlanmıştır.

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

Bu durumda, koşul şöyle görünür:

<Condition>(fault.name = "FailedToResolveAPIKey")</Condition>

Politika hatalarının listesi için Politika hatası referansı bölümüne bakın.

{policy_namespace}.{policy_name}.failed

Bir politika başarısız olduğunda *.failed değişkeni kullanılabilir. Aşağıda, farklı politikalar için *.failed değişkeni örnekleri verilmiştir. Politika ad alanları için her bir politika referansı konusundaki akış değişkenlerine bakın.

• GrowFault politikası: raisefault.failed (tüm PromoteFault politikaları için aynı)
• VerifyAPIKey politikası: oauthV2.{policy_name}.failed (örneğin, oauthV2.Verify-API-Key-1.failed)
• Kota politikası ve SpikeArrest politikası: ratelimit.{policy_name}.failed (ör. ratelimit.Quota-1.failed)

Kullanılabilen diğer değişkenler

Bir API proxy'si hata durumuna girdiğinde, koşullarda yalnızca şu değişkenler kullanılabilir:

• Politikanın başarısız olduğu değişkenler.
• Hata noktasında mevcut olan HTTP mesajı değişkenleri. Örneğin, yanıtta bir hata oluşursa <TargetEndpoint> içindeki bir FaultRule, response.status.code, message.content, error.content gibi HTTP verilerini kullanabilir. Kota politikası başarısız olduysa ratelimit.{quota_policy_name}.exceed.count değişkenini de kullanabilirsiniz. Hangi değişkenlerin ve HTTP verilerinin kullanılabilir olduğunu anlamanıza yardımcı olması için İzleme aracını ve politika referans konularını kullanın.

Daha fazla bilgi

• Koşullar: Koşullar referansı ve Akış değişkenleri ve koşulları

• Hatalar: Politika hatası referansı
• Değişkenler: Değişkenler referansı ve her politikada kullanılabilen değişkenler için bağımsız politika referans sayfalarına bakabilirsiniz.

Hata giderme için en iyi uygulamalar

Hata işleme, API proxy'si geliştirmede önemli bir mimari tasarım görevidir. Hataları nasıl ve ne zaman ele alacağınızı düşünmek, hata mesajlarının ne olacağını belirlemek ve hata mesajı biçimlerini tasarlamak için zaman ayırmak önemlidir. Bunları yaptıktan sonra (veya çözdükten sonra), hata giderme uygulamanızda size yardımcı olması için bu en iyi uygulamalardan yararlanın.

Aşağıda, hata gidermeyi tasarlama ve oluşturma ile ilgili en iyi uygulamalardan bazıları verilmiştir:

• Her FaultRule için bir "dış" <Condition> (<Step> öğesine eşdüzey öğe) sağlayın. Dış koşulu olmayan hata kuralları otomatik olarak doğru şeklinde değerlendirilir. "İç" Adım koşulları, FaultRule'ın doğru veya yanlış olduğunu belirlemek için kullanılmaz. Adım koşulları yalnızca Edge bunları içeren FaultRule'ı yürüttükten sonra değerlendirilir. Bir FaultRule'da, her biri bir Adım koşuluna sahip Mesaj Ata (veya başka) politikaları içeren birden fazla adım olması normaldir.

• Aynı türdeki birden fazla politikadaki (ör. birden fazla Kota politikası) hataları işlemek için, karşılaşabileceğiniz her politika hatası için bir FaultRule oluşturun. Örneğin, Kota politikalarındaki QuotaViolation, InvalidMessageWeight ve StartTimeNotSupported gibi olası her hata için bir FaultRule oluşturun. (Politika hataları için Politika hatası referansı bölümüne bakın. İşlenmesi gereken ek hatalar keşfettikçe daha sonra geri dönüp bunları FaultRules'a ekleyebilirsiniz. Proxy yeniden dağıtımı gerektirse de yinelemeli olabilir.) Bu yaklaşım, hataya neden olan politika ne olursa olsun aynı tür hatayı yakalamanızı sağlar. Bu da FaultRules XML'inizi verimli hale getirir.

  Ardından, daha ayrıntılı hata kontrolüne ihtiyacınız varsa iç Adım koşullarını kullanın. Örneğin, istek akışınızda hem bağımsız geliştirici kotasını hem de genel kotayı iki politika ile uyguluyorsanız "dış" FaultRule koşulunuzu QuotaViolation hatasıyla (her iki durumda da kota aşıldığında tetiklenir) tetiklenecek şekilde ayarlayın. Ardından her iki kota politikanızda da exceed.count değişkenlerini değerlendirmek için Adım koşulları ayarlayın. İstemciye sadece ilgili hata gönderilir (geliştirici kota aşımı veya genel kota aşımı). Bu yapılandırmanın bir örneğini aşağıda bulabilirsiniz:

  <FaultRule name="over_quota">
  <!-- This condition catches a QuotaViolation in *any* Quota policy -->
    <Condition>(fault.name = "QuotaViolation")</Condition>
    <Step>
      <Name>developer-over-quota-fault</Name>
      <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
    </Step>
    <Step>
      <Name>global-over-quota-fault</Name>
      <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
    </Step>
  </FaultRule>
  

  Başka bir örnek için bu Apigee Topluluğu ileti dizisine göz atın.

• Tek bir türde tek bir politika kullanırken hataları işlemek için bir politika başarısız olduğunda yürütülen tek bir hata kuralı kullanmayı düşünün ve olası her bir hatayla eşleşen birden çok adım ekleyin. Bu, birden fazla FaultKural (her hata türü için bir tane) yerine tek bir FaultRule kullanarak XML'inizin verimli olmasını sağlar. Örneğin:

  <FaultRule name="raise-fault-3">
  <!-- This condition catches *any* error in the Verify-API-Key-1 policy. -->
    <Condition>(oauthV2.Verify-API-Key-1.failed = "true")</Condition>
    <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. -->
    <Step>
      <Name>Generic-Key-Fault</Name>
    </Step>
    <Step>
      <Name>Assign-Message-Raise-Fault-1</Name>
      <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
    </Step>
    <Step>
      <Name>Assign-Message-Raise-Fault-2</Name>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </Step>
  </FaultRule>
  

• Hataların ortaya çıkacağı yere (istemci tarafı <ProxyEndpoint> veya hedef taraf <TargetEndpoint>) FaultRules ekleyin. Her konumda görünen her politika için FaultRules'u ekleyin.
• FaultRules'da, istemci uygulamasına mesaj döndürebilecek her tür politikayı yürütebilirsiniz. Bunun için assignMessage politikası en iyi seçenektir. Hataları takip etmek istiyorsanız MessageLogging politikasıyla bir mesajı günlüğe kaydetmeyi de düşünebilirsiniz.
• GrowFault politikalarını FaultRules ile birlikte kullanırken, hem PromoteFault politikası hem de bir FaultRule dönüş verisi olduğunda geri gönderilen yanıt verilerini koordine edin. Örneğin, {6/}ForFault politikanız HTTP durum kodunu sıfırlıyorsa FaultRule ile durum kodunu sıfırlamayın. Olabilecek en kötü şey, varsayılan durum kodunun istemci uygulamasına döndürülmesidir.
• <DefaultFaultRule> yürütmesi:
  • Başka bir FaultRule çalışmadığında bir <DefaultFaultRule> öğesinin her zaman yürütülmesini istiyorsanız ona <Condition> eklemeyin.
  • Başka bir FaultRule yürütüldüğünde bile bir <DefaultFaultRule> öğesinin her zaman yürütülmesini istiyorsanız <AlwaysEnforce>true</AlwaysEnforce> alt öğesini ekleyin.

Merkezi ve yeniden kullanılabilir hata giderme deseni

Aşağıdaki Apigee Community yayınında, kod tekrarı olmadan merkezi hata işleme kalıbı açıklanmaktadır:

https://community.apigee.com/articles/23724/an-error-handling-pattern-for-apigee-proxies.html

FaultRules Oluşturma

FaultRule eklemek için ProxyEndpoint veya TargetEndpoint'in XML yapılandırmasını düzenlemeniz gerekir. Edge kullanıcı arayüzünü kullanarak bir API proxy'si için Geliştirme görünümünün Kod bölmesinde bu düzenlemeyi yapabilir veya ProxyEndpoint ya da TargetEndpoint'i tanımlayan XML dosyasını düzenleyebilirsiniz.

Yönetim kullanıcı arayüzünde FaultRules oluşturursanız öncelikle yürütmek istediğiniz politikaları oluşturun, ardından bunları FaultRule yapılandırmasına ekleyin. (Henüz oluşturulmamış bir politikaya referans veren bir FaultRule kaydetmeye çalışırsanız kullanıcı arayüzünde bir hata mesajı alırsınız.)

FaultRule'a politika ekleme

FaultRule'a herhangi bir politika ekleyebilirsiniz, ancak genellikle bir hata koşulu için özel yanıt mesajı oluşturmak için assignMessage politikasını kullanırsınız. AttributionMessage; yük, HTTP durum kodu, başlıklar ve neden ifadesi öğeleriyle bir HTTP yanıtı yapılandırmanıza olanak tanır.

Aşağıdaki örnekte tipik bir assignMessage politikası yapılandırması gösterilmektedir:

<AssignMessage name="fault_invalidkey">
  <Set>
      <Payload contentType="text/plain">Contact support at support@mycompany.com.</Payload>
      <StatusCode>401</StatusCode>
      <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Artık bu politikayı FaultRule'ınızda kullanabilirsiniz. FaultRule'da AddMessage politikasına ada göre nasıl referans verdiğinize dikkat edin:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>fault_invalidkey</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

Yukarıdaki yapılandırmayı dağıttığınızda API proxy'si, bir uygulama geçersiz API anahtarı sunduğunda fault_invalidkey adlı AtaMessage politikasını yürütür.

Aşağıdaki örnekte gösterildiği gibi bir FaultRule'da birden çok politika yürütebilirsiniz:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>policy1</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

Politikalar, tanımlanan sırayla yürütülür. Örneğin, MessageLogging politikasını, ExtractVariables politikasını, assignMessage politikasını veya FaultRule'daki diğer herhangi bir politikayı kullanabilirsiniz. Aşağıdaki durumlardan herhangi biri gerçekleşirse FaultRule'ın işlenmesinin hemen duracağını unutmayın:

• FaultRule'daki herhangi bir politika hataya neden oluyor
• FaultRule'daki politikalardan herhangi biri ParentFault türündedir

Bir FaultRule öğesinden döndürülen özel hata mesajını tanımlama

En iyi uygulama olarak, API'lerinizden net hata yanıtları tanımlamanız gerekir. Bu şekilde müşterilerinize tutarlı ve yararlı bilgiler sunarsınız.

Aşağıdaki assignMessage politikası örneği, bir InvalidApiKey hatasında istemciye geri gönderilen özel hata yanıtını tanımlamak için <Payload>, <StatusCode> ve <ReasonPhase> etiketlerini kullanır (önceki FaultRules örneğine bakın).

<AssignMessage name="fault_invalidkey">
  <Set>
    <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization. 
       Contact support at support@mycompany.com.</Payload>
    <StatusCode>401</StatusCode>
    <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Bu yanıt aşağıdakileri içerir:

• Hata mesajını ve destek ekibiyle iletişim kurulacak e-posta adresini içeren yük.
• Yanıtta döndürülen HTTP durum kodu.
• Hatanın kısa bir açıklaması olan neden ifadesi.

VarsayılanFaultRule Oluşturma

VarsayılanFaultRule, başka bir FaultRule tarafından açıkça ele alınmayan hatalar için bir istisna işleyici oluşturur. Tüm FaultRules'un koşulları hatayla eşleşmezse, defaultFaultRule hatayı ele alır. <DefaultFaultRule> etiketini bir ProxyEndpoint veya TargetEndpoint'in alt öğesi olarak ekleyerek varsayılan hata işlemeyi etkinleştirin.

Örneğin, aşağıdaki TargetEndpoint yapılandırması, ReturnOverviewError adlı bir politikayı çağıran birDefaultFaultRule'ı tanımlar:

<TargetEndpoint name="default">
  ...
  <FaultRules>
    ...
  </FaultRules>

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

DefaultFaultRule genellikle, teknik destek için iletişim bilgilerini içeren bir ileti gibi beklenmeyen hatalar durumunda genel bir hata mesajı döndürmek için kullanılır. Bu varsayılan yanıtın iki amacı vardır. Aynı zamanda geliştirici dostu bilgiler sağlamakla birlikte, sistemin güvenliğini ihlal etmek için kullanılabilecek arka uç URL'lerini veya diğer bilgileri de karartır.

Örneğin, genel bir hata döndürmek için aşağıdaki Atatane Politikası politikasını tanımlarsınız:

<AssignMessage name="ReturnGenericError">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
  </Set>
</AssignMessage>

Başka bir FaultRule yürütülmüş olsa bile her hatadaDefaultFaultRule'u yürütmek için <DefaultFaultRule> etiketine <AlwaysEnforce> öğesini ekleyin. DefaultFaultRule her zaman yürütülecek son FaultRule'dür:

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

DefaultFaultRule'un bir kullanımı, başka şekilde belirleyemediğinizde ortaya çıkan hata türünü belirlemektir. Örneğin, API proxy'niz belirleyemediğiniz bir hata nedeniyle başarısız oluyor. Aşağıdaki AttributionMessage politikasını çağırmak içinDefaultFaultRule'ı kullanın. Bu politika, fault.name değerini yanıttaki DefaultFaultHeader adlı bir başlığa yazar:

<AssignMessage async="false" continueOnError="false" enabled="true" name="DefaultFaultRule">
  <DisplayName>DefaultFaultRule</DisplayName>
  <Set>
    <Headers>
      <Header name="DefaultFaultHeader">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Ardından, hatanın nedenini görmek için Edge izleme aracında veya yanıtta üst bilgiyi görüntüleyebilirsiniz.

PostClientFlow'a mesaj günlük kaydı ekleme

PostClientFlow, proxy hata durumuna girdikten sonra yürütülen tek akıştır. Bu akışa yalnızca MessageLogging politikası eklenebilir. Bu politika, yanıt istemciye geri gönderildikten sonra yürütülür. MessageLogging politikasını bu akışa eklemek teknik olarak bir hata giderme işlemi olmasa da hata durumunda bilgileri günlüğe kaydetmek için kullanabilirsiniz. Proxy'nin başarılı veya başarısız olmasına bakılmaksızın yürütüleceği için Message Logging politikalarını PostClientFlow'a yerleştirebilir ve her zaman yürütülecekleri garanti edebilirsiniz.

Mevcut akıştaki politika hatalarını işleme

Şu ana kadar gösterilen örneklerin hepsinde, hata durumunun bir parçası olarak politika hatalarını işlemek için ProxyEndpoint veya TargetEndpoint'te bir FaultRule kullanılır. Bunun nedeni, bir politikanın continueOnError öğesinin varsayılan değerinin false olmasıdır. Diğer bir deyişle, bir politikada hata meydana geldiğinde kontrol hata durumuna yönlendirilir. Hata durumuna geçtikten sonra kontrolü tekrar normal ardışık düzene döndüremezsiniz ve genellikle çağrı yapan uygulamaya bir tür hata mesajı döndürürsünüz.

Bununla birlikte, bir politika için continueOnError öğesini true olarak ayarlarsanız kontrol mevcut akışta kalır ve ardışık düzendeki bir sonraki politika, hataya neden olan politikadan sonra yürütülür. Mevcut akıştaki hatayı ele almanın avantajı, isteğin işlenmesini tamamlamak için hatadan kurtulmanın bir yolunun olmasıdır.

Aşağıda, continueOnError öğesi true: olarak ayarlanmış verify-api-key adlı bir VerifyAPIKey politikası gösterilmektedir.

<VerifyAPIKey async="false" continueOnError="true" enabled="true" name="verify-api-key">
  <DisplayName>Verify API Key</DisplayName>
  <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

API anahtarı eksik veya geçersizse VerifyAPIKey politikası oauthV2.verify-api-key.failed değişkenini true olarak ayarlar ancak işleme mevcut akışta devam eder.

Daha sonra, ProxyEndpoint'in PreFlow'unda bir adım olarak VerificationAPIKey politikasını ekleyin:

<ProxyEndpoint name="default">
  ...
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>verify-api-key</Name>
      </Step>
      <Step>
        <Name>FaultInFlow</Name>
        <Condition>(oauthV2.verify-api-key.failed = "true")</Condition>
      </Step>
    </Request>
    <Response/>
  </PreFlow>      
</ProxyEndpoint>  

PreFlow'daki sonraki adımın, hata olup olmadığını test etmek için bir koşulu nasıl kullandığına dikkat edin. VerifAPIKey politikasında bir hata oluştuysa FaultInFlow politikası adlı politika yürütülür. Aksi takdirde FaultInFlow politikası atlanır. FaultInFlow politikası; hatayı günlüğe kaydetme, hatayı düzeltmeye çalışma veya başka işlemler yapma gibi birçok şey yapabilir.

PromoteFault politikasını kullanarak hata tetikleme

Bir hata tetiklemek için akışta istediğiniz zaman GrowFault politikasını kullanabilirsiniz. Bir {6/}Fault politikası yürütüldüğünde mevcut akışı sonlandırır ve kontrolü hata durumuna aktarır.

GrowFault politikası, başka bir politikanın tespit edemeyebileceği belirli bir koşulu test etmek amacıyla kullanılır. Yukarıdaki örnekte, koşul karşılandığında FaultInFlow politikasının yürütülmesine neden olan bir PreFlow <Step> etiketine <Condition> etiketi eklediniz. FaultInFlow bir çıkarmaFault politikasıysa hata durumuna aktarımları kontrol edin. Alternatif olarak, FaultRules'daki hataları ayıklamak ve test etmek için bir akışa ParentFault politikası ekleyebilirsiniz.

Bir {6/}Fault politikası hata tetiklediğinde, bunu işlemek için aşağıdaki FaultRule ve koşulu kullanabilirsiniz:

<FaultRule name="raisefault_rule">
  <Step>
    <Name>{policy_name}</Name>
  </Step>
  <Condition>(fault.name = "RaiseFault")</Condition>
</FaultRule>

Koşulun RaiseFault adlı bir hata için test yaptığını unutmayın. PromoteFault politikası, fault.name değerini her zaman RaiseFault olarak ayarlar.

Hedef sunucudan HTTP hata kodlarının özel olarak işlenmesi

Önceki bölümlerde gösterilen örnekler, politikalar tarafından oluşturulan hatalar için geçerlidir. Bununla birlikte, hedef sunucudan döndürülen HTTP hataları anlamına gelen aktarım düzeyindeki hatalar için özel bir yanıt da oluşturabilirsiniz. HTTP hatasından alınan yanıtı kontrol etmek için TargetEndpoint'i HTTP yanıt kodlarını işleyecek şekilde yapılandırın.

Varsayılan olarak Edge, 1xx-3xx aralığındaki HTTP yanıt kodlarını "başarılı", 4xx-5xx aralığındaki HTTP yanıt kodlarını ise "başarısız" olarak değerlendirir. Diğer bir deyişle, arka uç hizmetinden 4xx-5xx HTTP yanıt koduna sahip herhangi bir yanıt otomatik olarak hata durumunu çağırır ve ardından, doğrudan istekte bulunan istemciye bir hata mesajı döndürür.

Tüm HTTP yanıt kodları için özel işleyiciler oluşturabilirsiniz. Örneğin, 4xx-5xx aralığındaki tüm HTTP yanıt kodlarını "failure" (hata) yerine yalnızca 5xx olarak işlemeyi veya 400 ve 500 HTTP yanıt kodları için özel hata mesajları döndürmeyi tercih edebilirsiniz.

Bir sonraki örnekte, TargetEndpoint'i varsayılan HTTP kodlarıyla birlikte 400 ve 500 HTTP yanıt kodlarını başarılı olarak değerlendirecek şekilde yapılandırmak için success.codes özelliğini kullanacaksınız. Bu kodları başarılı olarak değerlendiren TargetEndpoint, hata durumunu çağırmak yerine yanıt mesajının işlenmesini devralır:

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <Properties>
          <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Bu örnekte görebileceğiniz gibi, success.codes özelliğini bir değer aralığına ayarlamak için joker karakterler kullanabilirsiniz.

success.codes özelliği ayarlanırsa varsayılan değerlerin üzerine yazılır. Bu nedenle, HTTP kodu 400'ü varsayılan başarı kodları listesine eklemek isterseniz bu özelliği şu şekilde ayarlayın:

<Property name="success.codes">1xx,2xx,3xx,400</Property>

Ancak, yalnızca HTTP kodu 400'ün başarılı kod olarak işlenmesini istiyorsanız özelliği şu şekilde ayarlayın:

<Property name="success.codes">400</Property>

Artık istekte bulunan uygulamaya özelleştirilmiş bir yanıt mesajı döndürmek için 400 ve 500 HTTP yanıt kodları için özel işleyiciler tanımlayabilirsiniz. Aşağıdaki TargetEndpoint, HTTP 400 ve 500 yanıt kodlarını işlemek için ReturnError adlı politikayı kullanır:

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <Name>ReturnError</Name>
        <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition>
      </Step>
    </Response>
  </PreFlow>

  <HTTPTargetConnection>
    <Properties>
      <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Bu TargetEndpoint yapılandırması, TargetEndpoint 400 veya 500 HTTP yanıt koduyla karşılaştığında ReturnError adlı politikanın yanıtı işlemesine neden olur.

Hata sınıflandırması

API Hizmetleri, hataları aşağıdaki kategoriler ve alt kategorilerde düzenler.

Bir hatanın yanında her zaman hatanın nedenine dair bir metin açıklaması yer alır. Sistem bir hata bildirdiğinde, sorun gidermeye yardımcı olmak için bir dizi özellik doldurulur. Hata aşağıdaki bilgileri içerir:

• Neden
• Kullanıcı tanımlı özel özellikler