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

Wyświetlasz dokumentację Apigee Edge.
Zapoznaj się z dokumentacją Apigee X. Informacje

Każdy model programowania aplikacji obejmuje sposób kontrolowania przepływu przetwarzania. W przypadku serwera proxy interfejsu API odbywa się to za pomocą przepływów. Do przepływów dodajesz logikę, instrukcje warunku, obsługę błędów itd. Za pomocą przepływów możesz określać, co ma się dziać i kiedy.

Sekwencje to kolejne etapy na ścieżce przetwarzania żądania 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 danych. Gdy definiujesz warunek określający, czy i kiedy logika ma być wykonywana, dodaj go do przepływu.

W tym przykładzie konfiguracji przepływu zdefiniowano przepływ, w którym zasada VerifyAPIKey jest wykonywana jeśli ścieżka przychodzącego żądania 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 powoduje dodanie 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

Przepływy są tak skonstruowane, aby logika mogła być wykonywana we właściwej kolejności na ścieżce przetwarzania.

Podczas podejmowania decyzji o tym, gdzie dodać logikę, najpierw zdecyduj, czy chcesz dodać ją do punktu końcowego serwera proxy czy docelowego punktu końcowego. Pośrednik interfejsu API dzieli swój kod na kod, który współdziała z klientami pośrednika (punkt końcowy pośrednika), oraz opcjonalny kod, który współdziała z celami backendu pośrednika (jeśli takie istnieją).

Oba punkty końcowe zawierają przepływy, jak opisano tutaj:

Typ punktu końcowego Opis Obsługiwane przepływy
ProxyEndpoint Zawiera przepływy serwera proxy interfejsu API najbliższe klientowi. Udostępnia miejsca, w których logika najpierw działa w odpowiedzi na żądanie klienta, a na końcu odpowiada klientowi. PreFlow, przepływy warunkowe, PostFlow, PostClientFlow
TargetEndpoint Zawiera przepływy proxy interfejsu API najbliższe zasobowi backendu. Udostępnia miejsca na potrzeby logiki umożliwiające przygotowanie żądania, a następnie obsługę odpowiedzi z zasobu backendu. PreFlow, przepływy warunkowe, PostFlow

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

Żądanie od klienta HTTP przechodzące przez punkt końcowy serwera proxy do docelowego punktu końcowego w backendzie w celu dotarcia do usługi HTTP. Każdy panel żądań i odpowiedzi zawiera proces wstępny, procesy warunkowe i procesy po żądaniu. Dodatkowo podane są przykłady punktu końcowego serwera proxy i docelowego punktu końcowego.

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

Pozycja Typ przepływu Opis
1 PreFlow

Jest to przydatne, gdy chcesz mieć pewność, że określony kod zostanie wykonany przed wszystkimi innymi.

Jeśli funkcja PreFlow znajduje się w docelowym punkcie końcowym, jest wykonywana po wystąpieniu PostFlow punktu końcowego serwera proxy.
2 Przepływ warunkowy

Pole na logikę warunkową. Jest wykonywane po wystąpieniu PreFlow i przed przepływem PostFlow.

Na każdy segment jest wykonywany tylko jeden przepływ warunkowy – pierwszy, którego warunek przyjmuje wartość prawda. Oznacza to, że w ramach każdego z tych procesów możesz wykonać 1 przepływ warunkowy:
  • Potok żądań ProxyEndpoint
  • Potok żądań do usługi TargetEndpoint
  • Potok odpowiedzi ProxyEndpoint
  • Potok odpowiedzi TargetEndpoint
3 PostFlow

Dobre miejsce na rejestrowanie danych, wysyłanie powiadomień o wystąpieniu błędu podczas przetwarzania żądania itp. Wykonywane po przepływach warunkowych i PreFlow.

Jeśli obiekt PostFlow znajduje się w punkcie końcowym serwera proxy i istnieje docelowy punkt końcowy, punkt końcowy PostFlow serwera proxy jest wykonywany przed docelowym punktem końcowym PreFlow.
4 PostClientFlow (tylko przepływ serwera proxy) Proces rejestrowania wiadomości po przesłaniu odpowiedzi do klienta.

Wykonywanie kodu za pomocą PreFlow

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

W punkcie końcowym serwera proxy PreFlow to świetne miejsce na kod, który uwierzytelnia klienta i ogranicza ruch z klientów. W punkcie końcowym docelowym, w którym rozpoczyna się przygotowywanie do wysłania żądania do celu backendowego, preflow jest przydatne na etapie przygotowywania do wysyłania żądania.

Na przykład zwykle nie obsługujemy klienta, który przekroczył 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 innymi procesami przetwarzania.

W tym przykładzie reguły SpikeArrest i Quota są wykonywane przed przekazaniem przetwarzania 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

Pomiędzy PreFlow a PostFlow możesz mieć przepływy, które są wykonywane warunkowo. Pozwala to skonfigurować wiele sekwencji logiki, ale tylko jedno wykonanie jest zależne od stanu serwera proxy. Przepływ warunkowy jest opcjonalny, jeśli możesz wykonać całą logikę w PreFlow lub PostFlow i nie są wymagane żadne warunki (czyli obsługiwana jest tylko 1 ścieżka prowadząca przez punkt końcowy).

Każdy przepływ określa warunek, który testuje różne wartości stanu. Dzięki temu możesz warunkowo rozdzielać wykonywanie kodu. Konwertowanie XML na JSON może być na przykład korzystne tylko wtedy, gdy aplikacja żądająca dostępu jest uruchomiona na urządzeniu mobilnym.

W tym przypadku ograniczenia limitów są egzekwowane tylko wtedy, gdy żądanie jest żądaniem GET z wzorcem URI /issue/** (/issue/ z wszystko, co w identyfikatorze URI występuje 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>

Warunki określasz za pomocą zmiennych przepływu. Więcej informacji o używaniu zmiennych w warunkach znajdziesz w artykule Warunki z użyciem zmiennych przepływu.

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

wykonywanie kodu po głównej logice w PostFlow;

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

Pole PostFlow to dobre miejsce do rejestrowania niektórych danych, wysyłania powiadomienia o wystąpieniu zdarzeń, przekształcania formatu wiadomości z odpowiedzią itp.

W tym przykładzie zasada przypisywania wiadomości o nazwie SetResponseHeaders ustawia nagłówki wiadomości odpowiedzi, zanim Apigee Edge wyśle odpowiedź z powrotem do klienta.

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

Wykonywanie kodu po otrzymaniu przez klienta odpowiedzi z serwera proxy za pomocą funkcji PostClientFlow

Interfejs PostClientFlow może obejmować następujące zasady:

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

Jeśli go dodasz, ostatnim przepływem do wykonania będzie PostClientFlow, który będzie wykonywany po wysłaniu odpowiedzi do klienta.

Przepływ PostClientFlow jest dobrym rozwiązaniem do ostatecznego rejestrowania danych. Możesz też zapisać sygnaturę czasową rozpoczęcia i zakończenia wiadomości z odpowiedzią.

Oto przykład interfejsu 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ć raport PostClientFlow za pomocą zasad MessageLogging z serii Four Minute Video For Developers (4MV4D).

Aby dowiedzieć się więcej, zobacz:

Dodawanie logiki do przepływów

Dodając logikę do serwera proxy, dodajesz zasady do jego przepływów. Tak jak przepływy są wykonywane w sekwencji (PreFlow, następnie Flow, a PostFlow, zgodnie z tym tematem), zawartość przepływu jest wykonywana w sekwencji.

Poniżej przykładowa konfiguracja procesu odwołuje się do 3 zasad (skonfigurowanych w innych plikach XML). Zasada, do której odwołuje się Verify-API-Key, jest wykonywana przed zasadą, do której odwołuje się Remove-API-Key. Obie są poprzedzone zasadą, do której odwołuje się 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>

Konsole Apigee Edge przedstawiają tę sekwencję zasad jako rząd ikon, z których każda reprezentuje jedną zasadę.

Konsola Apigee Edge przedstawia tę sekwencję zasad jako rząd ikon, z których każda reprezentuje jedną zasadę. Ikony wyświetlane w ścieżce żądania obejmują Weryfikowanie klucza interfejsu API, Usuń klucz interfejsu API oraz Limit

Debugowanie przepływów

Narzędzie Apigee Edge Trace umożliwia graficzne wyświetlanie sposobu działania logiki w Twoim interfejsie API po otrzymaniu żądania. Narzędzie to ilustruje przetwarzanie żądania i odpowiedzi. Nie przedstawia wyraźnie podziału na sekcje PreFlow, warunkowe i PostFlow.

Więcej informacji na temat śledzenia serwerów proxy znajdziesz w artykule na temat używania narzędzia Trace.

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

Błędy możesz zgłaszać w różnych miejscach w pośredniku API, m.in. w przepływach.

Poniższy przykład to zwrotka odpowiedzi z preFlow w docelowym punkcie końcowym – innymi słowy, jest to kod, który jest wykonywany natychmiast po otrzymaniu odpowiedzi z docelowego backendu. W tym przykładzie błąd jest zgłaszany, jeśli odpowiedź z elementu docelowego nie wynosi 200 (powodzenie).

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

Więcej informacji o postępowaniu w przypadku błędów znajdziesz w artykule Zarządzanie błędami.