Kontrolowanie wykonywania serwera proxy za pomocą przepływów

Oglądasz dokumentację Apigee Edge.
Wyświetl dokumentację Apigee X.

Każdy model programowania aplikacji umożliwia kontrolowanie procesu przetwarzania. Na serwerze proxy interfejsu API odbywa się to przez przepływy. Do przepływów dodajesz funkcje logiczne, instrukcje dotyczące warunków, obsługę błędów itd. Wzorzec pozwala kontrolować, co i kiedy się dzieje.

Przepływy to kolejne etapy na ścieżce przetwarzania żądań do interfejsu API. Podczas dodawania logiki serwera proxy, np. w celu zweryfikowania klucza interfejsu API, musisz je dodać jako krok w sekwencji określonej przez przepływ. Gdy definiujesz warunek, który określa, czy i kiedy funkcje logiczne mają być wykonywane, dodajesz go do przepływu.

Poniższa przykładowa konfiguracja przepływu definiuje przepływ, w którym zasada WeryfikacjaAPIKey wykonuje jeśli ś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 pozwala dołączyć zasady XML do innych miejsc na serwerze proxy, takie jak:

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

Porządkujesz przepływy, aby wykonywać działania logiczne w odpowiedniej kolejności na ścieżce przetwarzania.

Wybierając miejsce, od którego zależy logika, musisz najpierw wybrać, czy ma on zostać dodany do punktu końcowego serwera proxy, czy do punktu końcowego. Serwer proxy interfejsu API dzieli swój kod między kod, który komunikuje się z klientem serwera proxy (punktem końcowym serwera proxy) a opcjonalnym kodem, który wchodzi w interakcję z celem backendu serwera proxy (o ile występuje) (docelowy punkt końcowy).

Oba punkty końcowe zawierają przepływy w sposób opisany poniżej:

Typ punktu końcowego Opis Obsługiwane przepływy
Punkt końcowy serwera proxy Zawiera przepływy proxy interfejsu API najbliżej klienta. Umożliwia logice reagowanie na żądanie klienta w pierwszej kolejności, a dopiero potem na odpowiedź klienta. PreFlow, przepływy warunkowe, PostFlow, PostClientFlow
Punkt końcowy Zawiera przepływy proxy interfejsu API najbliżej zasobu backendu. Udostępnia miejsca logiczne na potrzeby przygotowywania żądania oraz obsługi odpowiedzi z zasobu backendu. PreFlow, przepływy warunkowe, PostFlow

Konfiguracja w pliku XML pozwala określić, co ma się wydarzyć i w jakiej kolejności. Ilustracja poniżej pokazuje, jak przepływy są sekwencyjne w obrębie punktu końcowego serwera proxy i docelowego punktu końcowego:

Żądanie klienta HTTP przechodzącego przez punkt końcowy serwera proxy do docelowego punktu końcowego w backendzie w celu uzyskania dostępu do usługi HTTP. Każde żądanie i panel odpowiedzi zawierają proces wstępny, proces warunkowy i post. Zobaczysz też przykłady punktów końcowych serwera proxy i docelowego punktu końcowego.

Każdy punkt końcowy serwera proxy i punkt końcowy zawierają przepływy, które możesz uporządkować w tej sekwencji:

Pozycja Rodzaj przepływu Opis
1 Wstęp

Ta opcja przydaje się, gdy chcesz mieć pewność, że określony kod zostanie uruchomiony, zanim coś się stanie.

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

Miejsce na logikę warunkową. Wykonywany po parametrze PreFlow i przed nim.

W segmencie wykonywany jest tylko 1 przepływ warunkowy – pierwszy, którego warunek przyjmuje wartość „prawda”. Oznacza to, że można przeprowadzać jeden przepływ warunkowy w ramach każdego:
  • Potok żądania ProxyEndpoint
  • Potok żądania TargetEndpoint
  • Potok odpowiedzi ProxyEndpoint
  • Potok odpowiedzi w punkcie końcowym
3 PostFlow

To dobre miejsce na zapisanie danych, wysłanie powiadomienia, że coś poszło nie tak podczas przetwarzania żądania itd. Wykonywany po przepływach warunkowych i PreFlow.

Jeśli PostFlow znajduje się w punkcie końcowym serwera proxy, a istnieje docelowy punkt końcowy, PostFlow punktu końcowego serwera zostanie wykonany przed docelowym punktem końcowym punktu końcowego.
4 PostClientFlow (tylko przepływ proxy) Procedura logowania wiadomości po zwróceniu odpowiedzi klientowi.

Wykonanie kodu za pomocą PreFlow

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

W punkcie końcowym serwera proxy PreFlow jest świetnym miejscem na kod uwierzytelniania klienta i ograniczenie ruchu z niego. W przypadku docelowego punktu końcowego, w którym zaczyna się wysyłanie żądania do docelowego backendu, PreFlow jest dobrym pierwszym etapem przygotowań do wysłania żądania.

Raczej nie chcesz na przykład obsługiwać klienta, który przekroczył limit. Aby spełnić te wymagania, umieść zasady zabezpieczeń i limitów w segmencie PreFlow. Dzięki temu nie musisz się martwić, że jakiś warunek nie wyświetli się później. Zasady tego przepływu będą zawsze wykonywane przed rozpoczęciem innego przetwarzania.

W poniższym przykładzie zasady SpikeArrest i Quota są wykonywane przed przetwarzaniem kart do przepływów warunkowych.

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

Wykonanie kodu warunkowo zgodnie z przepływem warunkowym

Między PreFlow a PostFlow mogą występować przepływy, które są warunkowo wykonywane. Umożliwi to skonfigurowanie wielu sekwencji logicznych, ale tylko 1 wykonanie na podstawie stanu serwera proxy. Przepływ warunkowy jest opcjonalny, jeśli możesz wykonać wszystkie funkcje logiczne w ramach PreFlow lub PostFlow i nie są wymagane żadne warunki (tzn. 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. To skutecznie rozgałęzia wykonanie zgodnie z warunkami. Na przykład możesz przekonwertować 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 jakimkolwiek identyfikatorem 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>

Aby określić warunki, używasz zmiennych przepływu. Więcej informacji o używaniu zmiennych w warunkach znajdziesz w artykule Warunki ze zmiennymi przepływu.

Przykłady zastosowania dopasowania do warunków znajdziesz w artykule Dopasowanie wzorców.

Wykonanie kodu po głównej logice za pomocą PostFlow

PostFlow to świetne miejsce do wykonywania działań po zakończeniu logicznej procedury końcowego, a przed zakończeniem przetwarzania punktów końcowych. PostFlow wykonuje po przepływach warunkowych i PreFlow.

PostFlow to dobre miejsce na rejestrowanie pewnych danych, wysyłanie powiadomień o czegoś, przekształcanie formatu wiadomości z odpowiedzią itp.

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

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

Wykonanie kodu po tym, jak klient otrzyma odpowiedź serwera proxy za pomocą PostClientFlow

PostClientFlow może zawierać te zasady:

* Zasada Flowflow może wywoływać tylko te przepływy współdzielone, które spełniają kryteria obecności w PostClientFlow (tzn. zawierają tylko zgodne zasady).

Jeśli ją dodasz, PostClientFlow to ostatni przepływ, który zostanie wykonany po wysłaniu odpowiedzi do klienta.

PostClientFlow przydaje się przy finalizowaniu logowania. Możesz też zapisać sygnatury czasowe rozpoczęcia i zakończenia działania odpowiedzi.

Oto przykład 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, by dowiedzieć się, jak utworzyć PostClientFlow przy użyciu zasad MessageLogging z serii 4-minutowych filmów dla programistów (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 w sekwencji (PreFlow, Flow, PostFlow – jak opisano w tym temacie) – zawartość przepływu jest wykonywana w sekwencji.

Poniższa przykładowa konfiguracja przepływu pracy odwołuje się do 3 zasad (skonfigurowanych w innym miejscu w ich własnych 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. Po nich następuje 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 wyświetla tę sekwencję zasad w postaci wiersza z ikonami, w których każda ikona reprezentuje zasadę.

Konsola Apigee Edge wyświetla tę sekwencję zasad w postaci wiersza z ikonami, w których każda ikona reprezentuje zasadę. Ikony widoczne na ścieżce żądania to: Zweryfikuj klucz interfejsu API, Usuń klucz interfejsu API i Limit.

Debugowanie procesów

Narzędzie Apigee Edge Trace zapewnia graficzne przedstawienie sposobu działania logiki na serwerze proxy interfejsu API po przesłaniu żądania. To narzędzie obrazuje proces przetwarzania żądania i odpowiedzi. Nie pokazuje wyraźnie, czym różni się PreFlow, przepływy warunkowe i PostFlow.

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

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

Błąd można zgłaszać z różnych miejsc na serwerze proxy interfejsu API, w tym z przepływów.

Poniższy przykład to stan odpowiedzi z PreFlow w docelowym punkcie końcowym, czyli 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 wartości docelowej nie jest równa 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 Obsługa błędów.