Kontrolowanie działania serwera proxy za pomocą przepływów

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

Każdy model programowania aplikacji pozwala kontrolować przepływ przetwarzania. W przypadku serwera proxy interfejsu API robi to przepływy. Do przepływów dodaj funkcje logiczne, instrukcje warunku, obsługę błędów itp. Dzięki przepływom możesz kontrolować, co i kiedy ma się wydarzyć.

Przepływy to sekwencyjne etapy na ścieżce przetwarzania żądań do interfejsu API. Gdy dodajesz logikę serwera proxy, na przykład w celu weryfikacji klucza interfejsu API, dodajesz ją jako krok w sekwencji określonej przez przepływ. Gdy definiujesz warunek określający, czy i kiedy logika ma być wykonywana, dodaj go do przepływu.

Poniższy przykład konfiguracji przepływu definiuje przepływ, w którym jest wykonywana zasadaVerifyAPIKey, if ścieżka żądania przychodzącego kończy się na /, a czasownik HTTP żądania to GET.

<Flow name="Get Food Carts">
    <Description>Get Food Carts</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Wartość Verify-API-Key w elemencie <Name> przepływu służy do dołączania zasady skonfigurowanej w innym miejscu na serwerze proxy za pomocą kodu XML, na przykład:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <Properties/>
    <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

Projektowanie sekwencji wykonywania przepływu

Tworząc przepływy w taki sposób, aby logika była uruchamiana w odpowiedniej kolejności na ścieżce przetwarzania.

Podejmując decyzję, gdzie dodać logikę, najpierw zdecyduj, czy chcesz ją dodać do punktu końcowego serwera proxy czy do docelowego punktu końcowego. Serwer proxy interfejsu API dzieli swój kod na kod wchodzący w interakcję z klientem serwera proxy (punkt końcowy serwera proxy) i opcjonalny kod, który wchodzi w interakcję z docelowym backendem serwera proxy (jeśli taki istnieje).

Oba punkty końcowe zawierają przepływy. Opisaliśmy je w tym artykule:

Typ punktu końcowego Opis Przepływy obsługiwane
ProxyEndpoint Zawiera przepływy serwera proxy interfejsu API najbliższe klientowi. Zapewnia miejsca, w których logika może działać jako pierwsza na żądanie klienta, a następnie na końcu odpowiedzi klienta. PreFlow, przepływy warunkowe, PostFlow, PostClientFlow
TargetEndpoint Zawiera przepływy serwera proxy interfejsu API najbliżej zasobu backendu. Zapewnia miejsca na potrzeby logicznego przygotowania żądania, a następnie obsługi odpowiedzi z zasobu backendu. PreFlow, przepływy warunkowe, PostFlow

Konfigurujesz przepływ za pomocą kodu XML, który określa, co ma się stać i w jakiej kolejności. Ilustracja poniżej pokazuje kolejność przepływów w punkcie końcowym serwera proxy i w docelowym punkcie końcowym:

Żądanie od klienta HTTP przechodzące przez punkt końcowy serwera proxy do docelowego punktu końcowego w backendzie, aby dotrzeć do usługi HTTP. Każdy panel żądania i odpowiedzi pokazuje przepływ wstępny, przepływy warunkowe i przepływ końcowy. Dodatkowo podane są przykłady punktu końcowego serwera proxy i docelowego punktu końcowego.

Punkt końcowy serwera proxy i docelowy punkt końcowy zawierają przepływy, które możesz rozmieścić w tej kolejności:

Pozycja Typ przepływu Opis
1 PreFlow

Ta opcja jest przydatna, gdy chcesz mieć pewność, że określony kod zostanie wykonany, zanim cokolwiek się stanie.

Jeśli obiekt PreFlow znajduje się w docelowym punkcie końcowym, uruchamia się po PostFlow punktu końcowego serwera proxy.
2 Przepływ warunkowy

Miejsce na logikę warunkową. Wykonuje się po przepływie wstępnym i przed przepływem postFlow.

W każdym segmencie wykonywany jest tylko 1 proces warunkowy – pierwszy przepływ, którego warunek przyjmuje wartość prawda. Oznacza to, że w ramach każdego z tych elementów możesz wykonać 1 proces warunkowy:
  • Potok żądań ProxyEndpoint
  • Potok żądań elementu TargetEndpoint
  • Potok odpowiedzi ProxyEndpoint
  • Potok odpowiedzi elementu TargetEndpoint
3 PostFlow

Dobre miejsce na potrzeby rejestrowania danych, wysłania powiadomienia o jakimś zdarzeniu podczas przetwarzania żądania itd. Wykonuje po przepływach warunkowych i PreFlow.

Jeśli PostFlow jest w punkcie końcowym serwera proxy i istnieje docelowy punkt końcowy, punkt końcowy serwera proxy PostFlow zostanie wykonany przed docelowym punktem końcowym PreFlow.
4 PostClientFlow (tylko przepływ proxy) Przepływ komunikatów po zwróceniu odpowiedzi do klienta.

Uruchamianie kodu za pomocą PreFlow

Jest on przydatny, gdy chcesz mieć pewność, że określony kod zostanie uruchomiony, zanim cokolwiek się stanie.

W punkcie końcowym serwera proxy jest doskonałym miejscem na kod, który uwierzytelnia klienta i ogranicza ruch z klientów. W docelowym punkcie końcowym, gdzie zaczyna się przygotowywać się do wysłania żądania do miejsca docelowego backendu, proces PreFlow sprawdza się w pierwszych krokach przygotowań do wysłania żądania.

Na przykład zwykle nie chcesz obsługiwać klienta, który przekroczył swój limit. Aby spełnić te wymagania, umieszczasz zasady zabezpieczeń i limitów w segmencie PreFlow. Dzięki temu nie musisz się martwić, że warunek nie zostanie oceniony w późniejszym procesie warunkowym. Zasady w tym procesie będą zawsze wykonywane przed rozpoczęciem przetwarzania.

W poniższym przykładzie zasady SpikeArrest i limitów są wykonywane przed przetworzeniem przejść do przepływów warunkowych.

<PreFlow name="MyPreFlow">
    <Request>
        <Step>
            <Name>Spike-Arrest</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
</PreFlow>

Warunkowe wykonywanie kodu z użyciem przepływu warunkowego

Między przepływem wstępnym a PostFlow mogą występować przepływy wykonywane warunkowo. Pozwala to skonfigurować wiele sekwencji logicznych, ale na podstawie stanu serwera proxy może być wykonywane tylko raz. Proces warunkowy jest opcjonalny, jeśli możesz wykonać całą logikę we PreFlow lub PostFlow i nie są wymagane żadne warunki (czyli obsługiwana jest tylko jedna ścieżka przez punkt końcowy).

Każdy proces określa warunek, który sprawdza różne wartości stanu. Efektywnie rozgałęzia to wykonywanie wykonania na podstawie warunków. Możesz na przykład skonwertować kod XML na JSON tylko wtedy, gdy aplikacja żądająca działa na urządzeniu mobilnym.

W tym przypadku ograniczenia limitów są egzekwowane tylko wtedy, gdy żądanie jest żądaniem GET ze wzorcem identyfikatora URI /issue/** (/issue/ z dowolnym elementem identyfikatora URI po ostatnim ukośniku).

<Flow name="MyFlow">
    <Description/>
    <Request>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>

Do określania warunków używasz zmiennych przepływu. Więcej informacji o używaniu zmiennych w warunkach znajdziesz w artykule Warunki ze zmiennymi przepływu.

Przykłady korzystania z dopasowania do wzorca w warunkach znajdziesz w sekcji Dopasowywanie do wzorca.

Wykonywanie kodu po głównej logice za pomocą postFlow

PostFlow to świetne miejsce do wykonywania działań po głównej logice punktu końcowego, a przed zakończeniem przetwarzania punktu końcowego. Element PostFlow jest wykonywany po zastosowaniu przepływów warunkowych i PreFlow.

PostFlow to dobre miejsce do rejestrowania niektórych danych, wysyłania powiadomień o zdarzeniach, przekształcania formatu wiadomości z odpowiedzią itp.

W poniższym przykładzie zasada AssignMessage o nazwie SetResponseHeaders ustawia nagłówki wiadomości z odpowiedzią przed wysłaniem odpowiedzi z powrotem do klienta przez Apigee Edge.

<PostFlow>
    <Response>
        <Step>
            <Name>SetResponseHeaders</Name>
        </Step>
    </Response>
 </PostFlow>

Uruchamianie kodu po otrzymaniu odpowiedzi od serwera proxy za pomocą PostClientFlow

Obiekt PostClientFlow może zawierać następujące zasady:

* Zasada FlowCallout może wywoływać tylko przepływy udostępnione, które spełniają kryteria warunku PostClientFlow (tzn. zawierają tylko zgodne zasady).

Jeśli dodasz algorytm PostClientFlow, będzie to ostatni przepływ wykonywany po wysłaniu odpowiedzi do klienta.

Proces PostClientFlow jest odpowiedni do końcowego logowania. Możesz też zapisać sygnatury czasowe rozpoczęcia i zakończenia wiadomości z odpowiedzią.

Oto przykład obiektu PostClientFlow z dołączoną zasadą MessageLogging.

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

Film: obejrzyj ten krótki film pokazujący, jak utworzyć obiekt PostClientFlow przy użyciu zasady MessageLogging z serii Four Minute Video For Developers (4MV4D).

Aby dowiedzieć się więcej, zobacz:

Dodawanie logiki do przepływów

Aby to zrobić, dodaj zasady do przepływów serwera proxy. Tak samo jak przepływy są wykonywane w sekwencji (PreFlow, a potem Flow, a PostFlow, jak opisano w tym temacie), zawartość przepływu jest wykonywana w sekwencji.

Poniższa przykładowa konfiguracja przepływu odwołuje się do 3 zasad (skonfigurowanych w innym miejscu we własnych plikach XML). Zasada, do której odwołuje się Verify-API-Key, jest uruchamiana przed zasadą, do której odwołuje się Remove-API-Key. Po obu stronach znajduje się zasada reprezentowana przez Quota.

<Flow name="Get Food Cart Menus">
    <Description>Get Food Cart Menus</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
        <Step>
            <Name>Remove-API-Key</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Konsola Apigee Edge prezentuje tę sekwencję zasad w postaci wiersza ikon, w których każda ikona reprezentuje zasadę.

Konsola Apigee Edge prezentuje tę sekwencję zasad w postaci wiersza ikon, w których każda ikona reprezentuje zasadę. Ikony wyświetlane na ścieżce żądania obejmują te ikony: Weryfikowanie klucza interfejsu API, usuwanie klucza interfejsu API i limit

Procesy debugowania

Narzędzie Apigee Edge Trace w formie graficznej pozwala sprawdzić, jak jest wykonywana logika serwera proxy interfejsu API po otrzymaniu żądania. Narzędzie pokazuje przetwarzanie między żądaniami a odpowiedziami. Nie przedstawia bezpośrednio różnicy między przepływami PreFlow, warunkowymi i PostFlow.

Więcej informacji o śledzeniu serwerów proxy znajdziesz w artykule Korzystanie z narzędzia do śledzenia.

Obsługa błędów w przepływach

Możesz zgłaszać błędy z różnych miejsc w serwerze proxy interfejsu API, w tym z przepływów.

Poniższy przykład to sekcja odpowiedzi z procesu wstępnego przepływu w docelowym punkcie końcowym. Inaczej mówiąc, jest to kod, który jest wykonywany natychmiast po otrzymaniu odpowiedzi z celu backendu. W tym przykładzie błąd jest zgłaszany, jeśli odpowiedź z celu nie wynosi 200 (sukces).

<PreFlow name="PreFlow">
    <Response>
        <Step>
            <Name>RaiseFault</Name>
            <Condition>(response.status.code GreaterThan "200")</Condition>
        </Step>
    </Response>
</PreFlow>

Więcej informacji o obsłudze błędów znajdziesz w artykule na temat obsługi błędów.