Hataları işleme

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

API proxy'leri uygulamalardan gelen istekleri işlerken 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.

Bir istemci uygulaması API proxy'sini çağırdıktan sonra bir hata oluştuğunda istemciye bir hata mesajı döndürülür. Varsayılan olarak, istemci genellikle ayrıntı veya rehberlik içermeyen, anlaşılması zor bir hata mesajı alır. Ancak varsayılan hata mesajlarını daha faydalı özel mesajlarla değiştirmek ve hatta bunları ek HTTP üstbilgileri gibi öğelerle zenginleştirmek istiyorsanız Edge'de özel hata işleme ayarlamanız gerekir.

Özel hata işleme, hata oluştuğunda mesaj günlüğü oluşturma gibi işlevler eklemenize de olanak tanır.

API proxy'lerinizde özel hata işlemeyi uygulama konusuna geçmeden önce hataların nasıl oluştuğunu ve API proxy'lerin bunlara nasıl tepki verdiğini anlamak faydalı olacaktır.

Videolar

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

Hatalar nasıl oluşur?

Öncelikle hataların nasıl oluştuğunu 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 verir:

• Bir politika hata veriyor. Örneğin, bir API çağrısı süresi dolmuş bir anahtar gönderirse VerifyAPIKey politikası otomatik olarak hata verir. API çağrılarının sayısı belirli bir sınırı aşarsa Quota politikası veya SpikeArrest politikası hata verir. (Politikaların oluşturabileceği hata türleri için Politika hatası referansı'na bakın).
• API proxy'si mesaj akışında yönlendirme hatası gibi bir sorun var.
• Protokol düzeyindeki hatalar, TLS/SSL hataları veya kullanılamayan hedef hizmet nedeniyle HTTP hatası gibi bir arka uç hatası vardır.
• Sistem düzeyinde bir hata (ör. bellek yetersizliği istisnası) oluştuğunda

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

Özel hatalar

Otomatik hata oluşmayan durumlarda özel bir hata oluşturmak isteyebilirsiniz. Örneğin, bir yanıtta "kullanılamıyor " kelimesi varsa veya HTTP durum kodu 201'den büyükse. Bunu, API proxy akışında uygun bir yere RaiseFault politikası ekleyerek yapabilirsiniz.

RaiseFault politikasını, diğer tüm politikaları eklediğiniz şekilde bir API proxy akışına ekleyebilirsiniz. Aşağıdaki proxy yapılandırması örneğinde, Raise-Fault-1 politikası TargetEndpoint yanıtına eklenir. Hedef hizmetten gelen yanıtta "unavailable" (kullanılamıyor) kelimesi varsa RaiseFault politikası yürütülür ve hata verilir.

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

Bu yalnızca özel hatalar oluşturabileceğinizi göstermek içindir. RaiseFault politikası hakkında daha ayrıntılı bilgiyi FaultRules ve RaiseFault politikası bölümünde bulabilirsiniz.

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

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

Hata oluştuğunda API proxy'lerinin yaptığı işlemler

Bir proxy hata verdiğinde neler olur?

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

Bir API proxy'si, nasıl oluştuğundan bağımsız olarak bir hatayla karşılaştığında normal akış işlem hattından çıkar, hata durumuna girer ve istemci uygulamasına bir hata mesajı döndürür. API proxy'si hata durumuna girdikten sonra işlemeyi normal akış işlem hattına geri döndüremez.

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

1. API anahtarını doğrulama
2. Kota
3. JSON'dan XML'ye

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

FaultRule'ları kontrol etme

Hata durumunda, API proxy'leri istemci uygulamasına varsayılan bir hata mesajı döndürmeden önce API proxy yapılandırmasında aşağıdaki öğelerin (sırayla) bulunup bulunmadığını da 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 bir <FaultRules> bölümü.
2. Aşağıdaki durumlarda varsayılan hata mesajını tetikleyen bir <DefaultFaultRule> bölümü:
   • <FaultRules> tanımlanmamış.
   • Mevcut <FaultRules> yürütülmez.
   • <AlwaysEnforce> öğesi doğru olarak ayarlanır.

API proxy'si, özünde özel bir hata mesajı döndürme ve başka bir mantığı tetikleme fırsatı sunar. Proxy bu bölümlerin ikisini de bulamazsa veya bu bölümler mevcut olmasına rağmen özel bir hata tetiklenmezse proxy, kendi Edge tarafından oluşturulan varsayılan mesajını gönderir.

Basit hata işleme örneği

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

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 anlamayabilir de. Ayrıca, birçok varsayılan hata daha ince ayrıntılıdır ve çözülmesi daha zordur.

Bir API geliştiricisi olarak, bu mesajı nihayetinde hata mesajını alacak kişinin (iOS uygulama geliştiricisi veya kendi hata mesajı biçimi şartlarına sahip bir dahili test grubu) ihtiyaçlarını karşılayacak şekilde değiştirmek sizin sorumluluğunuzdadır.

Bu hatayı işlemek için nasıl özel bir hata mesajı oluşturacağınıza dair 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 ve isteğe bağlı HTTP başlıklarını (ör. durum kodu ve neden ifadesi) ayarlayabilen AssignMessage politikası gibi herhangi bir politika türünü kullanabilirsiniz. Bu işlem için Assign Message (Mesaj Atama) idealdir. Bu özellik, ileti yükünü kontrol etmenize, farklı bir HTTP durum kodu ayarlamanıza, farklı bir HTTP neden ifadesi ayarlamanıza ve HTTP üst bilgileri eklemenize olanak tanır.

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

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

Aşağıda, AssignMessage politikasının bir örneği verilmiştir:

• JSON mesajı döndürür.
• Bir HTTP durum kodu ayarlar (911, sahip olduğunuz esnekliği göstermek için açıkça var olmayan bir durum kodudur). Durum kodu, HTTP üstbilgisinde görünür.
• Bir HTTP neden ifadesi ayarlar (bu eksik API anahtarı hatası için varsayılan "Yetkisiz" neden ifadesinin yerine). Neden ifadesi, HTTP başlığındaki durum kodunun yanında görünür.
• invalidKey adlı yeni bir HTTP üst bilgisi oluşturur ve bu üst bilgiyi 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 uygulamasına 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 saçma ama neyin mümkün olduğunu gösteriyor. En azından artık mesajı alan geliştirici, sorgu parametresi olarak bir API anahtarı eklemeyi unuttuğunu biliyor.

Peki bu politika nasıl uygulanır? Sonraki bölümde bu konuyla ilgili bilgiler verilmektedir.

2. Politikayı tetikleyecek <FaultRule> öğesini oluşturun.

Proxy yapılandırmasının <ProxyEndpoint> veya <TargetEndpoint> bölümlerine, bir veya daha fazla <FaultRule> bölümü içeren bir <FaultRules> XML bloğu eklersiniz. Her FaultRule, ele almak istediğiniz farklı bir hatayı temsil eder. Bu basit örnekte, neyden oluştuğunu göstermek için yalnızca bir FaultRule kullanacağız.

Ayrıca, FaultRule'larınızdan 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:

• FaultRule'lar ProxyEndpoint'te tanımlanır. Bu önemlidir. ProxyEndpoint'e ve TargetEndpoint'e FaultRule yerleştirme hakkında daha fazla bilgiyi ilerleyen bölümlerde bulabilirsiniz.
• <Name> - Yürütülecek politikanın adı. Ad, daha önce politika örneğinde gösterildiği gibi, üst öğedeki politikanın 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 çok FaultRule varsa Edge, doğru olan ilk FaultRule'u yürütür. (Önemli: Birden fazla FaultRule ve yürütme mantığı bölümünde açıklandığı gibi, FaultRule'ların değerlendirildiği sıra (yukarıdan aşağıya veya aşağıdan yukarıya) TargetEndpoint ile ProxyEndpoint arasında farklılık gösterir.) Koşul eklemezseniz FaultRule otomatik olarak doğru olur. Ancak bu en iyi uygulama değildir. Her FaultRule'un kendi koşulu olmalıdır.

• <DefaultFaultRule> - Özel bir FaultRule yürütülmezse <DefaultFaultRule> yürütülür ve şifreli varsayılan Edge tarafından oluşturulan mesaj yerine daha genel bir özel mesaj gönderilir. Bir <DefaultFaultRule>, <Condition> de içerebilir ancak çoğu durumda son çare olarak ne olursa olsun yürütülmesini istediğiniz için bunu dahil etmezsiniz.

  DefaultFaultRule, genellikle beklenmedik hatalar için genel bir hata mesajı döndürmek üzere kullanılır. Örneğin, teknik destek için iletişim bilgilerini içeren bir ileti. Bu varsayılan yanıt, geliştirici dostu bilgiler sağlamanın yanı sıra arka uç URL'lerini veya sistemi tehlikeye atmak için kullanılabilecek diğer bilgileri de karartır.

Birden çok FaultRule ve yürütme mantığı

Basit hata işleme örneği bölümünde, tek bir FaultRule ve koşul içeren basit bir örnek kullandık. Gerçek dünyadaki bir API projesinde, oluşabilecek tüm olası hatalarla birlikte hem <ProxyEndpoint> hem de <TargetEndpoint> içinde birden fazla FaultRule ve bir DefaultFaultRule olması muhtemeldir. Ancak sonuç olarak, bir API proxy'si hata durumuna geçtiğinde yalnızca bir FaultRule yürütülür.

Bu bölümde, Edge'in FaultRule'ları işlerken kullandığı mantık açıklanmaktadır. Bu mantık, yürütülecek tek bir FaultRule'a nasıl ulaşıldığından, FaultRule'ları tetiklendiğinde "içteki" adım koşullarının nasıl işlendiğine kadar her şeyi kapsar. Bu bölümde, <ProxyEndpoint> ve <TargetEndpoint> içinde ne zaman FaultRule tanımlanacağıyla ilgili rehberlik de sağlanmakta ve FaultRule ile RaiseFault politikası arasındaki ilişki açıklanmaktadır.

FaultRules yürütme

Kısaca, bir API proxy'si hata durumuna geçtiğinde Edge'in kullandığı mantık şöyledir: 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 nerede oluştuğuna bağlı olarak ProxyEndpoint veya TargetEndpoint'teki FaultRule'ları değerlendirir:
   • ProxyEndpoint: Edge, yapılandırma XML'sindeki en alttaki <FaultRule> ile başlar ve yukarı doğru ilerleyerek her bir <FaultRule>'nin <Condition>'ünü (<Step> koşulları değil, "dış" koşul) değerlendirir.
   • TargetEndpoint: Edge, yapılandırma XML'sindeki en üstteki <FaultRule> ile başlar ve aşağı doğru ilerleyerek her bir <FaultRule>'nin <Condition>'ünü (<Step> koşulları değil, "dış" koşul) değerlendirir.
2. Koşulu doğru olan ilk FaultRule'u yürütür. Bir FaultRule'da koşul 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 doğru sırayla değerlendirilir. Koşulsuz adımlar otomatik olarak yürütülür (politikalar yürütülür) ve <Condition> koşulu "doğru" olarak değerlendirilen adımlar yürütülür ("yanlış" olarak değerlendirilen koşullar yürütülmez).

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

3. Herhangi bir FaultRule yürütülmezse Edge, varsa <DefaultFaultRule> öğesini yürütür.

Aşağıda satır içi yorumlar içeren örnekler verilmiştir.

ProxyEndpoint yürütme

ProxyEndpoint FaultRule'ların değerlendirilmesi aşağıdan yukarıya doğru yapılır. Bu nedenle, aşağıdaki örnekte son FaultRule'dan başlayarak yukarı doğru okuyun. 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

Hedef uç nokta FaultRule'larının değerlendirilmesi yukarıdan aşağıya doğru yapılır. Bu nedenle, aşağıdaki örnekte ilk FaultRule'dan başlayarak aşağı doğru okuyun. 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 de görebileceğiniz gibi, hatanın ProxyEndpoint'te mi yoksa TargetEndpoint'te mi oluştuğuna bağlı olarak FaultRule'ları yerleştirme sıranız önemlidir.

Örneğin:

Dahil edilecek politikalar

FaultRule'daki politikaları Steps'e yerleştirerek yürütebilirsiniz. Örneğin, istemci uygulamasına yanıtı biçimlendirmek için AssignMessage politikası yürütebilir, ardından MessageLogging politikası ile mesajı günlüğe kaydedebilirsiniz. Politikalar, XML'de yukarıdan aşağıya doğru olmak üzere eklediğiniz sırayla yürütülür.

Hata kuralları YALNIZCA hata durumunda tetiklenir (continueOnError hakkında)

Başlıkta kendimizi tekrar ediyor gibi görünebiliriz ancak bir API proxy'sinin hata durumuna girmesine neden olan bir proxy hatasıyla ilgili olarak dikkat edilmesi gereken belirli bir nüans vardır. Daha doğrusu, hata durumuna girmemesi: Bir politikadaki continueOnError özelliği.

Özetlemek gerekirse: Bir API proxy'si, <FaultRules> ve <DefaultFaultRule> değerlerini yalnızca proxy hata durumuna girmişse değerlendirir. Bu nedenle, bir FaultRule koşulu doğru olarak değerlendirilse bile proxy hata durumunda değilse tetiklenmez.

Ancak, bir hata oluştuğu ve proxy'nin hata durumuna girmediği bir örneği aşağıda bulabilirsiniz. Herhangi bir politikada, üst öğede continueOnError adlı bir özellik ayarlayabilirsiniz. Bu özellik, politika başarısız olursa vekil sunucunun hata durumuna girip girmeyeceğini belirlediği için hata işleme açısından çok önemlidir. Çoğu durumda, varsayılan continueOnError="false" değerini korumak istersiniz. Bu değer, politika başarısız olursa proxy'yi hata durumuna geçirir ve özel hata işleme tetiklenir. Ancak continueOnError="true" (örneğin, bir hizmet çağrısının başarısız olmasının proxy yürütmesini 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ında hataların günlüğe kaydedilmesi hakkında bilgi için Mevcut akışta politika hatalarını işleme başlıklı makaleyi inceleyin.

FaultRule'ların tanımlanacağı yerler: ProxyEndpoint veya TargetEndpoint

Bir API proxy'si hata yaşadığında hata <ProxyEndpoint> (istemci uygulamasından gelen istek veya istemci uygulamasına verilen yanıt) ya da <TargetEndpoint> (hedef hizmete yapılan istek veya hedef hizmetten gelen yanıt) içinde oluşur. Edge, FaultRules'u hatanın oluştuğu yerde arar.

Örneğin, bir hedef sunucu kullanılamıyorsa (HTTP durum kodu 503), API proxy'si <TargetEndpoint> yanıtında hata durumuna geçer ve normal API proxy'si akışı <ProxyEndpoint> ile devam etmez. FaultRule'ları yalnızca <ProxyEndpoint> içinde tanımladıysanız bu hata işlenmez.

Başka bir örnek gösterelim. <ProxyEndpoint> yanıtındaki bir RaiseFault politikası hatayı tetiklerse <TargetEndpoint> içindeki bir FaultRule yürütülmez.

FaultRules ve RaiseFault politikası

Hata kuralları ve RaiseFault politikası, hata işlemeyi gerçekleştirmenin alternatif yolları gibi görünebilir ve bazı açılardan bu doğrudur. Ancak birlikte de çalışırlar. Bu bölümde, ikisi arasındaki ilişki açıklanmaktadır. Bu ilişkiyi anlamak, özellikle her ikisini de kullanmak istiyorsanız hata işleme biçiminizi tasarlamanıza yardımcı olur.

Özet olarak:

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

• RaiseFault politikası, aksi takdirde hata oluşmayacakken bir API proxy'sini hata durumuna geçirmenin bir yoludur.

  Örneğin, hedef hizmetten gelen yanıttaki HTTP durum kodu 200'den büyükse hata oluşturmak istiyorsanız yanıt akışınıza bir RaiseFault 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>

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

RaiseFault politikası bir hatayı tetiklediğinde ne olur? Bu durumda proxy hata durumuna geçer ve FaultRule yürütülür. İşler burada biraz karışabilir. RaiseFault politikası bir hata mesajı döndürürse ve bir FaultRule tetiklenip hata mesajı döndürürse istemci uygulamasına ne döndürülür?

• FaultRule veya DefaultFaultRule, RaiseFault politikası yürütüldükten sonra çalıştırıldığından FaultRule yanıt verileri önceliklidir.
• RaiseFault politikası yanıt verileri (durum kodu, neden ifadesi veya mesaj yükü), bu veriler FaultRule veya DefaultFaultRule tarafından ayarlanmamışsa kullanılır.
• Hem RaiseFault politikası hem de FaultRule özel HTTP üstbilgileri eklerse her ikisi de yanıta dahil edilir. Yinelenen üstbilgi adları, birden çok değer içeren bir üstbilgi oluşturur.

Aşağıda, RaiseFault politikası ve FaultRule tarafından ayarlananlar ile istemci uygulamasına döndürülenler hakkında bir örnek verilmiştir. Ö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'un yürütülmesinin anahtarıdır. FaultRule koşullarını, Edge'deki diğer koşullarla (ör. koşullu akışlar veya RaiseFault koşulları) aynı şekilde oluşturursunuz.

Bu bölümün geri kalanını bağlama oturtmak için, dışta bir FaultRule koşulu ve içte bir Step koşulu olan ö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 özgü 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 hatayı bir koşulda 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ğıdakilerde hata adı FailedToResolveAPIKey'dır. Bu durumda, fault.name adlı bir akış değişkeni FailedToResolveAPIKey değerine ayarlanır.

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

Bu nedenle koşul şöyle görünür:

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

Politika hatalarının listesi için Politika hatası referansı'na bakın.

{policy_namespace}.{policy_name}.failed

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

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

Kullanılabilen diğer değişkenler

Bir API proxy'si hata durumuna geçtiğinde koşullarda kullanılabilen tek değişkenler şunlardır:

• Başarısız olan politikanın değişkenleri.
• Hatanın oluştuğu sırada mevcut olan HTTP mesajı değişkenleri. Örneğin, yanıtta bir hata oluşursa <TargetEndpoint> içindeki bir FaultRule, HTTP verilerini (response.status.code, message.content, error.content vb.) kullanabilir. Alternatif olarak, kota politikası başarısız olursa ratelimit.{quota_policy_name}.exceed.count değişkenini kullanabilirsiniz. Hangi değişkenlerin ve HTTP verilerinin kullanılabildiğini belirlemek için izleme aracını ve politika referans konularını kullanın.

Daha fazla bilgi

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

• Hatalar: Politika hatası referansı
• Değişkenler: Değişken referansı ve her politikayla kullanılabilen değişkenler için ayrı politika referans sayfalarına bakın.

Hata işleme ile ilgili en iyi uygulamalar

Hata işleme, API proxy'si geliştirme için önemli bir mimari tasarım görevidir. Hataları nasıl ve ne zaman ele alacağınızı belirlemek, hata mesajlarının ne söyleyeceğini tespit etmek ve hata mesajı biçimlerini tasarlamak için zaman ayırmak önemlidir. Bu konuları netleştirdikten sonra (veya netleştirirken) hata işleme uygulamanızda size yardımcı olması için aşağıdaki en iyi uygulamalardan yararlanın.

Hata işlemeyi tasarlama ve oluşturmayla ilgili bazı en iyi uygulamaları aşağıda bulabilirsiniz:

• Her FaultRule için bir "outer" <Condition> (<Step> öğesinin kardeşi) sağlayın. Dış koşulu olmayan hata kuralları otomatik olarak doğru olarak değerlendirilir. "İç" adım koşulları, bir FaultRule'un doğru mu yanlış mı olduğunu belirlemek için kullanılmaz. Adım koşulları yalnızca Edge, bunları içeren FaultRule'u yürüttükten sonra değerlendirilir. Bir FaultRule'da, her biri bir adım koşuluna sahip olan Assign Message (veya diğer) politikalarıyla birden fazla adım olması normaldir.

• Aynı türdeki birden fazla politikada (ör. birden fazla kota politikası) hataları işlemek için almanız muhtemel her politika hatası için bir FaultRule oluşturun. Örneğin, kota politikalarındaki olası her hata için bir FaultRule oluşturun. Örneğin, QuotaViolation, InvalidMessageWeight, StartTimeNotSupported. (Politika hataları için Politika hatası referansı'na bakın. İşlenmesi gereken ek hatalar keşfettikçe daha sonra geri dönüp bunları FaultRules'unuza ekleyebilirsiniz. Yinelemeli bir yaklaşım benimseyebilirsiniz ancak bu durumda proxy'nin yeniden dağıtılması gerekir.) Bu yaklaşım, hangi politika tarafından oluşturulduğuna bakılmaksızın aynı türdeki hatayı yakalamanıza olanak tanır. Bu da FaultRules XML'nizi verimli hale getirir.

  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 iki politikayla hem bireysel geliştirici kotasını hem de genel kotayı zorunlu kılıyorsanız "dış" FaultRule koşulunuzu QuotaViolation hatası (her iki durumda da kota aşıldığında oluşturulur) tetiklenecek şekilde ayarlayın. Ardından, her iki kota politikanızdaki exceed.count değişkenlerini değerlendirmek için adım koşullarını ayarlayın. İstemciye yalnızca ilgili hata gönderilir (geliştirici kotası aşımı veya genel kota aşımı). Bu yapılandırmanın bir örneğini aşağıda görebilirsiniz:

  <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 Community ileti dizisine bakın.

• Tek bir türden politika kullanırken hataları işlemek için bu politika başarısız olduğunda yürütülen tek bir hata kuralı kullanmayı ve olası her hatayla eşleşen birden fazla adım eklemeyi düşünebilirsiniz. Bu, her hata türü için bir FaultRule olmak üzere birden fazla FaultRule yerine tek bir FaultRule kullanarak XML'nizin 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 oluşacağı yerlere (istemci tarafı <ProxyEndpoint> veya hedef tarafı <TargetEndpoint>) FaultRule'lar ekleyin. Her konumda görünen her politika için FaultRule'ları ekleyin.
• FaultRules'da, istemci uygulamasına mesaj döndürebilen her tür politikayı yürütebilirsiniz. Bu işlem için AssignMessage politikası idealdir. Hataları takip etmek istiyorsanız MessageLogging politikası ile mesaj kaydetmeyi de düşünebilirsiniz.
• RaiseFault politikalarını FaultRules ile birlikte kullanırken hem RaiseFault politikası hem de bir FaultRule veri döndürdüğünde geri gönderilen yanıt verilerini koordine edin. Örneğin, RaiseFault politikanız HTTP durum kodunu sıfırlıyorsa FaultRule'un durum kodunu sıfırlamasına izin vermeyin. En kötü ihtimalle, varsayılan durum kodu istemci uygulamasına döndürülür.
• <DefaultFaultRule> execution:
  • Başka bir FaultRule yürütülmediğinde <DefaultFaultRule> öğesinin her zaman yürütülmesini istiyorsanız <Condition> eklemeyin.
  • Başka bir FaultRule yürütülse bile <DefaultFaultRule> öğesinin her zaman yürütülmesini istiyorsanız <AlwaysEnforce>true</AlwaysEnforce> alt öğesini ekleyin.

Merkezi, yeniden kullanılabilir hata işleme deseni

Aşağıdaki Apigee topluluk gönderisinde, kod tekrarı olmadan merkezi hata işleme için bir kalıp açıklanmaktadır:

Apigee proxy'leri için hata işleme kalıbı

FaultRule oluşturma

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

Yönetim kullanıcı arayüzünde FaultRule oluşturursanız önce 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'u kaydetmeye çalışırsanız kullanıcı arayüzünde hata alırsınız.)

FaultRule'a politika ekleme

FaultRule'a herhangi bir politika yerleştirebilirsiniz ancak genellikle bir hata durumu için özel bir yanıt mesajı oluşturmak üzere AssignMessage politikası kullanılır. AssignMessage, yük, HTTP durum kodu, üstbilgiler ve neden ifadesi öğeleri içeren 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'unuzda kullanabilirsiniz. FaultRule'da AssignMessage politikasını ada göre nasıl referanslandırdığınıza 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, bir uygulama geçersiz bir API anahtarı sunduğunda API proxy'si fault_invalidkey adlı AssignMessage politikasını yürütür.

Aşağıdaki örnekte gösterildiği gibi, bir FaultRule'da birden fazla politika uygulayabilirsiniz:

<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ı, ExtractVariables politikası, AssignMessage politikası veya FaultRule'daki diğer politikaları kullanabilirsiniz. Aşağıdaki durumlardan herhangi biri gerçekleşirse FaultRule işleme işleminin hemen durdurulacağını unutmayın:

• FaultRule'daki herhangi bir politika hataya neden oluyorsa
• FaultRule'daki politikalardan herhangi biri RaiseFault türündedir.

Bir FaultRule'dan 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 sayede, müşterilerinize tutarlı ve faydalı bilgiler sunabilirsiniz.

Aşağıdaki AssignMessage politikası örneğinde, <Payload>, <StatusCode> ve <ReasonPhase> etiketleri kullanılarak InvalidApiKey hatası durumunda istemciye geri gönderilen özel hata yanıtı tanımlanı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ıtta şunlar yer alır:

• Hata mesajını ve destek ekibiyle iletişime geçmek için kullanılacak e-posta adresini içeren yük.
• Yanıtla döndürülen HTTP durum kodu.
• Hatanın kısa bir açıklaması olan neden ifadesi.

Varsayılan Hata Kuralı Oluşturma

DefaultFaultRule, başka bir FaultRule tarafından açıkça işlenmeyen tüm hatalar için bir istisna işleyici görevi görür. Tüm FaultRule'ların koşulları hatayla eşleşmezse DefaultFaultRule hatayı işler. <DefaultFaultRule> etiketini ProxyEndpoint veya TargetEndpoint'in alt öğesi olarak ekleyerek varsayılan hata işlemeyi etkinleştirin.

Örneğin, aşağıdaki TargetEndpoint yapılandırması, ReturnGenericError adlı bir politikayı çağıran bir DefaultFaultRule 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 beklenmedik hatalar için genel bir hata mesajı döndürmek amacıyla kullanılır. Örneğin, teknik destek için iletişim bilgilerini içeren bir mesaj döndürmek amacıyla kullanılabilir. Bu varsayılan yanıt, geliştirici dostu bilgiler sağlamanın yanı sıra arka uç URL'lerini veya sistemi tehlikeye atmak için kullanılabilecek diğer bilgileri karartmak gibi iki amaca hizmet eder.

Örneğin, genel bir hata döndürmek için aşağıdaki AssignMessage 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 zaten yürütülmüş olsa bile her hata için DefaultFaultRule'u yürütmek üzere <AlwaysEnforce> öğesini <DefaultFaultRule> etiketine ekleyin. DefaultFaultRule her zaman yürütülecek son FaultRule'dur:

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

DefaultFaultRule'un bir kullanım alanı, aksi takdirde belirleyemeyeceğiniz bir hata türünü belirlemektir. Örneğin, API proxy'niz belirleyemediğiniz bir hata nedeniyle başarısız oluyor. Aşağıdaki AssignMessage politikasını çağırmak için DefaultFaultRule'u kullanın. Bu politika, yanıttaki fault.name değerini DefaultFaultHeader adlı bir üstbilgiye 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, hataya neyin neden olduğunu görmek için Edge izleme aracında veya yanıtta başlığı görüntüleyebilirsiniz.

PostClientFlow'a mesaj 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 hata işleme olmasa da hata durumunda bilgileri günlüğe kaydetmek için bu politikayı kullanabilirsiniz. Proxy'nin başarılı olup olmamasından bağımsız olarak yürütüldüğünden, PostClientFlow'a ileti günlüğü politikaları yerleştirebilir ve bunların her zaman yürütüleceğini garanti edebilirsiniz.

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

Şimdiye kadar gösterilen örneklerin tümünde, hata durumunun bir parçası olarak politika hatalarını işlemek için ProxyEndpoint veya TargetEndpoint üzerinde bir FaultRule kullanılır. Bunun nedeni, bir politikanın continueOnError öğesinin varsayılan değerinin false olmasıdır. Bu, bir politikada hata oluştuğunda kontrolün hata durumuna yönlendirildiği anlamına gelir. Hata durumuna geçtikten sonra kontrolü normal işlem hattına döndüremezsiniz ve genellikle çağıran uygulamaya bir hata mesajı döndürürsünüz.

Ancak bir politika için continueOnError öğesini true olarak ayarlarsanız kontrol mevcut akışta kalır ve işlem hattındaki bir sonraki politika, hataya neden olan politikadan sonra yürütülür. Hatayı mevcut akışta ele almanın avantajı, isteğin işlenmesini tamamlamak için hatadan kurtulmanın bir yolunu bulabilmenizdir.

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

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

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

Ardından, ProxyEndpoint'in PreFlow'una bir adım olarak VerifyAPIKey politikasını eklersiniz:

<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 bir sonraki adımda, bir hatanın varlığını test etmek için nasıl koşul kullanıldığına dikkat edin. VerifAPIKey politikasında bir hata oluşursa FaultInFlow 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 bir işlem gerçekleştirme gibi birçok şey yapabilir.

RaiseFault politikasını kullanarak hata tetikleme

Bir akışta istediğiniz zaman RaiseFault politikasını kullanarak hata tetikleyebilirsiniz. RaiseFault politikası yürütüldüğünde mevcut akış sonlandırılır ve kontrol hata durumuna aktarılır.

RaiseFault politikasının kullanım alanlarından biri, başka bir politikanın algılayamayabileceği belirli bir koşulu test etmektir. Yukarıdaki örnekte, bir <Condition> etiketi eklediniz. Bu etiket, koşul karşılandığında FaultInFlow politikasının yürütülmesine neden olan bir PreFlow <Step> etiketine eklenmiştir. FaultInFlow bir RaiseFault politikasıysa kontrol hata durumuna aktarılır. Alternatif olarak, bir akışa RaiseFault politikası ekleyerek FaultRule'larınızı hata ayıklama ve test etme işlemlerini gerçekleştirebilirsiniz.

RaiseFault politikası bir hatayı tetiklediğinde, hatayı işlemek için aşağıdaki FaultRule ve koşulunu 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. RaiseFault politikası, fault.name değerini her zaman RaiseFault olarak ayarlar.

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

Önceki bölümlerde gösterilen örnekler, politikalardan kaynaklanan hatalar için geçerlidir. Ancak, 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 gelen yanıtı kontrol etmek için bir TargetEndpoint'i HTTP yanıt kodlarını işleyecek şekilde yapılandırın.

Edge, varsayılan olarak 1xx-3xx aralığındaki HTTP yanıt kodlarını "başarı", 4xx-5xx aralığındaki HTTP yanıt kodlarını ise "başarısızlık" olarak değerlendirir. Bu, arka uç hizmetinden gelen ve HTTP yanıt kodu 4xx-5xx olan tüm yanıtların otomatik olarak hata durumunu çağırdığı ve ardından doğrudan istekte bulunan istemciye bir hata mesajı döndürdüğü anlamına gelir.

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ı "başarısızlık" olarak değerlendirmek istemeyip yalnızca 5xx kodlarını değerlendirmek isteyebilirsiniz veya 400 ve 500 HTTP yanıt kodları için özel hata mesajları döndürmek isteyebilirsiniz.

Sonraki örnekte, success.codes özelliğini kullanarak TargetEndpoint'i, varsayılan HTTP kodlarının yanı sıra 400 ve 500 HTTP yanıt kodlarını başarı olarak değerlendirecek şekilde yapılandırıyorsunuz. 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ğinin ayarlanması, varsayılan değerlerin üzerine yazar. Bu nedenle, varsayılan başarı kodları listesine HTTP kodu 400'ü eklemek istiyorsanız 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ı kodu olarak değerlendirilmesini istiyorsanız özelliği şu şekilde ayarlayın:

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

Artık HTTP yanıt kodları 400 ve 500 için özel işleyiciler tanımlayarak istekte bulunan uygulamaya özelleştirilmiş bir yanıt mesajı döndürebilirsiniz. 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 kategoriler halinde düzenler.

Hatalara her zaman başarısızlığın nedenini açıklayan bir metin eşlik eder. Sistem bir hata verdiğinde, sorun gidermeye yardımcı olmak için bir dizi özellik doldurulur. Bir hata aşağıdaki bilgileri içerir:

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