Obsługa awarii

Przeglądasz dokumentację Apigee Edge.
Przejdź do Dokumentacja Apigee X. informacje.

Gdy serwery proxy interfejsów API obsługują żądania z aplikacji, może wystąpić wiele błędów. Dla: serwery proxy interfejsu API mogą na przykład napotkać problemy sieciowe podczas komunikacji z usługami backendu, aplikacje mogą prezentować wygasłe dane uwierzytelniające, żądania mogą być nieprawidłowo sformatowane itd. włącz.

Jeśli po wywołaniu serwera proxy interfejsu API przez aplikację kliencką wystąpi błąd, komunikat o błędzie zostanie zwrócony do do klienta. Domyślnie klient otrzymuje często niejasny komunikat o błędzie bez szczegółów ze wskazówkami. Jeśli jednak chcesz zastąpić domyślne komunikaty o błędach bardziej przydatnymi komunikatami niestandardowymi, a nawet wzbogacić je o dodatkowe nagłówki HTTP, trzeba skonfigurować niestandardowe błędy z obsługą przeglądarki Edge.

Niestandardowa obsługa błędów pozwala też dodać funkcje, takie jak rejestrowanie komunikatów za każdym razem, gdy występuje błąd.

Zanim przejdziemy do implementacji niestandardowej obsługi błędów na serwerach proxy interfejsu API, warto sprawdzić, zrozumieć, jak występują błędy i jak reagują na nie serwery proxy interfejsów API.

Filmy

Aby dowiedzieć się więcej o usuwaniu awarii, obejrzyj te filmy.

Jak występują błędy

Najpierw po prostu omówimy sposób występowania błędów. Wiedza o tym, jak występują błędy, ułatwia planowanie w przypadku różnych sytuacji, w których chcesz wdrożyć niestandardową obsługę błędów.

Błędy automatyczne

Serwer proxy interfejsu API zgłasza błąd automatycznie w tych sytuacjach:

• Zasada zgłasza błąd. Jeśli na przykład wywołanie interfejsu API wysyła nieaktualny klucz, funkcja Zasada VerifyAPIKey powoduje zgłoszenie błędu. lub jeśli liczba wywołań interfejsu API przekroczy określony limit, zasada limitu lub zasada SpiekeArrest zwróci błąd. (Zapoznaj się z informacjami o błędach zasad, aby dowiedzieć się, rodzaje błędów, jakie mogą spowodować zasady).
• Wystąpił problem z przepływem komunikatów serwera proxy interfejsu API, na przykład błąd routingu.
• Wystąpił błąd backendu, na przykład błąd HTTP w wyniku błędów na poziomie protokołu, protokół TLS/SSL lub niedostępna usługa docelowa.
• Wystąpiła awaria na poziomie systemu, na przykład wyjątek braku pamięci.

Więcej informacji o tych błędach znajdziesz w sekcji Taksonomia błędów w tym temacie.

Błędy niestandardowe

Jeśli nie ma błędu automatycznego, możesz zgłosić błąd niestandardowy. w przypadku jeśli odpowiedź zawiera słowo „unavailable” (niedostępny) lub jeśli kod stanu HTTP jest większy niż 201. Aby to zrobić, dodaj RaiseFault zasadę do odpowiednie miejsce w procesie serwera proxy interfejsu API.

Zasadę RaiseFault możesz dodać do przepływu serwera proxy interfejsu API tak samo jak w przypadku każdej innej zasady. W ten przykład konfiguracji serwera proxy, do której dołączona jest zasada Raise-Fault-1 odpowiedź TargetEndpoint. Jeśli słowo „niedostępny” występuje w odpowiedzi z elementu docelowego usługa RaiseFault jest wykonywana i zwraca błąd.

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

To tylko pokazanie, że mogą generować błędy niestandardowe. Przyjrzyjmy się temu bliżej Zasada RaiseFault w zasadach FaultRules vs. RaiseFault .

Więcej przykładów znajdziesz w tych postach na forach społeczności Apigee:

• Odwoływanie się do zmiennych JavaScriptu w RaiseFault

Co robią serwery proxy interfejsu API w przypadku błędów

Oto, co się dzieje, gdy serwer proxy zgłasza błąd.

Zamknij potok serwera proxy

Gdy serwer proxy interfejsu API napotka błąd (niezależnie od tego, w jaki sposób) wystąpi, wyjdzie z potoku normalnego przepływu, wpisze polecenie i zwraca komunikat o błędzie do aplikacji klienckiej. Gdy serwer proxy interfejsu API wpisze wartość nie może przywrócić przetwarzania z powrotem do normalnego potoku przepływu.

Załóżmy na przykład, że serwer proxy interfejsu API ma zasady w poniższej kolejności w punkcie końcowym żądanie:

1. Zweryfikuj klucz interfejsu API
2. Limit
3. Z JSON na XML

Jeśli podczas weryfikacji klucza interfejsu API wystąpi błąd, serwer proxy interfejsu API przechodzi w stan błędu. Zasady dotyczące limitów i plików JSON na XML nie są wykonywane, serwer proxy nie przechodzi do docelowego punktu końcowego, a do aplikacji klienckiej zwracany jest komunikat o błędzie.

Sprawdź reguły błędów

W stanie błędu serwery proxy API sprawdzają również obecność (w odpowiedniej kolejności) w pliku Konfiguracja serwera proxy interfejsu API przed zwróceniem aplikacji klienckiej domyślnego komunikatu o błędzie:

1. Sekcja <FaultRules>, która zawiera funkcje logiczne służące do wyświetlanie niestandardowych komunikatów o błędach (i innych zasad) na podstawie określonych warunków określić definicję.
2. Sekcja <DefaultFaultRule>, która wywołuje ustawienie domyślne. może pojawić się w następujących sytuacjach:
   • Nie zdefiniowano elementu <FaultRules>.
   • Żadne istniejące polecenie <FaultRules> nie zostało wykonane.
   • Element <AlwaysEnforce> ma wartość Prawda.

Serwer proxy interfejsu API umożliwia zwrócenie niestandardowego komunikatu o błędzie oraz które mogą wywoływać inne logiki. Jeśli serwer proxy nie znajduje żadnej z tych sekcji lub nie istnieją one, ale nie ma własnych został wywołany błąd, serwer proxy wysyła własny komunikat domyślny wygenerowany przez Edge.

Prosty przykład obsługi awarii

Zacznijmy od prostego przykładu, w którym wywołanie serwera proxy interfejsu API nie zawiera wymaganego interfejsu API . Domyślnie do aplikacji klienckiej zwracana jest odpowiedź:

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

Użytkownicy interfejsu API mogą być w stanie odczytać komunikat o błędzie, ale nie muszą. Wiele domyślnych są subtelniejsze i trudniejsze do rozszyfrowania.

Jako programista interfejsów API możesz zmienić tę wiadomość, aby spełniała potrzeby wszystkich otrzymują komunikat o błędzie. Może to dotyczyć dewelopera aplikacji na iOS czy testów wewnętrznych. grupę, która ma własne wymagania związane z formatem komunikatów o błędach.

Oto podstawowy przykład tworzenia niestandardowego komunikatu o błędzie do obsługi tego błędu. Ten wymaga 1) zasady definiującej komunikat niestandardowy, 2) reguły FaultRule, która je wykonuje gdy serwer proxy przejdzie w stan błędu.

1. Utwórz zasadę który definiuje komunikat niestandardowy

Najpierw utwórz zasadę definiującą niestandardowy komunikat o błędzie. Możesz używać dowolnego typu zasad, na przykład AssignMessage (zasada AssignMessage), która umożliwia ustawienie ładunku i opcjonalnych nagłówków HTTP, kod stanu i wyrażenia uzasadnienia. Funkcja Przypisz wiadomość jest do tego idealna. Pozwala kontrolować ładunek wiadomości, różne kody stanu HTTP, ustaw inne wyrażenie HTTP i dodaj nagłówki HTTP.

Nie dołączaj zasady do żadnego przepływu na serwerze proxy interfejsu API. Wystarczy, że będzie on istniał pakiet proxy. Aby to zrobić w edytorze proxy interfejsu zarządzania, otwórz kartę Programowanie i W panelu nawigacji i kliknij ikonę + na pasku zasad.

Dzięki temu możesz utworzyć zasadę bez dołączania jej do przepływu na serwerze proxy interfejsu API. Zasada który nie jest podłączony do żadnego przepływu, jest oznaczony jako „odłączony”. na liście Zasady, obok zasady komunikatu dotyczącego klucza interfejsu API widocznej na poprzednim ilustracji.

Poniżej znajduje się przykładowa zasada AssignMessage, która:

• Zwraca wiadomość JSON.
• Ustawia kod stanu HTTP (911, który jest oczywistym nieistniejącym kodem stanu), ilustruje Twoją elastyczność). Kod stanu pojawi się w nagłówku HTTP.
• Ustawia wyrażenie HTTP (aby zastąpić domyślne wyrażenie „Brak autoryzacji” dla tego błąd braku klucza interfejsu API). Uzasadnienie pojawi się obok kodu stanu w żądaniu HTTP nagłówek.
• Tworzy i wypełnia nowy nagłówek HTTP o nazwie invalidKey.

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

Po wykonaniu tej zasady odpowiedź na aplikację kliencką będzie wyglądać tak: Porównaj ją z widoczną wcześniej odpowiedzią domyślną.

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."}

Tak, to trochę głupie, ale pokazuje, co można zrobić. Teraz przynajmniej deweloper otrzymują komunikat, że zapomniał podać klucz interfejsu API jako parametr zapytania.

Jak jednak realizowana jest ta zasada? Możesz to zrobić w następnej sekcji.

2. Utwórz <FaultRule> które będą aktywować zasadę

W sekcji <ProxyEndpoint> lub <TargetEndpoint> sekcji konfiguracji serwera proxy, dodaj blok XML <FaultRules>, który zawiera jeden lub więcej pojedynczych sekcji <FaultRule>. Każda reguła błędu reprezentuje inny który chcesz naprawić. W tym prostym przykładzie użyjemy tylko jednej reguły FaultRule, żeby pokazać, z których składa się element.

Aby podać niestandardowy błąd ogólny, musisz też dodać <DefaultFaultRule> jest wyświetlany, jeśli żadna z reguł FaultRule nie została wykonana.

Przykład

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

Najważniejsze kwestie:

• Reguły błędów definiuje się w punkcie końcowym serwera proxy. To ważne. Więcej na temat puttowania Reguły błędów w punkcie końcowym serwera proxy a później w punkcie końcowym docelowym.
• <Name> – nazwa zasady do wykonania. Nazwa pochodzi z atrybutu name zasady w elemencie nadrzędnym, jak widać w tabeli przykład zasad.

• <Condition> – krawędź ocenia warunek i uruchamia zasadę tylko wtedy, gdy warunek jest prawdziwy. Jeśli istnieje wiele reguł błędów, które wartość prawda, Edge wykonuje pierwszą z nich. (Ważne: kolejność sprawdzania reguł FaultRule (od góry do dołu lub od dołu do góry) różni się między TargetEndpoint i ProxyEndpoint zgodnie z opisem w sekcji Wiele Reguły FaultRules i logika wykonania). Jeśli nie podasz warunku, ma automatycznie wartość prawda. Nie jest to jednak najlepsza metoda. Każda reguła FaultRule powinna mieć własną .

• <DefaultFaultRule> – jeśli nie ma niestandardowej reguły błędu wykonywane jest polecenie <DefaultFaultRule>, co powoduje wysłanie bardziej ogólnego kodu zamiast niejasnej domyślnej wiadomości wygenerowanej przez Edge. O <DefaultFaultRule> może też mieć parametr <Condition>, ale w w większości przypadków nie będziesz ich wpisywać, ponieważ zależy Ci, aby były wykonywane niezależnie ośrodka wypoczynkowego.

  Używa się zwykle do zwrócenia ogólnego komunikatu o błędzie w przypadku nieoczekiwany błąd. Przykładem może być wiadomość zawierająca informacje kontaktowe pomocy technicznej. Ta domyślna odpowiedź ma podwójny cel: przydatne dla programistów przy ukrywaniu adresów URL backendu i innych danych, może zostać wykorzystany do naruszenia bezpieczeństwa systemu.

Wiele reguł błędów i logika wykonywania

W sekcji Prosty przykład obsługi błędów użyliśmy prostego przykładu pojedynczej reguły FaultRule i warunku. W rzeczywistym projekcie interfejsu API ze wszystkimi możliwymi błędami jeśli wystąpi taka sytuacja, prawdopodobnie w Twoich <ProxyEndpoint> i <TargetEndpoint>. Ostatecznie jednak gdy serwer proxy interfejsu API przejdzie w stan błędu, będzie wykonywana tylko jedna reguła FaultRule.

Ta sekcja opisuje logikę używaną przez Edge przy obsłudze reguł FaultRules, od sposobu, w jaki dociera ona do jedną regułę błędu, która pozwala wykonać Warunki kroków są obsługiwane, gdy ich reguła błędu ma wartość . Ta sekcja zawiera również wskazówki na temat tego, kiedy należy definiować reguły błędów w tagu <ProxyEndpoint> kontra <TargetEndpoint> i opisuje relacji między FaultRules a zasadą RaiseFault.

Wykonanie FaultRules

W skrócie przedstawiamy logikę używaną przez Edge w sytuacji, gdy serwer proxy interfejsu API przejdzie w stan błędu. Pamiętaj, że występuje niewielka różnica między oceną reguł błędów w interfejsie ProxyEndpoint a metodą Docelowy punkt końcowy.

1. Edge ocenia reguły błędów w punkcie końcowym proxy lub w punkcie końcowym, w zależności od gdzie wystąpił błąd:
   • ProxyEndpoint – Edge zaczyna się od bottom <FaultRule> w pliku XML konfiguracji i działa w górę, oceniając <Condition> każdego parametru <FaultRule> ("zewnętrzny" stan, a nie „wewnętrzny” <Step> warunków).
   • TargetEndpoint – krawędź zaczyna się od top <FaultRule> w pliku XML konfiguracji i przesuwa się w dół, oceniając <Condition> każdego parametru <FaultRule> ("zewnętrzny" stan, a nie „wewnętrzny” <Step> warunków).
2. Wykonuje pierwszą regułę błędów, której warunek jest prawdziwy. Jeśli reguła błędu ma brak warunku, domyślnie ma wartość prawda.
   • Po wykonaniu reguły FaultRule wszystkie kroki w tej regule są oceniane w kolejności, w konfiguracji XML. Etapy bez warunków są wykonywane automatycznie (zasady są wykonywane) i czynności z parametrem <Condition>, który zwraca wartość „true” (prawda) są wykonywane (warunki, które przyjmują wartość „fałsz”, nie są ).

   • Jeśli reguła FaultRule jest wykonywana, ale nie są wykonywane żadne kroki z tej reguły (ponieważ warunki przyjmuje wartość „false” (fałsz), zwracany jest domyślny komunikat o błędzie wygenerowany przez krawędzie do aplikacji klienckiej. Pole <DefaultFaultRule> nie zostało wykonane, ponieważ przeglądarka Edge wykonała już swoją jedną regułę błędu.

3. Jeśli nie zostanie wykonana żadna reguła FaultRule, Edge wykonuje polecenie <DefaultFaultRule>, jeśli obecnie.

Oto przykłady z wpisanymi komentarzami.

Wykonanie punktu końcowego serwera proxy

Ocena reguł błędów ProxyEndpoint znajduje się od dołu do góry, więc zacznij czytać od końca FaultRule w poniższym przykładzie i zwiększ swoją szansę. Sprawdzaj na końcu regułę DefaultFaultRule.

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

Wykonanie docelowego punktu końcowego

Ocena reguł błędów punktu końcowego punktu końcowego jest oceniana od góry do dołu, więc zacznij czytać od pierwszego FaultRule w poniższym przykładzie i przechodź do kolejnych poziomów. Sprawdzaj na końcu regułę DefaultFaultRule.

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

Kolejność reguł błędu

Jak widać w poprzednim przykładzie, kolejność umieszczania reguł FaultRules jest taka: ważne w zależności od tego, czy błąd występuje w punkcie końcowym serwera proxy, czy w Docelowy punkt końcowy.

Na przykład:

Zasady, które należy uwzględnić

Możesz uruchamiać dowolne zasady z reguły FaultRule, umieszczając je w krokach. Możesz na przykład: Wykonaj zasadę AssignMessage, aby sformatować odpowiedź dla aplikacji klienckiej, a następnie zapisz wiadomość. z zasadami MessageLogging. Zasady są stosowane w kolejności, w jakiej zostały umieszczone (w pliku XML od góry do dołu).

Reguły błędów są wyzwalane TYLKO w stanie błędu (informacje o ContinueOnError)

Nagłówek może sprawiać wrażenie, że się powtarzamy, ale jest jeden specjalny niuans, o błędzie serwera proxy, który powoduje przejście serwera proxy interfejsu API w stan błędu – lub a nie bez wprowadzania stanu błędu: atrybutu continueOnError w .

Podsumujmy: serwer proxy interfejsu API ocenia <FaultRules> oraz <DefaultFaultRule> tylko wtedy, gdy serwer proxy jest w stanie błędu. Ten co oznacza, że nawet jeśli warunek FaultRule zostanie uznany za prawdziwy, nie zostanie aktywowany, jeśli serwer proxy nie jest w stanie błędu.

Oto przykład błędu, w którym serwer proxy nie przechodzi w stan błędu. Wł. dowolną zasadę, możesz ustawić w elemencie nadrzędnym atrybut o nazwie continueOnError. Ten atrybut jest bardzo ważny w kontekście rozwiązywania problemów, ponieważ określa, czy a nie serwer proxy przejdzie w stan błędu w przypadku niepowodzenia zasady. W większości przypadków lepiej jest zachować wartość domyślna continueOnError="false", która ustawia serwer proxy w stanie błędu, jeśli nie powiedzie się i uruchomi się niestandardowa obsługa błędów. Jeśli jednak continueOnError="true" (jeśli na przykład nie chcesz, aby usługa uległa awarii objaśnienie, aby zatrzymać wykonywanie działania serwera proxy), serwer proxy nie przejdzie w stan błędu, jeśli to nie powiedzie się, a serwer proxy nie będzie sprawdzać reguł FaultRule.

Informacje o logowaniu błędów w działaniu continueOnError="true" znajdziesz w sekcji Postępowanie w przypadku błędów zasad w bieżącym przepływie.

Gdzie w celu zdefiniowania reguł błędów: ProxyEndpoint lub TargetEndpoint

Jeśli wystąpi błąd serwera proxy interfejsu API, błąd ten występuje albo w <ProxyEndpoint> (żądanie z aplikacji klienckiej lub odpowiedź na nie) lub w <TargetEndpoint> (żądanie lub odpowiedź od usługi docelowej). Za każdym razem, występuje błąd, gdy Edge szuka reguł FaultRule.

Jeśli na przykład serwer docelowy jest niedostępny (kod stanu HTTP 503), serwer proxy interfejsu API w odpowiedzi <TargetEndpoint> i zwykły serwer proxy interfejsu API, przepływ nie będzie kontynuowany do <ProxyEndpoint>. Jeśli masz zdefiniowane reguły błędów tylko w <ProxyEndpoint>, nie naprawią tego błędu.

Oto kolejny przykład. Jeśli w systemie <ProxyEndpoint> została zastosowana zasada o zachowaniu błędu w przypadku wywołania błędu, reguła FaultRule w <TargetEndpoint> nie zostanie .

Zasady dotyczące błędów a zasada RaiseFault

Reguły błędów i zasada RaiseFault mogą brzmieć jak alternatywne sposoby naprawianie błędów; I w pewnym sensie jest to prawdą. Ale one też działają razem. Ten wyjaśnia relację między nimi. Zrozumienie tej relacji powinno pomóc zaprojektowanie obsługi błędów, zwłaszcza jeśli chcemy korzystać z obu.

W skrócie:

• Reguły błędów są zawsze oceniane, gdy serwer proxy interfejsu API wpisze błąd stanu.

• Zasada RaiseFault pozwala na wprowadzenie serwera proxy interfejsu API w stanie błędu gdy dany błąd nie wystąpiłby w innym przypadku.

  Jeśli na przykład chcesz zgłosić błąd, jeśli kod stanu HTTP w odpowiedzi z gdy usługa docelowa ma wartość większą niż 200, dodajesz do odpowiedzi zasadę RaiseFault przepływu danych. Mogłoby to wyglądać następująco:

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

  Zasada RaiseFault wysyła też komunikat o błędzie do aplikacji klienckiej.

Co się dzieje, gdy zasada RaiseFault aktywuje błąd, w wyniku którego serwer proxy działa stan, który może potencjalnie wykonywać regułę błędu? Tutaj wszystko może być złe. Jeśli zasada RaiseFault zwraca komunikat o błędzie i zostaje aktywowana reguła FaultRule, zwraca komunikat o błędzie – co jest zwracane do aplikacji klienckiej?

• Ponieważ reguła FaultRule lub DefaultFaultRule jest wykonywana po zasadzie RaiseFault, funkcja Wygrywa dane odpowiedzi FaultRule.
• Dane odpowiedzi zasady RaiseFault (kod stanu, wyrażenie przyczyny lub ładunek wiadomości) są jest używana, jeśli te dane nie są ustawione przez FaultRule lub DefaultFaultRule.
• Jeśli zasada RaiseFault i FaultRule dodają niestandardowe nagłówki HTTP, oba te typy zostaną uwzględnione w odpowiedź. Zduplikowane nazwy nagłówków powodują utworzenie nagłówka z wieloma wartościami.

Oto przykład ustawień ustawionych przez zasadę RaiseFault i regułę FaultRule oraz listę wartości, do aplikacji klienckiej. Przedstawione przykłady powinny być zwięzłe, a nie sprawdzone.

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

Warunki budynku

Warunki mają kluczowe znaczenie przy wykonywaniu reguły FaultRule. Warunki reguły FaultRule tworzy się w ten sam sposób wykonywane w przypadku innych warunków w Edge, takich jak przepływy warunkowe lub warunki RaiseFault.

Aby pokazać resztę tej sekcji, oto przykładowa reguła błędów, która zawiera atrybut zewnętrzny Warunek FaultRule i warunek wewnętrzny kroku.

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

Zmienne związane z zasadami błędy

Zmienne fault.name i {policy_namespace}.{policy_name}.failed są dostępne, gdy zasada zwróci błąd.

fault.name

Gdy zasada ulegnie awarii, wykrywaj błąd w warunkach za pomocą funkcji fault.name . Na przykład:

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

Nazwa błędu pojawi się w domyślnym komunikacie o błędzie. Na przykład w poniższym przykładzie błąd nazywa się FailedToResolveAPIKey. W tym przypadku zmienna przepływu o nazwie fault.name ma wartość FailedToResolveAPIKey.

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

Warunek będzie więc wyglądał następująco:

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

Zobacz Błąd związany z zasadami zapoznaj się z listą błędów zasad.

{policy_namespace}.{policy_name}.niepowodzenie

Zmienna *.failed jest dostępna w przypadku błędu zasady. Obserwujesz przykłady zmiennych *.failed dla różnych zasad. W przypadku przestrzeni nazw zasad zobacz zmienne przepływu w każdym temacie z informacjami o zasadach.

• Zwiększony błąd zasady: raisefault.failed (taka sama w przypadku wszystkich zasad RaiseFault)
• Zasada VerifyAPIKey: oauthV2.{policy_name}.failed dla przykład: oauthV2.Verify-API-Key-1.failed
• Zasady dotyczące limitów i zasady SpiekeArrest: ratelimit.{policy_name}.failed, na przykład ratelimit.Quota-1.failed

Inne dostępne zmienne

Gdy serwer proxy interfejsu API przejdzie w stan błędu, jedyne dostępne zmienne do użycia w warunkach to:

• Zmienne zasady, w przypadku której wystąpiły błędy.
• Zmienne komunikatu HTTP istniejące w momencie awarii. Jeśli na przykład błąd jest w odpowiedzi, reguła FaultRule w <TargetEndpoint> może używać HTTP. dane: response.status.code, message.content, error.content itd. Jeśli zawiodło zasada limitów, możesz użyć zmienna ratelimit.{quota_policy_name}.exceed.count Użyj narzędzia do śledzenia i zasad , które pomogą Ci zorientować się, które zmienne i dane HTTP są dostępne.

Więcej informacji

• Warunki: Informacje o warunkach i Zmienne przepływu i warunki

• Błędy: Informacje o błędach zasad
• Zmienne: informacje o zmiennych i wyświetlanie poszczególnych stronach z odniesieniami do zmiennych, które są dostępne dla danej zasady.

Sprawdzone metody postępowania z awariami

Obsługa błędów to główne zadanie projektowania architektury na potrzeby programowania serwerów proxy interfejsów API. To ważne czas na określenie, jak i kiedy można go naprawić, ustalić, który błąd i zaprojektuj formaty komunikatów o błędach. Gdy już to zrobisz, a następnie skorzystaj z tych sprawdzonych metod, aby ułatwić sobie implementację obsługi błędów.

Poniżej przedstawiamy kilka sprawdzonych metod projektowania i usuwania usterek:

• Dla każdej reguły FaultRule podaj wartość „outer” <Condition> (równorzędna z parametrem <Step>). Reguły błędów bez warunku zewnętrznego są oceniane automatycznie na wartość true (prawda). „Wewnętrzne” Warunki kroków nie są używane do określania, czy reguła błędów jest spełniony lub false. Warunki kroków są oceniane dopiero po wykonaniu przez Edge reguły FaultRule, która je zawiera. Zazwyczaj w regule FaultRule jest wiele kroków z zasadą Assign Message (lub innymi), każdy z warunkiem kroku.

• Aby obsługiwać błędy w wielu zasadach tego samego typu (na przykład wiele zasad dotyczących limitu zasad), utwórz jedną regułę błędu dla każdego błędu związanego z zasadami, który prawdopodobnie wystąpi. Przykład: dla każdego prawdopodobnego błędu w zasadach dotyczących limitów, takich jak QuotaViolation, InvalidMessageWeight, StartTimeNotSupported (Zapoznaj się z informacjami o błędach zasad w sekcji błędów związanych z naruszeniem zasad. Gdy wykryjesz inne błędy, które trzeba naprawić, możesz wrócić i dodaj je do reguł FaultRules. Działanie iteracyjne jest dozwolone, chociaż wymaga to ponowne wdrożenie serwera proxy). Takie podejście pozwala wychwytywać ten sam typ błędu niezależnie od tego, co sprawia, że reguły FaultRules są wydajne w formacie XML.

  Następnie użyj warunków kroku wewnętrznego, jeśli potrzebujesz bardziej szczegółowej kontroli błędów. Przykład: jeśli egzekwujesz zarówno limit indywidualny dewelopera, jak i limit globalny za pomocą 2 zasad w procesie żądania, ustaw „zewnętrzny” Warunek FaultRule zostanie aktywowany QuotaViolation błąd (występujący po przekroczeniu limitu w obu przypadkach). Potem ustaw warunki kroków, aby ocenić zmienne exceed.count w obu limitach . Do klienta zostanie wysłany tylko odpowiedni błąd (przekroczenie limitu programisty lub globalny nadwyżki limitu). Oto przykład takiej konfiguracji:

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

  Inny przykład znajdziesz w tym wątku społeczności Apigee.

• Aby obsługiwać błędy w przypadku korzystania z jednej zasady jednego typu, należy rozważyć pojedynczy błąd reguła, która jest wykonywana w przypadku niepowodzenia tej jednej zasady i zawiera wiele kroków, które są mapowane na każdego możliwego błędu. Pozwala to utrzymać wydajność pliku XML dzięki użyciu pojedynczej reguły błędu zamiast wiele reguł FaultRules (po jednej na każdy typ błędu). Na przykład:

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

• Dodaj reguły FaultRules w miejscu występowania błędów (<ProxyEndpoint> po stronie klienta) lub strona docelowa <TargetEndpoint>). Uwzględnij reguły błędów dla każdej zasady, która w każdej lokalizacji.
• W FaultRules możesz uruchamiać dowolne zasady, które mogą zwrócić komunikat do klienta. . Do tego celu idealna jest zasada AssignMessage. Rozważ też zapisanie wiadomości z zasadę MessageLogging, jeśli chcesz śledzić błędy.
• Gdy używasz zasad RaiseFault w połączeniu z regułami FaultRules, koordynuj odpowiedź dane, które są wysyłane z powrotem, gdy zwracają dane zarówno przez zasadę RaiseFault, jak i regułę FaultRule. Dla: jeśli na przykład zasada RaiseFault resetuje kod stanu HTTP, nie zresetuj reguły FaultRule. kod stanu. Najgorsze, co może się zdarzyć, to przywrócenie domyślnego kodu stanu do funkcji aplikacji klienckiej.
• Wykonanie <DefaultFaultRule>:
  • Jeśli chcesz, aby reguła <DefaultFaultRule> była zawsze wykonywana, gdy żaden inny Wykonuje się FaultRule. Nie dodawaj do nich <Condition>.
  • Jeśli chcesz, aby dyrektywa <DefaultFaultRule> była zawsze wykonywana, nawet jeśli inna Reguła FaultRule została wykonana, dodaj Element podrzędny <AlwaysEnforce>true</AlwaysEnforce>.

Wzór dla scentralizowana, wielokrotnego użytku;

Poniższy post na karcie Społeczność Apigee opisuje wzorzec scentralizowanej obsługi awarii bez duplikowanie kodu:

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

Tworzenie reguł błędów

Aby dodać regułę błędu, musisz zmodyfikować konfigurację XML punktu końcowego serwera proxy lub Docelowy punkt końcowy. Możesz użyć interfejsu Edge, aby wprowadzić tę zmianę w panelu Kod Zaprogramuj widok dla serwera proxy interfejsu API lub zmodyfikuj plik XML, który definiuje punkt końcowy serwera proxy lub Docelowy punkt końcowy.

Jeśli tworzysz reguły FaultRules w interfejsie zarządzania, najpierw utwórz zasady, które chcesz wykonać, a następnie dodaj je do konfiguracji FaultRule. (Jeśli spróbujesz zapisać plik Reguła błędu odwołująca się do zasady, która nie została jeszcze utworzona).

Dodawanie zasad do reguły błędu

Możesz umieścić dowolną zasadę w regule błędu, ale zwykle używasz atrybutu AssignMessage (Zasada AssignMessage) do generowania niestandardowej odpowiedzi dla warunku błędu. Funkcja AssignMessage pozwala skonfigurować odpowiedź HTTP z ładunkiem, kodem stanu HTTP, nagłówkami i wyrażeń związanych z argumentami.

Poniżej znajduje się przykładowa konfiguracja zasady AssignMessage:

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

Możesz teraz używać tej zasady w regule FaultRule. Zwróć uwagę, że odwołujesz się do właściwości AssignMessage zasada według nazwy w regule FaultRule:

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

Gdy wdrożysz powyższą konfigurację, serwer proxy interfejsu API uruchomi zasadę AssignMessage. fault_invalidkey za każdym razem, gdy aplikacja przedstawi nieprawidłowy klucz interfejsu API.

W regule błędu możesz uruchomić wiele zasad, jak pokazano w tym przykładzie:

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

Zasady są stosowane w określonej kolejności. Na przykład możesz użyć atrybutu Zasadę MessageLogging, WyodrębnijZmienne, AssignMessage lub dowolnej innej zasady w FaultRule. Pamiętaj, że przetwarzanie reguły FaultRule zostaje zatrzymane natychmiast w jednej z tych sytuacji: występują:

• Każda zasada w regule FaultRule powoduje błąd
• Dowolna z zasad w regule FaultRule jest typu RaiseFault

Definiowanie niestandardowy komunikat o błędzie zwrócony z reguły FaultRule

Dobrą praktyką jest zdefiniowanie jasnych odpowiedzi na błędy w API. W ten sposób będziesz przekazywać klientom spójne i przydatne informacje.

Następujący przykład zasady AssignMessage korzysta z: <Payload>, <StatusCode> i <ReasonPhase>, aby zdefiniować niestandardową odpowiedź informująca o błędzie odesłana do klienta w przypadku błędu Nieprawidłowy klucz API (patrz poprzednie reguły FaultRules) ).

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

Ta odpowiedź zawiera:

• Ładunek zawierający komunikat o błędzie i adres e-mail do kontaktu z zespołem pomocy.
• Kod stanu HTTP zwrócony w odpowiedzi.
• Wyrażenie, które jest krótkim opisem błędu.

Tworzenie domyślnej reguły błędów

Reguła defaultFaultRule działa jako moduł obsługi wyjątków w przypadku każdego błędu, który nie jest obsługiwany przez do kolejnej reguły FaultRule. Jeśli warunki wszystkich reguł FaultRule nie są zgodne z błędem, wtedy funkcja DefaultFaultRule obsługuje błąd. Włącz domyślną obsługę błędów przez dodanie parametru tag <DefaultFaultRule> jako element potomny punktu ProxyEndpoint lub Docelowy punkt końcowy.

Na przykład poniższa konfiguracja punktu końcowego określa regułę DefaultFaultRule, która wywołuje zasada o nazwie ReturnGeneralError:

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

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

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

Używa się zwykle reguły DefaultFaultRule w celu zwrócenia ogólnego komunikatu o błędzie w przypadku wystąpienia nieoczekiwanych wyników np. komunikat zawierający informacje kontaktowe. To ustawienie domyślne ma na celu dostarczanie informacji przyjaznych dla programistów, ukrywających adresy URL backendu lub inne informacje, które mogłyby zostać użyte do naruszenia bezpieczeństwa systemu.

Możesz na przykład zdefiniować tę zasadę AssignMessage, aby zwracać błąd ogólny:

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

Umieść element <AlwaysEnforce> w parametrze <DefaultFaultRule> do wykonania reguły DefaultFaultRule w przypadku każdego błędu, nawet jeśli inna reguła błędu została już wykonana. Domyślna reguła błędów jest zawsze ostatnią regułą błędów do wykonania:

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

Jednym z zastosowań reguły DefaultFaultRule jest określenie typu błędu, który występuje, gdy w inny sposób nie mogą go określić. Na przykład serwer proxy interfejsu API ulega awarii z powodu błędu nie możemy określić. Użyj domyślnej reguły AssignMessage, aby wywołać poniższą zasadę AssignMessage. Ten zasada zapisuje wartość fault.name w nagłówku o nazwie DefaultFaultHeader w odpowiedzi:

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

Potem możesz wyświetlić nagłówek w narzędziu do śledzenia Edge lub w odpowiedzi, aby sprawdzić, co spowodowało problem. .

Dodaję logowanie wiadomości do PostClientFlow

PostClientFlow to jedyny proces wykonywany po wprowadzeniu błędu przez serwer proxy. stanu. Do tego przepływu, który jest wykonywany, można dołączyć tylko zasadę MessageLogging. po wysłaniu odpowiedzi zwracając się do klienta. Mimo że dołączenie zasad MessageLogging do tego procesu jest technicznie nie obsługi błędów, za jego pomocą można rejestrować informacje w przypadku wystąpienia błędu. Ponieważ niezależnie od tego, czy serwer proxy się powiódł, czy nie, możesz umieścić w usłudze Message Logging w PostClientFlow i można mieć pewność, że będą one zawsze wykonywane.

Postępowanie w przypadku błędów zasad w bieżącym przepływie

Dotychczasowe przykłady wykorzystują regułę błędu w punkcie końcowym serwera proxy lub w punkcie końcowym wszystkie błędy związane ze zgodnością z zasadami. To dlatego, że domyślna wartość parametru Element continueOnError zasady to false, co oznacza, że gdy w zasadzie występuje błąd, kontrola jest kierowana do stanu błędu. W stanie błędu nie może przywrócić elementu sterującego do normalnego potoku i zwykle zwracany jest jakiś rodzaj błędu do aplikacji do rozmów.

Jeśli jednak ustawisz element continueOnError na true w przypadku zasada, kontrola pozostaje w bieżącym przepływie, a następna zasada w potoku jest wykonywana po zasady, która spowodowała błąd. Zaletą obsługi błędu w bieżącym procesie jest to, może istnieć sposób na naprawienie błędu i dokończenie przetwarzania żądania.

Poniżej znajduje się zasadaVerifyAPIKey o nazwie verify-api-key z parametrem continueOnError element został ustawiony na true:

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

Jeśli brakuje klucza interfejsu API lub jest on nieprawidłowy, zasadaVerifyAPIKey ustawia Zmienną oauthV2.verify-api-key.failed na true, ale w trakcie przetwarzania i kontynuowanie procesu.

Następnie dodaj zasadę VerifyAPIKey jako krok w procesie PreFlow punktu końcowego ProxyEndpoint:

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

Zwróć uwagę, że w następnym kroku PreFlow jest używany warunek do przetestowania . Jeśli wystąpił błąd w zasadzie VerifAPIKey, wówczas zasada o nazwie Wykonuję zasadę FaultInFlow. W przeciwnym razie zasada FaultInFlow jest pominięto. Zasada FaultInFlow może wykonywać wiele czynności, np. rejestrować błąd, próba naprawienia błędu lub wykonania innej czynności.

Wywołanie błędu przy użyciu metody RaiseFault polityka

Aby wywołać błąd, możesz w dowolnym momencie procesu użyć zasady RaiseFault. Gdy Zasada RaiseFault jest wykonywana, zamyka bieżący przepływ i przenosi kontrolę na błąd stanu.

Jednym z zastosowań zasady RaiseFault jest przetestowanie pod kątem określonego warunku twierdzonego przez inną zasadę może nie zostać wykryty. W powyższym przykładzie dodano tag <Condition> do Tag PreFlow <Step>, który spowodował wykonanie zasady FaultInFlow jeśli warunek jest spełniony. Jeśli zasada FaultInFlow jest zasadą RaiseFault, przechodzi do stanu błędu. Możesz też wstawić zasadę RaiseFault w procesie debugowania i testowania reguł FaultRules.

Gdy zasada RaiseFault aktywuje błąd, możesz użyć tego warunku i reguły FaultRule , aby go przetworzyć:

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

Pamiętaj, że warunek sprawdza błąd o nazwie RaiseFault. Wspólnota zasada zawsze ustawia wartość fault.name na RaiseFault.

Niestandardowa obsługa kodów błędów HTTP z serwera docelowego

Przykłady podane w poprzednich sekcjach odnoszą się do błędów utworzonych przez zasady. Jakkolwiek może też utworzyć odpowiedź niestandardową dla błędów na poziomie transportu, co oznacza błędy HTTP zwracane przez na serwerze docelowym. Aby kontrolować odpowiedź z błędu HTTP, skonfiguruj docelowy punkt końcowy jako przetwarzania kodów odpowiedzi HTTP.

Domyślnie Edge traktuje kody odpowiedzi HTTP z zakresu 1xx–3xx jako „powodzenie”, a HTTP z zakresu 4xx–5xx jako „niepowodzenie”. Oznacza to, że każda odpowiedź z backendu usługa z kodem odpowiedzi HTTP 4xx-5xx automatycznie wywołuje stan błędu, który wtedy zwraca komunikat o błędzie bezpośrednio do klienta, który wysłał żądanie.

Możesz utworzyć niestandardowe moduły obsługi dla dowolnych kodów odpowiedzi HTTP. Możesz na przykład nie chcieć: traktuj wszystkie kody odpowiedzi HTTP z zakresu 4xx-5xx jako „niepowodzenie” ale tylko 5xx, lub chcesz , aby zwracać niestandardowe komunikaty o błędach dla kodów odpowiedzi HTTP 400 i 500.

W następnym przykładzie użyjesz właściwości success.codes, aby skonfigurować Docelowy punkt końcowy traktujący kody odpowiedzi HTTP 400 i 500 jako udane wraz z domyślnym kodem HTTP kodami. Traktując te kody jako udany, docelowy punkt końcowy przejmuje przetwarzanie jako odpowiedź, zamiast wywoływać stan błędu:

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

Jak widać w tym przykładzie, za pomocą symboli wieloznacznych możesz ustawić dla właściwości success.codes zakres: wartości...

Ustawienie właściwości success.codes powoduje zastąpienie domyślnych. Jeśli więc chcesz dodać kod HTTP 400 do listy domyślnego stanu powodzenia ustaw tę właściwość jako:

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

Jeśli jednak chcesz, aby jako kod powodzenia traktowano tylko kod HTTP 400, ustaw tę właściwość jako:

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

Możesz teraz zdefiniować niestandardowe moduły obsługi kodów odpowiedzi HTTP 400 i 500, aby zwracać dostosowane z odpowiedzią do aplikacji, która je wysłała. Następujący docelowy punkt końcowy korzysta z zasady o nazwie ReturnError do obsługi kodów odpowiedzi HTTP 400 i 500:

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

Ta konfiguracja docelowego punktu końcowego powoduje, że obsługa jest obsługiwana przez zasadę o nazwie ReturnError odpowiedź za każdym razem, gdy docelowy punkt końcowy napotka kod odpowiedzi HTTP o wartości 400 lub 500.

Taksonomia błędów

Usługi interfejsu API porządkują błędy w następujące kategorie i podkategorie.

Błądowi towarzyszy zawsze opis jego przyczyny. Gdy system zgłasza usterkę, uzupełniono zestaw atrybutów, które ułatwiają rozwiązywanie problemu. Błąd zawiera następujące informacje:

• Przyczyna
• Atrybuty niestandardowe zdefiniowane przez użytkownika