Obsługa awarii

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X.
Informacje

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

Jeśli po wywołaniu przez aplikację kliencką serwera proxy interfejsu API wystąpi błąd, do klienta zostanie zwrócony komunikat o błędzie. Domyślnie klient otrzymuje często zagadkowy komunikat o błędzie bez szczegółów i wskazówek. 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, musisz skonfigurować niestandardową obsługę błędów w Edge.

Niestandardowa obsługa błędów pozwala też dodać funkcje, takie jak logowanie komunikatów, gdy wystąpi błąd.

Zanim zajmiemy się implementacją niestandardowej obsługi błędów w serwerach proxy interfejsu API, warto dowiedzieć się, jak występują błędy i jak reagują na nie serwery proxy API.

Filmy

Aby dowiedzieć się więcej o postępowaniu z błędami, obejrzyj poniższe filmy.

Wideo Opis
Wprowadzenie do obsługi błędów i przepływów błędów Dowiedz się więcej o obsłudze błędów i o tym, co się dzieje, gdy błąd wystąpi na serwerze proxy interfejsu API.
Obsługuj błędy za pomocą reguł błędów Dowiedz się, jak obsługiwać błędy za pomocą reguł błędów.
Zgłaszanie błędów niestandardowych za pomocą zasady GrowFault Zgłaszanie błędów niestandardowych w środowisku wykonawczym interfejsu API za pomocą zasady romotingFault.
Zdefiniuj reguły błędów w serwerze proxy interfejsu API i docelowych punktach końcowych Zdefiniuj reguły błędów w serwerze proxy interfejsu API i docelowych punktach końcowych oraz poznaj różnice.
Zapoznaj się z kolejnością wykonywania reguł błędów Poznaj kolejność wykonywania reguł błędów na serwerze proxy interfejsu API i docelowych punktach końcowych.
Zdefiniuj domyślną regułę błędu Zdefiniuj domyślną regułę błędów do obsługi błędów ogólnych w interfejsie API.

Jak występują błędy

Najpierw omówimy po prostu, jak występują błędy. Wiedza o tym, jak występują błędy, pomaga zaplanować różne sytuacje, w których chcesz wdrożyć niestandardową obsługę błędów.

Błędy automatyczne

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

  • Zasada powoduje błąd. Jeśli na przykład wywołanie interfejsu API wysyła wygasły klucz, zasadaVerifyAPIKey automatycznie zgłasza błąd. Jeśli liczba wywołań interfejsu API przekroczy określony limit, zasada limitów lub zasada SpikeArrest zgłosi błąd. Typy błędów, jakie mogą zgłaszać zasady, znajdziesz w dokumentacji błędów zasad.
  • Wystąpił problem z przepływem wiadomości przez serwer proxy interfejsu API, na przykład błąd routingu.
  • Wystąpił błąd backendu, na przykład błąd HTTP spowodowany awariami na poziomie protokołu, błędami TLS/SSL lub niedostępną usługą docelową.
  • Wystąpiła awaria na poziomie systemu, na przykład z powodu braku pamięci.

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

Błędy niestandardowe

W sytuacjach, gdy nie występuje żaden błąd automatyczny, możesz zgłosić błąd niestandardowy, np. gdy odpowiedź zawiera słowo „niedostępny” lub kod stanu HTTP ma wartość większą niż 201. Aby to zrobić, w odpowiednim miejscu procesu serwera proxy interfejsu API dodaj GrowFault.

Możesz dodać zasadę bidFault do przepływu proxy interfejsu API tak samo jak każdą inną zasadę. W poniższym przykładzie konfiguracji serwera proxy do odpowiedzi TargetEndpoint jest dołączona zasada Raise-Fault-1. Jeśli w odpowiedzi usługi docelowej znajduje się słowo „niedostępny”, zasada romotingFault jest wykonywana i zgłasza błąd.

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

Chodzi o to, aby pokazać, że możesz zgłaszać błędy niestandardowe. Więcej informacji na temat zasady ThroughFault znajdziesz w sekcji dotyczącej zasad dotyczących błędów i zasad ThroughFault.

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

Co robią serwery proxy interfejsu API w przypadku wystąpienia 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 jego wystąpienia, wychodzi z normalnego potoku, wchodzi w stan błędu i zwraca komunikat o błędzie do aplikacji klienckiej. Gdy serwer proxy interfejsu API wejdzie w stan błędu, nie może powrócić przetwarzanie z powrotem do normalnego potoku.

Załóżmy na przykład, że serwer proxy interfejsu API ma zasady w żądaniu ProxyEndpoint w następującej kolejności:

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

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

Sprawdź reguły błędów

W stanie błędu serwery proxy interfejsu API przed zwróceniem domyślnego komunikatu o błędzie do aplikacji klienckiej sprawdzają dodatkowo, czy w konfiguracji serwera proxy interfejsu API występują te elementy (w kolejności):

  1. Sekcja <FaultRules> zawierająca funkcje aktywujące niestandardowe komunikaty o błędach (i inne zasady) na podstawie zdefiniowanych przez Ciebie warunków.
  2. Sekcja <DefaultFaultRule>, która w tych sytuacjach wywołuje domyślny komunikat o błędzie:
    • Nie zdefiniowano <FaultRules>.
    • Żadne istniejące żądania <FaultRules> nie zostaną wykonane.
    • Element <AlwaysEnforce> ma wartość Prawda.

W skrócie – serwer proxy interfejsu API umożliwia zwrócenie niestandardowego komunikatu o błędzie i aktywowanie innej logiki. Jeśli serwer proxy nie znajdzie żadnej z tych sekcji lub one istnieją, ale nie wystąpił żaden błąd niestandardowy, serwer proxy wysyła własny komunikat domyślny wygenerowany na brzegu sieci.

Przykład prostej obsługi błędów

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

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 zrozumieć komunikat o błędzie, ale nie muszą. Wiele błędów domyślnych jest też bardziej subtelnych i trudniejszych do rozszyfrowania.

Jako deweloper interfejsu API możesz zmienić ten komunikat tak, aby odpowiadał wszystkim użytkownikom, którzy zobaczą komunikat o błędzie – niezależnie od tego, czy jest to deweloper aplikacji na iOS, czy wewnętrzna grupa testowa, która ma własne wymagania związane z formatem komunikatu o błędzie.

Oto podstawowy przykład tworzenia niestandardowego komunikatu o błędzie w celu rozwiązania tego problemu. Wymaga to: 1) zasady definiującej komunikat niestandardowy oraz 2) reguły FaultRule, która uruchamia zasadę, gdy serwer proxy przejdzie w stan błędu.

1. Utwórz zasadę definiującą komunikat niestandardowy

Najpierw utwórz zasadę definiującą niestandardowy komunikat o błędzie. Możesz użyć dowolnego typu zasady, na przykład zasady AssignMessage, która pozwala ustawić ładunek oraz opcjonalnych nagłówków HTTP, takich jak kod stanu i wyrażenie przyczyny. Idealna opcja to Przypisz wiadomość. Pozwala kontrolować ładunek wiadomości, ustawiać inny kod stanu HTTP, ustawić inną przyczynę HTTP i dodawać nagłówki HTTP.

Nie dołączaj zasady do żadnego przepływu w serwerze proxy interfejsu API. Wystarczy, że znajduje się on w pakiecie proxy. Aby to zrobić, w edytorze serwera proxy interfejsu zarządzania otwórz kartę Programowanie, a następnie w panelu nawigacji kliknij ikonę + na pasku Zasady.

Pozwala to utworzyć zasadę bez dołączania jej do procesu w serwerze proxy interfejsu API. Zasada, która nie jest dołączona do żadnego procesu, jest oznaczona na liście zasad ikoną „odłączona”, jak pokazano obok zasady dotyczącej komunikatów klucza interfejsu API pokazanej na poprzedniej ilustracji.

Oto przykładowa zasada AssignMessage, która:

  • Zwraca wiadomość JSON.
  • Ustawia kod stanu HTTP (911, czyli oczywiście nieistniejący kod stanu, który tylko ilustruje Twoją elastyczność). Kod stanu pojawi się w nagłówku HTTP.
  • Ustawia wyrażenie uzasadniające HTTP (zastępujące domyślne wyrażenie przyczyny braku dostępu do klucza interfejsu API w przypadku tego błędu „Brak autoryzacji”). Uzasadnienie jest wyświetlane obok kodu stanu w nagłówku HTTP.
  • 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 uruchomieniu tej zasady odpowiedź dla aplikacji klienckiej będzie wyglądać tak: Porównaj ją z pokazaną 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ć. Deweloper, który otrzymał tę wiadomość, wie już, że zapomniał dodać klucz interfejsu API jako parametr zapytania.

Jak jednak wdrożyć tę zasadę? Zobaczysz ją w następnej sekcji.

2. Utwórz <FaultRule>, który będzie aktywować zasadę

W sekcjach <ProxyEndpoint> lub <TargetEndpoint> konfiguracji serwera proxy dodaj blok XML <FaultRules> zawierający co najmniej 1 sekcję <FaultRule>. Każda reguła błędu oznacza inny błąd, który chcesz naprawić. W tym prostym przykładzie użyjemy tylko jednej reguły FaultRule, aby pokazać, z czego składa się dana reguła.

Dodaj też <DefaultFaultRule>, aby wyświetlać niestandardowy ogólny komunikat o błędzie, gdy żadna z reguł FaultRule nie zostanie 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 są zdefiniowane w punkcie ProxyEndpoint. To ważne. Więcej informacji o umieszczaniu reguł błędów w punkcie końcowym proxy i w punkcie docelowym później.
  • <Name> – nazwa zasady do wykonania. Nazwa pochodzi z atrybutu name zasady w elemencie nadrzędnym, tak jak we wcześniejszym przykładzie zasady.
  • <Condition> – Edge ocenia warunek i uruchamia zasadę tylko wtedy, gdy jest on prawdziwy. Jeśli istnieje wiele reguł FaultRule, które zwracają wartość „true” (prawda), Edge wykonuje pierwszą, która jest prawdziwa. (Ważne: kolejność oceny reguł błędów (od góry do dołu lub od dołu do góry) różni się w zależności od elementu docelowego (TargetEndpoint) i ProxyEndpoint, co opisano w sekcji Wiele reguł błędów i logika wykonania. Jeśli nie dodasz warunku, reguła FaultRule ma wartość „true” (prawda). Nie jest to jednak najlepsza metoda. Każda reguła FaultRule powinna mieć własny warunek.

  • <DefaultFaultRule> – jeśli nie zostanie wykonana żadna niestandardowa reguła FaultRule, zostanie wykonana <DefaultFaultRule>, co spowoduje wysłanie bardziej ogólnego komunikatu niestandardowego zamiast niejawnego domyślnego komunikatu wygenerowanego na brzegu sieci. <DefaultFaultRule> może też zawierać element <Condition>, ale w większości przypadków nie umieszczasz go, ponieważ powinien on być uruchamiany niezależnie od okoliczności w ostateczności.

    Reguła defaultFaultRule jest zwykle używana do zwrócenia ogólnego komunikatu o błędzie w przypadku dowolnego nieoczekiwanego błędu. Przykładem może być wiadomość z danymi kontaktowymi pomocy technicznej. Ta domyślna odpowiedź ma 2 cel: dostarcza informacji łatwych dla programistów, a jednocześnie maskuje adresy URL backendu lub inne informacje, które mogą zostać użyte do zaatakowania systemu.

Wiele FaultRules i logika wykonania

W sekcji Przykład prostej obsługi błędów zastosowaliśmy prosty przykład pojedynczej reguły FaultRule i warunku. W rzeczywistym projekcie interfejsu API zawierającym wszystkie możliwe błędy, które mogą wystąpić, w regułach <ProxyEndpoint> i <TargetEndpoint> prawdopodobnie będzie występować wiele reguł FaultRule i DefaultFaultRule. Ostatecznie, gdy serwer proxy interfejsu API przejdzie w stan błędu, jest wykonywana tylko jedna reguła FaultRule.

W tej sekcji opisano logikę, której przeglądarka Edge używa do obsługi reguł FaultRule – od sposobu dostarczania pojedynczej reguły FaultRule do wykonania, aż po sposób obsługi „wewnętrznych” warunków kroku po wywołaniu ich reguły FaultRule. W tej sekcji znajdziesz też wskazówki, kiedy definiować reguły błędów w zasadzie <ProxyEndpoint>, a kiedy w <TargetEndpoint>. Opisujemy też związek między regułami FaultRule i ReportingFault.

Wykonanie reguł błędów

Krótko mówiąc, ta zasada jest używana przez Edge, gdy serwer proxy interfejsu API przejdzie w stan błędu. Zwróć uwagę, że występuje niewielka różnica między oceną FaultRules w punkcie ProxyEndpoint i w punkcie końcowym TargetEnd.

  1. Edge ocenia reguły błędów w punkcie końcowym ProxyEndpoint lub TargetEndpoint w zależności od miejsca, w którym wystąpił błąd:
    • ProxyEndpoint – Edge zaczyna się od dołu <FaultRule> w pliku XML konfiguracji i przesuwa się w górę, oceniając <Condition> każdego elementu <FaultRule> (warunek „zewnętrzny”, a nie „wewnętrzny” <Step>).
    • TargetEndpoint – Edge zaczyna się od top <FaultRule> w pliku XML konfiguracji i przesuwa się w dół, oceniając <Condition> każdego obiektu <FaultRule> (warunek „zewnętrzny”, a nie „wewnętrzny” <Step>).
  2. Wykonuje pierwszą regułę błędu, której warunek jest spełniony. Jeśli reguła FaultRule nie ma warunku, ma ona domyślnie wartość true (prawda).
    • Po wykonaniu reguły FaultRule są sprawdzane wszystkie kroki wewnątrz reguły FaultRule, od góry do dołu w konfiguracji XML. Kroki bez warunków są wykonywane automatycznie (zasady są wykonywane), a kroki z obiektem <Condition> zwracającym wartość „true” (prawda) są wykonywane (warunki, które zwracają wartość „false”; nie są wykonywane).
    • Jeśli reguła FaultRule zostanie wykonana, ale nie zostaną wykonane żadne kroki z reguły FaultRule (ponieważ ich warunki mają wartość „false”), do aplikacji klienta zostanie zwrócony domyślny komunikat o błędzie wygenerowany przez Edge. <DefaultFaultRule> nie jest wykonywany, ponieważ Edge wykonał już jedną regułę FaultRule.

  3. Jeśli nie zostanie wykonana żadna reguła FaultRule, Edge uruchomi element <DefaultFaultRule> (jeśli jest dostępny).

Poniżej znajdziesz przykłady z komentarzami w tekście.

Wykonanie serwera proxy

Ocena błędu ProxyEndpoint FaultRules jest od dołu do góry. Zacznij więc czytać od ostatniej reguły błędów w poniższym przykładzie i przesuwaj się w górę. Na końcu przyjrzyj się reguleDefaultFaultRule.

<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 błędów obiektu TargetEndpoint FaultRules jest od góry do dołu, więc zacznij czytać od pierwszej reguły błędów w poniższym przykładzie i przesuwaj się w dół. Na końcu przyjrzyj się reguleDefaultFaultRule.

<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łędów

Jak widać w poprzednim przykładzie, kolejność umieszczania reguł FaultRule jest ważna w zależności od tego, czy błąd występuje w punkcie ProxyEndpoint czy w docelowym punkcie końcowym.

Na przykład:

Kolejność punktów końcowych serwera proxy Kolejność docelowych punktów końcowych

W poniższym przykładzie ocena znajduje się od dołu do góry, dlatego wykonywana jest reguła FaultRule 3, co oznacza, że reguły FaultRule 2 i 1 nie są sprawdzane.

5. Reguła błędu 1: FAŁSZ

4. Reguła błędu 2: PRAWDA

3. Reguła błędu 3: PRAWDA

2. Reguła błędu 4: FAŁSZ

1. Reguła błędów: 5 FAŁSZ

W poniższym przykładzie ocena przebiega od góry do dołu, dlatego wykonywana jest reguła FaultRule 2, co oznacza, że reguły błędów 3, 4 i 5 nie są oceniane.

1. Reguła błędu 1: FAŁSZ

2. Reguła błędu 2: PRAWDA

3. Reguła błędu 3: PRAWDA

4. Reguła błędu 4: FAŁSZ

5. Reguła błędów: 5 FAŁSZ

Zasady do uwzględnienia

Aby uruchomić dowolne zasady z reguły błędów, umieść je w krokach. Możesz na przykład uruchomić zasadę AssignMessage, aby sformatować odpowiedź dla aplikacji klienta, a następnie zalogować wiadomość za pomocą zasady MessageLogging. Zasady są wykonywane w kolejności, w jakiej zostały umieszczone (od góry do dołu w pliku XML).

Reguły błędów są wywoływane TYLKO w stanie błędu (informacje o kontynuowaniu: błąd)

Nagłówek może się wydawać, że się powtarzamy, ale trzeba pamiętać o jednym niuansie związanym z błędem serwera proxy powodującym wprowadzenie stanu błędu na serwerze proxy interfejsu API lub w przeciwnym razie nie wstawieniem stanu błędu – atrybutem continueOnError zasad.

Podsumowując: serwer proxy interfejsu API ocenia <FaultRules> i <DefaultFaultRule> tylko wtedy, gdy wystąpił błąd. Oznacza to, że nawet jeśli warunek FaultRule ma wartość prawda, nie zostanie aktywowany, jeśli serwer proxy nie jest w stanie błędu.

Poniżej znajdziesz jednak przykład wystąpienia błędu i niewprowadzenia stanu błędu przez serwer proxy. W przypadku dowolnej zasady możesz ustawić atrybut w elemencie nadrzędnym o nazwie continueOnError. Ten atrybut jest bardzo ważny w przypadku obsługi błędów, ponieważ określa, czy serwer proxy wprowadzi stan błędu w przypadku niepowodzenia zasady. W większości przypadków lepiej jest zachować domyślną wartość continueOnError="false". Spowoduje to wystąpienie błędu serwera proxy w przypadku błędu zasady i wywołanie niestandardowej obsługi błędów. Jeśli jednak continueOnError="true" (jeśli na przykład nie chcesz, aby wywołanie serwera proxy zatrzymało wywołanie serwera proxy, błąd tej zasady nie), to serwer proxy nie przejdzie w stan błędu, gdy ta zasada nie zadziała, a serwer proxy nie sprawdzi reguł FaultRule.

Informacje o błędach logowania występujących podczas continueOnError="true" znajdziesz w artykule Obsługa błędów zasad w bieżącym przepływie.

Gdzie można zdefiniować reguły błędów: ProxyEndpoint lub TargetEndpoint

Gdy w serwerze proxy interfejsu API wystąpi błąd, błąd występuje w <ProxyEndpoint> (żądanie z aplikacji klienckiej lub odpowiedź na nią) albo w <TargetEndpoint> (żądanie wysyłane do usługi docelowej lub odpowiedź z niej). Wszędzie tam, gdzie wystąpi błąd, Edge szuka reguł FaultRule.

Jeśli na przykład serwer docelowy jest niedostępny (kod stanu HTTP 503), serwer proxy interfejsu API przejdzie w stan błędu w odpowiedzi <TargetEndpoint>, a normalny przepływ serwera proxy interfejsu API nie przejdzie do interfejsu <ProxyEndpoint>. Jeśli reguły FaultRules są zdefiniowane tylko w obiekcie <ProxyEndpoint>, nie obsługują tego błędu.

Oto kolejny przykład. Jeśli zasada ClaimFault w odpowiedzi <ProxyEndpoint> wywoła błąd, reguła FaultRule w obiekcie <TargetEndpoint> nie zostanie wykonana.

FaultRules a zasada RemoveFault

Reguły błędów i ReturnFault mogą sprawiać wrażenie alternatywnych sposobów obsługi błędów, a pod pewnymi względami tak właśnie jest. Współdziałają one jednak również. Ta sekcja wyjaśnia relację między nimi. Zrozumienie tej relacji pomoże Ci w zaprojektowaniu sposobu obsługi błędów, zwłaszcza jeśli chcesz korzystać z obu.

W skrócie:

  • Reguły błędów są zawsze sprawdzane, gdy serwer proxy interfejsu API wprowadzi stan błędu.
  • Zasada RaiseFault pozwala wprowadzić serwer proxy interfejsu API w stan błędu, który w innym przypadku nie miałby miejsca.

    Jeśli na przykład chcesz zgłosić błąd, jeśli kod stanu HTTP w odpowiedzi z usługi docelowej ma wartość większą niż 200, dodaj zasadę romotingFault w przepływie odpowiedzi. 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 GrowFault wysyła też komunikat o błędzie do aplikacji klienckiej.

Co się dzieje, gdy zasada GrowFault wywoła błąd, co spowoduje, że serwer proxy zostanie w stanie błędu, co może spowodować wykonanie reguły FaultRule? Tutaj wszystko może być nieco skomplikowane. Co jest zwracane do aplikacji klienckiej, jeśli zasada CauseFault zwraca komunikat o błędzie, a reguła FaultRule zostanie aktywowana i zwróci komunikat o błędzie?

  • Ponieważ zasada FaultRule lub defaultFaultRule jest uruchamiana po zasadzie ClaimFault, wygrywa dane odpowiedzi FaultRule.
  • Dane odpowiedzi zasady ClaimFault (kod stanu, wyrażenie przyczyny lub ładunek wiadomości) są używane, jeśli te dane nie są ustawione przez FaultRule lub DomyślnieFaultRule.
  • Jeśli zarówno zasada GrowFault, jak i reguła FaultRule dodają niestandardowe nagłówki HTTP, obie te wartości zostaną uwzględnione w odpowiedzi. Zduplikowane nazwy nagłówków tworzą nagłówek z wieloma wartościami.

Oto przykład tego, co są ustawiane przez zasady ClaimFault i FaultRule oraz co jest zwracane do aplikacji klienckiej. Próbki mają na celu zwięzłość, a nie sprawdzone metody.

Aplikacja kliencka otrzymuje:

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

<- Zasada reguł błędów ustawia to:

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

<- ClaimFault ustawia tę zasadę:

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

Warunki budynków

Warunki są kluczem do wykonania reguły FaultRule. Warunki FaultRule możesz utworzyć w taki sam sposób jak w przypadku innych warunków w Edge, na przykład w przypadku przepływów warunkowych lub warunków romotingFault.

Aby umieścić resztę tej sekcji w kontekście, oto przykładowa reguła błędu, która ma zewnętrzny warunek reguły FaultRule i wewnętrzny warunek 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 szczegółowe dotyczące błędów zasad

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

fault.name

Jeśli zasada nie działa, wychwytuj błąd w warunku za pomocą zmiennej fault.name. Na przykład:

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

Nazwa błędu pojawia się w domyślnym komunikacie o błędzie. Na przykład w przykładzie poniżej nazwa błędu to FailedToResolveAPIKey. W tym przypadku zmienna przepływu o nazwie fault.name jest ustawiona na 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ć tak:

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

Listę błędów związanych z zasadami znajdziesz w dokumentacji błędów zasad.

{policy_namespace}.{policy_name}.failed

Zmienna *.failed jest dostępna, gdy zasada nie działa. Poniżej znajdziesz przykłady zmiennych *.failed dla różnych zasad. Informacje o przestrzeni nazw zasad znajdziesz w opisach zmiennych przepływu w poszczególnych tematach z omówieniem zasad.

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ł błąd.
  • Zmienne komunikatu HTTP, które istnieją w momencie błędu. Jeśli na przykład w odpowiedzi zostanie zwrócony błąd, reguła FaultRule w <TargetEndpoint> może użyć danych HTTP response.status.code, message.content, error.content itd. Jeśli nie uda się spełnić zasad limitów, możesz użyć zmiennej ratelimit.{quota_policy_name}.exceed.count. Aby ustalić, które zmienne i dane HTTP są dostępne, użyj narzędzia do śledzenia i informacji o zasadach.

Więcej informacji

  • Warunki: informacje o warunkach oraz zmienne i warunki przepływu.

  • Błędy: informacje o błędach zasad
  • Zmienne: odniesienie do zmiennych i wyświetlanie poszczególnych stron z informacjami o zasadach dotyczących zmiennych, które są dostępne w przypadku poszczególnych zasad.

Sprawdzone metody obsługi błędów

Obsługa błędów to główne zadanie związane z projektowaniem architektury podczas tworzenia serwerów proxy interfejsów API. Ważne jest, aby dobrze się zastanowić, jak i kiedy będziesz rozwiązywać problemy, określić treść komunikatów o błędach i zaprojektować ich format. Gdy już to zrobisz, skorzystaj z tych sprawdzonych metod, aby usprawnić obsługę błędów.

Poniżej znajduje się kilka sprawdzonych metod projektowania i usuwania usterek:

  • Dla każdej reguły FaultRule podaj „outer” <Condition> (element równorzędny wobec elementu <Step>). Reguły błędów bez warunku zewnętrznego automatycznie zwracają wartość prawda. Warunki kroku „Inner” nie są używane do określania, czy reguła FaultRule ma wartość prawda czy fałsz. Warunki kroku są sprawdzane dopiero po wykonaniu przez Edge reguły FaultRule, która je zawiera. W regule błędów często występuje wiele kroków z zasadami przypisywania wiadomości (lub innych), z których każdy zawiera warunek kroku.
  • Aby obsługiwać błędy w wielu zasadach tego samego typu (na przykład w wielu zasadach dotyczących limitów), utwórz 1 regułę FaultRule na błąd zasad, który prawdopodobnie wystąpi. Na przykład utwórz regułę FaultRule dla każdego prawdopodobnego błędu w zasadach limitów, takich jak QuotaViolation, InvalidMessageWeight lub StartTimeNotSupported. (Informacje o błędach związanych z zasadami znajdziesz w dokumentacji błędów zasad). Gdy znajdziesz kolejne błędy, które musisz przetworzyć, możesz wrócić i dodać je do reguł FaultRule. Możesz użyć iteracji, ale wymaga to ponownego wdrożenia serwera proxy. To podejście pozwala wychwytywać ten sam typ błędu bez względu na to, która zasada go generuje, co zwiększa efektywność pliku XML FaultRule.

    Jeśli potrzebujesz bardziej szczegółowej kontroli błędów, użyj wewnętrznych warunków kroku. Jeśli na przykład egzekwujesz zarówno limit indywidualny, jak i globalny, przy użyciu 2 zasad w przepływie żądania, ustaw „zewnętrzny” warunek FaultRule, aby był wywoływany po wystąpieniu błędu QuotaViolation (który jest wywoływany, gdy w obu przypadkach przekroczysz limit). Następnie ustaw warunki kroku, aby ocenić zmienne exceed.count w obu zasadach dotyczących limitów. Klient otrzyma tylko odpowiedni błąd (przekroczenie limitu dewelopera lub globalne przekroczenie limitu). Oto przykład tej 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>
    

    Innym przykładem jest ten wątek społeczności Apigee.

  • Aby obsługiwać błędy, gdy używasz pojedynczej zasady jednego typu, rozważ zastosowanie reguły z jednym błędem, która jest wykonywana w przypadku niepowodzenia jednej z zasad, i uwzględnij wiele kroków, które mapują się na każdy możliwy błąd. Zwiększa to efektywność kodu XML, ponieważ korzysta z jednej reguły FaultRule zamiast wielu reguł FaultRule (po jednej dla każdego typu 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 błędów, w których wystąpią błędy (po stronie klienta <ProxyEndpoint> lub po stronie docelowej <TargetEndpoint>). Uwzględnij reguły błędów dla każdej zasady, która pojawia się w każdej lokalizacji.
  • W FaultRules możesz uruchomić dowolny typ zasady, która może zwrócić wiadomość do aplikacji klienta. Idealnie sprawdza się w tym przypadku zasada AssignMessage. Jeśli chcesz śledzić błędy, rozważ zarejestrowanie wiadomości za pomocą zasady MessageLogging.
  • Jeśli używasz zasad PodnieśFault w połączeniu z regułami FaultRule, skoordynuj dane odpowiedzi wysyłane z powrotem, gdy zarówno zasada ClaimFault, jak i reguła FaultRule zwraca dane. Jeśli na przykład zasada ClaimFault resetuje kod stanu HTTP, to zasada FaultRule nie może resetować kodu stanu. Najgorsze, co może się zdarzyć, to zwrócenie domyślnego kodu stanu do aplikacji klienckiej.
  • Wykonanie <DefaultFaultRule>:
    • Jeśli chcesz, aby reguła <DefaultFaultRule> była zawsze wykonywana, gdy nie jest wykonywana żadna inna reguła FaultRule, nie dodawaj do niej elementu <Condition>.
    • Jeśli chcesz, aby reguła <DefaultFaultRule> była wykonywana zawsze nawet po wykonaniu innej reguły FaultRule, dodaj element podrzędny <AlwaysEnforce>true</AlwaysEnforce>.

Wzór scentralizowanej obsługi błędów wielokrotnego użytku

W tym poście w społeczności Apigee opisano wzorzec scentralizowanej obsługi błędów bez duplikowania 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 ProxyEndpoint lub TargetEndpoint. Możesz wprowadzić tę zmianę w interfejsie użytkownika Edge w panelu Kod w widoku Develop (Programowanie) dla serwera proxy interfejsu API lub zmodyfikować plik XML określający punkt końcowy lub docelowy punkt końcowy.

Jeśli utworzysz reguły błędów w interfejsie zarządzania, najpierw utwórz zasady, które chcesz wykonać, a następnie dodaj je do konfiguracji reguły błędów. Jeśli spróbujesz zapisać regułę błędów, która odwołuje się do zasady, która nie została jeszcze utworzona, pojawi się błąd w interfejsie.

Dodawanie zasad do reguły błędu

Możesz umieścić w regule FaultRule dowolną zasadę, ale często korzystasz z zasadyAssignMessage do generowania niestandardowego komunikatu z odpowiedzią na warunek błędu. Przypisanie wiadomości umożliwia skonfigurowanie odpowiedzi HTTP z ładunkiem, kodem stanu HTTP, nagłówkami i elementami z wyrażeniem powodu.

Przykład poniżej przedstawia typową konfigurację zasad 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ę na to, jak odwołujesz się do zasady AssignMessage według nazwy w 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 o nazwie fault_invalidkey za każdym razem, gdy aplikacja przedstawi nieprawidłowy klucz interfejsu API.

W regule FaultRule możesz uruchomić wiele zasad, tak jak 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. Możesz na przykład użyć zasady MessageLogging, ExtractVariables, zasady AssignMessage lub dowolnej innej zasady w FaultRule. Przetwarzanie reguły FaultRule zatrzymuje się natychmiast w jednej z tych sytuacji:

  • Każda zasada w regule błędów powoduje błąd
  • Każda zasada w regule FaultRule jest typu romotingFault

Zdefiniowanie niestandardowego komunikatu o błędzie zwracanego przez regułę FaultRule

Sprawdzoną metodą jest zdefiniowanie jasnych odpowiedzi na błędy w interfejsach API. Dzięki temu przekazujesz klientom spójne i przydatne informacje.

W poniższym przykładzie zasady AssignMessage użyto tagów <Payload>, <StatusCode> i <ReasonPhase> do zdefiniowania niestandardowej odpowiedzi na błąd odesłanej do klienta w przypadku błędu InvalidApiKey (zobacz poprzedni przykład 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.
  • Informacja o przyczynie, czyli krótki opis błędu.

Tworzenie reguły domyślnego błędu

Reguła defaultFaultRule działa jako moduł obsługi wyjątków w przypadku każdego błędu, który nie jest wyraźnie obsługiwany przez inną regułę FaultRule. Jeśli warunki w przypadku wszystkich reguł FaultRule nie są zgodne z błędem, błądDefaultFaultRule obsługuje ten błąd. Włącz domyślną obsługę błędów, dodając tag <DefaultFaultRule> jako element podrzędny punktu końcowego ProxyEndpoint lub TargetEndpoint.

Na przykład poniższa konfiguracja TargetEndpoint określa domyślną regułę FaultRule, która wywołuje zasadę o nazwie ReturnTypoweError:

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

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

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

RegułaDefaultFaultRule jest zwykle używana do zwrócenia ogólnego komunikatu o błędzie w przypadku dowolnego nieoczekiwanego błędu, na przykład wiadomości z danymi kontaktowymi pomocy technicznej. Ta domyślna odpowiedź ma 2 cel: dostarcza informacje łatwe dla programistów, a jednocześnie maskuje adresy URL backendu lub inne informacje, które mogą zostać użyte do naruszenia bezpieczeństwa systemu.

Możesz na przykład zdefiniować następującą zasadę AssignMessage w celu zwrócenia ogólnego błędu:

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

Umieść element <AlwaysEnforce> w tagu <DefaultFaultRule>, aby wykonywać regułęDefaultFaultRule w przypadku każdego błędu, nawet jeśli inna reguła FaultRule została już wykonana. Reguła defaultFaultRule jest zawsze ostatnią regułą FaultRule do wykonania:

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

Jednym z zastosowań regułyDefaultFaultRule jest określenie typu błędu, który występuje, gdy nie można go określić w inny sposób. Na przykład w przypadku serwera proxy interfejsu API występuje błąd, którego nie możesz określić. Użyj metodyDefaultFaultRule, aby wywołać następującą zasadę AssignMessage. Ta 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>

Następnie możesz wyświetlić nagłówek w narzędziu do śledzenia Edge lub w odpowiedzi, aby sprawdzić, co spowodowało błąd.

Dodaję logowanie wiadomości do PostClientFlow

PostClientFlow to jedyny przepływ, który jest wykonywany po wystąpieniu przez serwer proxy stanu błędu. Do tego procesu, który jest wykonywany po zwróceniu odpowiedzi do klienta, można dołączyć tylko zasadę MessageLogging. Chociaż dołączenie zasady MessageLogging do tego procesu nie stanowi obsługi błędów, możesz jej użyć do rejestrowania informacji, gdy wystąpi błąd. Ponieważ jest uruchamiana niezależnie od tego, czy użycie serwera proxy powiodło się, czy nie, możesz umieścić zasady usługi Message Logging w PostClientFlow, aby mieć pewność, że będą zawsze wykonywane.

Obsługa błędów zasad w bieżącym przepływie

Wszystkie przedstawione do tej pory przykłady używają reguły FaultRule w punkcie końcowym ProxyEndpoint lub TargetEndpoint do obsługi wszelkich błędów zasad w ramach stanu błędu. Dzieje się tak, ponieważ domyślną wartością elementu continueOnError zasady jest false, co oznacza, że gdy w zasadzie wystąpi błąd, element sterujący kieruje do stanu błędu. W stanie błędu nie można przywrócić kontroli do normalnego potoku i zwykle do aplikacji wywołującej wyświetlany jest jakiś komunikat o błędzie.

Jeśli jednak ustawisz dla zasady element continueOnError na true, element sterujący pozostanie w bieżącym przepływie, a kolejna zasada w potoku zostanie uruchomiona po zasadzie, która spowodowała błąd. Zaletą obsługi błędu w ramach bieżącego procesu jest to, że możesz go naprawić, aby zakończyć przetwarzanie żądania.

Poniżej widoczna jest zasadaVerifyAPIKey o nazwie verify-api-key z elementem continueOnError ustawionym 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, zasada VerifyAPIKey ustawia zmienną oauthV2.verify-api-key.failed na true, ale przetwarzanie jest kontynuowane w bieżącym procesie.

Następnie musisz dodać zasadę ConfirmAPIKey jako krok w przebiegu wstępnym 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 następny krok w PreFlow używa warunku do sprawdzenia, czy wystąpił błąd. Jeśli w zasadzie VerifAPIKey wystąpił błąd, zostanie uruchomiona zasada o nazwie FaultInFlow. W przeciwnym razie zasada FaultInFlow jest pomijana. Zasada FaultInFlow może wykonywać wiele czynności, np. rejestrować błąd, podejmować próby naprawienia błędu lub wykonywać inne działania.

Aktywowanie błędu przy użyciu zasady romotingFault

Aby wywołać błąd, możesz w dowolnym momencie użyć zasady ClaimFault. Gdy zasada GrowFault zostanie wykonana, zakończy bieżący przepływ i przenosi kontrolę do stanu błędu.

Jednym z zastosowań zasady ClaimFault jest testowanie pod kątem określonego warunku, którego inna zasada może nie wykryć. W przykładzie powyżej do tagu <Condition> PreFlow <Step> dodano tag <Condition>, który powodował wykonanie zasady FaultInFlow po spełnieniu warunku. Jeśli FaultInFlow jest zasadą GrowFault, kontrola przełączy się do stanu błędu. Możesz też wstawić zasadę MoveFault w przepływie, aby debugować i przetestować reguły FaultRule.

Gdy zasada MoveFault wywoła błąd, możesz użyć tej reguły FaultRule i warunku, aby ją przetworzyć:

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

Zwróć uwagę, że warunek sprawdza błąd o nazwie RaiseFault. Zasada GrowFault 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 spowodowanych przez zasady. Możesz też utworzyć niestandardową odpowiedź na błędy na poziomie transportu, co oznacza błędy HTTP zwracane z serwera docelowego. Aby kontrolować odpowiedź z błędu HTTP, skonfiguruj obiekt TargetEndpoint do przetwarzania kodów odpowiedzi HTTP.

Domyślnie Edge traktuje kody odpowiedzi HTTP z zakresu 1xx–3xx jako „sukces”, a kody odpowiedzi HTTP z zakresu od 4xx do 5xx – jako „failure”. Oznacza to, że każda odpowiedź usługi backendu z kodem odpowiedzi HTTP 4xx-5xx automatycznie wywołuje stan błędu, który następnie zwraca komunikat o błędzie bezpośrednio do klienta wysyłającego żądanie.

Możesz utworzyć niestandardowe moduły obsługi dla dowolnych kodów odpowiedzi HTTP. Możesz na przykład nie traktować wszystkich kodów odpowiedzi HTTP z zakresu 4xx–5xx jako „failure” (niepowodzenie), ale tylko 5xx, albo zwracać niestandardowe komunikaty o błędach w przypadku kodów odpowiedzi HTTP 400 i 500.

W następnym przykładzie użyjesz właściwości success.codes, aby skonfigurować punkt końcowy tak, aby traktował jako udane kody odpowiedzi HTTP 400 i 500 wraz z domyślnymi kodami HTTP. Oznaczając, że te kody są udane, docelowy punkt końcowy przejmuje przetwarzanie komunikatu z odpowiedzią, 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, możesz użyć symboli wieloznacznych, aby ustawić we właściwości success.codes zakres wartości.

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

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

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

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

Możesz teraz zdefiniować niestandardowe moduły obsługi dla kodów odpowiedzi HTTP 400 i 500, aby zwracać niestandardową odpowiedź do aplikacji żądającej. Ten docelowy punkt końcowy używa 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 punktu końcowego docelowego powoduje, że zasada ReturnError obsługuje odpowiedź za każdym razem, gdy obiekt TargetEndpoint napotka kod odpowiedzi HTTP 400 lub 500.

Mapa błędów

Usługi interfejsu API dzielą błędy na następujące kategorie i podkategorie.

Kategoria Podkategoria Nazwa błędu Opis
Wiadomości Błędy występujące podczas procesu przesyłania wiadomości (z wyłączeniem błędów zasad)
Błędy niestandardowe {fault_name} Wszelkie błędy jawnie obsługiwane przez serwer proxy interfejsu API za pomocą zasady romotingFault
Kody odpowiedzi Wewnętrzny błąd serwera, nie znaleziono Kody błędów HTTP 5xx, 4xx
Niepowodzenia routingu NoRoutesMatched Nie udało się wybrać nazwanego punktu końcowego docelowego dla żądania
Błędy klasyfikacji NotFound Awarie spowodowane przez identyfikator URI żądania, który nie pasuje do żadnej ścieżki BasePath w przypadku żadnej konfiguracji ProxyEndpoint (czyli żadne serwery proxy interfejsu API nie pasują do adresu URL w żądaniu aplikacji klienckiej)
Transport Błędy HTTP na poziomie transportu
Połączenia Odmowa połączenia, Resetowanie połączenia, Przekroczono limit czasu połączenia Błędy występują podczas nawiązywania połączeń na poziomie sieci lub transportu
Poproś o weryfikację Brak długości treści, Brak nagłówka hosta Błędy występują podczas kontroli semantycznej każdego żądania
Weryfikacje odpowiedzi Błędy występują podczas sprawdzania semantyki każdej odpowiedzi
Błędy wejścia-wyjścia SSLHandshakeError, ReadTimeout, ReadError, WriteTimeout, WriteError, ChunkError. Błędy odczytu/zapisu w punktach końcowych klienta lub docelowego, przekroczenie czasu oczekiwania, błędy TLS/SSL i błędy podziału
System Niezdefiniowane błędy środowiska wykonawczego
Pamięć Za mało pamięci, GCOverLimit Awarie związane z pamięcią
Wątek RogueTaskTerminated Błędy, takie jak zakończenie zadań działających poza domem
Zasady Błędy każdego typu zasady są zdefiniowane w dokumentacji zasad.

Błąd zawsze jest uzupełniany przez tekstowy opis przyczyny niepowodzenia. Gdy system zgłasza błąd, uzupełniany jest zbiór atrybutów, aby ułatwić rozwiązywanie problemów. Błąd zawiera te informacje:

  • Przyczyna
  • Atrybuty niestandardowe zdefiniowane przez użytkownika