Korzystanie ze zmiennych przepływu

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

Zmienne przepływu to obiekty, do których można uzyskać dostęp z poziomu zasad lub narzędzi (takich jak narzędzie śledzenia). Pozwalają utrzymać stan powiązany z transakcją interfejsu API przetwarzaną przez Apigee Edge.

Czym są zmienne przepływu?

Zmienne przepływu występują w kontekście procesu serwera proxy interfejsu API i śledzą stan w transakcji API w taki sposób, w jaki zmienne nazwane śledzą stan w programie. Zmienne przepływu przechowują takie informacje jak:

  • Adres IP, nagłówki, ścieżka adresu URL i ładunek wysłane z aplikacji wysyłającej żądanie.
  • informacje o systemie, takie jak data i godzina odbioru żądania przez Edge;
  • Dane uzyskiwane w momencie wykonywania zasady. Na przykład po uruchomieniu zasady, która weryfikuje token OAuth, Edge tworzy zmienne przepływu przechowujące informacje takie jak nazwa aplikacji żądającej.
  • Informacje o odpowiedzi z systemu docelowego

Niektóre zmienne są wbudowane w Edge i są wypełniane automatycznie po otrzymaniu żądania do interfejsu API. Są dostępne w ramach transakcji realizowanych za pomocą interfejsu API. Możesz też tworzyć własne zmienne niestandardowe, korzystając z zasad takich jak zasada AssignMessage lub w kodzie JavaScript, Node.js i w Javie.

Jak widać, zmienne mają zakres, a to, gdzie są dostępne, zależy częściowo od tego, kiedy zostały utworzone w procesie serwera proxy interfejsu API. Ogólnie rzecz biorąc, po utworzeniu zmiennej jest ona dostępna dla wszystkich zasad i kodu uruchamianego później w procesie transakcji przez interfejs API.

Do czego służą zmienne przepływu?

Zmienna przepływu jest używana w zasadach i procesach warunkowych:

  • Zasady mogą pobierać stan ze zmiennych przepływu i używać ich do pracy.

    Na przykład zasada weryfikacji JWT może pobrać token do zweryfikowania ze zmiennej przepływu, a następnie przeprowadzić na nim weryfikację. Inny przykład: zasada JavaScriptu może pobierać zmienne przepływu i kodować zawarte w nich dane.

  • Przepływy warunkowe mogą odwoływać się do zmiennych przepływu, aby kierować przepływ interfejsu API przez Edge – podobnie jak instrukcja Switch w programowaniu.

    Na przykład zasada zwracająca błąd może być wykonywana tylko wtedy, gdy ustawiona jest konkretna zmienna przepływu. Na koniec możesz pobrać i ustawić zmienne przepływu w aplikacji docelowej Node.js.

Przyjrzyjmy się przykładom wykorzystania zmiennych w każdym z tych kontekstów.

Zmienne przepływu w zasadach

Niektóre zasady przyjmują jako dane wejściowe zmienne przepływu.

Na przykład ta zasada AssignMessage pobiera wartość zmiennej przepływu client.ip i umieszcza ją w nagłówku żądania o nazwie My-Client-IP. Jeśli zasada zostanie dodana do przepływu żądania, ustawia nagłówek, który jest przekazywany do celu backendu. Jeśli ustawisz go w procesie odpowiedzi, nagłówek będzie wysyłany z powrotem do aplikacji klienckiej.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

W innym przykładzie, gdy wykonywana jest zasada dotycząca limitów, kilka zmiennych przepływu zawiera wartości związane z zasadami. Jedna z tych zmiennych nosi nazwę ratelimit.my-quota-policy.used.count (gdzie my-quota-policy to nazwa interesującej Cię zasady dotyczącej limitów).

Możesz później wykonać proces warunkowy, który brzmi: „Jeśli bieżąca liczba limitów jest mniejsza niż 50%, a przedział czasu mieści się między 9:00 a 17:00, wyegzekwuj inny limit”. Ten warunek może zależeć od wartości bieżącej liczby limitów oraz od zmiennej przepływu o nazwie system.time, która jest jedną z wbudowanych zmiennych Edge.

Zmienne przepływu w przepływach warunkowych

Przepływy warunkowe oceniają zmienne przepływu i umożliwiają dynamiczne zachowanie serwerów proxy. Warunki są zwykle używane do zmiany działania przepływów, kroków i reguł trasy.

Oto proces warunkowy, który ocenia wartość zmiennej request.verb w kroku przepływu proxy. W tym przypadku, jeśli czasownik żądania to POST, jest wykonywana zasadaVerifyAPIKey. Jest to typowy wzorzec używany w konfiguracjach serwera proxy interfejsu API.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

Możesz się zastanawiać, skąd pochodzą zmienne takie jak request.verb, client.ip i system.time? Kiedy są tworzone instancje i wypełniane wartościami? Aby dowiedzieć się, kiedy zmienne są tworzone i kiedy są dla Ciebie dostępne, przeczytaj artykuł Omówienie zakresu zmiennej przepływu.

Zmienne przepływu w kodzie JavaScript wywoływane za pomocą zasady JavaScript

Dzięki zasadom JavaScript możesz uruchamiać kod JavaScript z poziomu procesu serwera proxy interfejsu API. JavaScript wykonywany przez tę zasadę korzysta z obiektowego modelu JavaScript Apigee, który zapewnia Twojemu niestandardowemu kodowi dostęp do obiektów żądań, odpowiedzi i kontekstu powiązanych z procesem serwera proxy interfejsu API, w którym uruchamiany jest Twój kod. Na przykład ten kod ustawia nagłówek odpowiedzi z wartością uzyskaną ze zmiennej przepływu target.name.

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

Ta technika korzystania z JavaScriptu do odczytu i ustawiania zmiennych jest podobna do przedstawionej powyżej zasady AssignMessage. To po prostu inny sposób na uzyskanie takiego samego efektu w Edge. Pamiętaj, że kod JavaScript wykonywany przez zasadę JavaScript ma dostęp do wszystkich istniejących i objętych zakresem zmiennych przepływu przez serwer proxy interfejsu API.

Zmienne przepływu w kodzie Node.js

Wymagając modułu apigee-access, możesz ustawiać zmienne przepływu i uzyskiwać do nich dostęp z poziomu kodu Node.js wdrożonego w Edge.

Oto prosty przykład, w którym zmienna o nazwie custom.foo jest ustawiona na wartość Bar. Po ustawieniu ta nowa zmienna staje się dostępna dla wszystkich zasad lub innego kodu występującego w procesie serwera proxy po wykonaniu kodu Node.js.

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

Więcej informacji o korzystaniu ze zmiennych apigee-access znajdziesz w artykule Uzyskiwanie dostępu do zmiennych przepływu w Node.js.

Omówienie zakresu zmiennej przepływu

Zakres zmiennej jest powiązany z przepływem lub ogólnym „cyklem życia” wywołania serwera proxy interfejsu API.

Wizualizacja przepływu serwera proxy interfejsu API

Aby zrozumieć zakres zmiennych przepływu, musisz zrozumieć lub zwizualizować sposób przepływu wiadomości przez serwer proxy interfejsu API. Serwer proxy interfejsu API składa się z serii etapów przetwarzania wiadomości zorganizowanych w przepływ. Na każdym etapie procesu proxy ocenia on dostępne informacje i decyduje, co zrobić dalej. Po drodze serwer proxy może wykonać kod zasady lub wykonać rozgałęzienie warunkowe.

Poniższy rysunek przedstawia tę sekwencję przepływów. Zwróć uwagę na to, że przepływy składają się z 4 głównych segmentów: żądanie punktu końcowego ProxyEnd, żądanie elementu TargetEndpoint, odpowiedź elementu TargetEndpoint i odpowiedź ProxyEndpoint.

Pamiętaj o tej strukturze procesu, gdy zaczniemy badać zmienne przepływu w pozostałej części tego tematu.

Jak zakres zmienny jest powiązany z procesem serwera proxy

Gdy tylko zwizualizujesz sposób przepływu wiadomości przez serwer proxy (tak jak to opisano wcześniej), możesz zacząć rozumieć zakres zmiennych. Zakres oznacza punkt w cyklu życia przepływu serwera proxy, w którym po raz pierwszy tworzysz instancję zmiennej.

Jeśli na przykład masz zasadę powiązaną z segmentem żądań ProxyEndpoint, ta zasada nie będzie miała dostępu do żadnych zmiennych ograniczonych do segmentu żądania TargetEndpoint. Powodem jest to, że segment żądania TargetEndpoint w procesie nie został jeszcze wykonany, więc serwer proxy interfejsu API nie miał jeszcze okazji wypełniania zmiennych w tym zakresie.

Poniższa tabela zawiera pełny zestaw zakresów zmiennych i wskazuje, kiedy w procesie serwera proxy stają się one dostępne.

Zakres zmienny Gdzie są wypełniane te zmienne
żądanie serwera proxy Segment żądania ProxyEndpoint
żądanie docelowe Segment żądania docelowego punktu końcowego
odpowiedź docelowa Segment odpowiedzi docelowego punktu końcowego
odpowiedź serwera proxy Segment odpowiedzi ProxyEndpoint
zawsze dostępny Gdy tylko serwer proxy otrzyma żądanie. Te zmienne są dostępne w całym cyklu życia przepływu proxy.

Na przykład dostępna jest wbudowana zmienna Edge o nazwie client.ip. Ta zmienna ma zakres „Żądanie proxy”. Jest ono automatycznie wypełniane adresem IP klienta, który wywołał serwer proxy. Jest ona wypełniana, gdy żądanie po raz pierwszy trafi do punktu końcowego serwera proxy i pozostaje dostępne w całym cyklu życia przepływu przez serwer proxy.

Inna wbudowana zmienna nosi nazwę target.url. Zakres tej zmiennej to „docelowe żądanie”. W segmencie żądania docelowego punktu końcowego jest ona zapełniana adresem URL żądania wysłanym do miejsca docelowego backendu. Jeśli spróbujesz uzyskać dostęp do target.url w segmencie żądania ProxyEndpoint, otrzymasz wartość NULL. Jeśli spróbujesz ustawić tę zmienną, zanim znajdzie się w zakresie, serwer proxy nic nie zrobi – nie wygeneruje błędu ani nie ustawi zmiennej.

Oto prosty przykład, który pokazuje, jak rozumieć zakres zmienny. Załóżmy, że chcesz skopiować całą zawartość obiektu żądania (nagłówki, parametry, treść) i przypisać go do ładunku odpowiedzi, aby wysłać go z powrotem do aplikacji wywołującej. W tym zadaniu możesz użyć zasady AssignMessage. Kod zasady wygląda tak:

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

Ta zasada po prostu kopiuje obiekt request i przypisuje go do obiektu response. Gdzie należy umieścić tę zasadę w procesie serwera proxy? Odpowiedź brzmi, że musi on zostać umieszczony w odpowiedzi z TargetEndpoint, bo zakres zmiennej odpowiedzi to „target response”.

Odwoływanie się do zmiennych przepływu

Wszystkie zmienne wbudowane w Apigee Edge są zgodne z konwencją nazewnictwa w notatkach z kropkami. Taka konwencja ułatwia określenie przeznaczenia zmiennej. Na przykład system.time.hour i request.content.

Apigee rezerwuje różne prefiksy, aby odpowiednio uporządkować odpowiednie zmienne. Są to między innymi:

  • request
  • response
  • system
  • target

Aby odwołać się do zmiennej w zasadzie, umieść ją w nawiasach klamrowych. Na przykład poniższa zasada AssignMessage pobiera wartość zmiennej client.ip i umieszcza ją w nagłówku żądania o nazwie Client-IP.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

W przypadku przepływów warunkowych nawiasy klamrowe nie są konieczne. Ten przykładowy warunek ocenia zmienną request.header.accept:

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

Możesz się też odwoływać do zmiennych przepływu w kodzie JavaScript i Javy. Aby dowiedzieć się więcej, zobacz:

Typ danych zmiennych przepływu

Każda właściwość zmiennej przepływu ma jasno zdefiniowany typ danych, np. Ciąg znaków, Długi, Liczba całkowita, Wartość logiczna lub Kolekcja. Typy danych znajdziesz w dokumentacji zmiennych przepływu. W przypadku zmiennych utworzonych przez zasadę zapoznaj się z informacjami o konkretnych typach danych w odpowiednim temacie dotyczącym zasad.

Zmienne tworzone ręcznie zakładają typ podany podczas tworzenia i zależą od typów dozwolonych wartości. Na przykład zmienne utworzone w kodzie Node.js mogą być tylko liczbami, ciągiem znaków, wartością logiczną, wartością null lub niezdefiniowaną.

Używanie zmiennych przepływu w zasadach

Wiele zasad w ramach normalnego wykonywania tworzy zmienne przepływu. W dokumencie Informacje o zasadach znajdziesz informacje o wszystkich zmiennych związanych z zasadami.

Podczas pracy z serwerami proxy i zasadami zapoznaj się z informacjami o zasadach, aby dowiedzieć się, które zmienne są tworzone i do czego służą. Na przykład zasada dotycząca limitów tworzy zestaw zmiennych zawierających informacje o liczbie i limitach, czasie ich wygaśnięcia itd.

Niektóre zmienne zasad są przydatne podczas debugowania. Możesz na przykład użyć narzędzia do śledzenia, by sprawdzić, które zmienne zostały ustawione w konkretnej instancji w procesie serwera proxy.

Zasada ExtractVariables umożliwia wypełnianie zmiennych niestandardowych danymi wyodrębnionymi z wiadomości. Możesz wyodrębnić parametry zapytania, nagłówki i inne dane. Możesz na przykład przeanalizować wiadomości z żądaniami i odpowiedziami za pomocą wzorców, aby wyodrębnić z nich określone dane.

W poniższym przykładzie funkcja Wyodrębnianie zmiennych analizuje wiadomość z odpowiedzią i przechowuje określone dane zebrane z tej odpowiedzi. Zasada tworzy 2 zmienne niestandardowe (geocoderesponse.latitude i geocoderesponse.longitude), a następnie przypisuje do nich wartości.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Przypominamy, że wiele zasad automatycznie tworzy zmienne. Dostęp do tych zmiennych możesz uzyskać w kontekście procesu serwera proxy. Są one udokumentowane w dokumencie „Zasady dotyczące zasad” w ramach poszczególnych tematów zasad.

Praca ze zmiennymi przepływu w kodzie JavaScript

Możesz uzyskiwać dostęp do zmiennych i ustawiać je bezpośrednio w kodzie JavaScript, który jest uruchamiany w kontekście serwera proxy interfejsu API. Za pomocą obiektowego modelu JavaScript Apigee usługa JavaScript wykonywana na Edge ma bezpośredni dostęp do zmiennych przepływu serwera proxy.

Aby uzyskać dostęp do zmiennych w kodzie JavaScript, wywołaj metody getter/setter w dowolnym z tych obiektów:

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

Jak widać, odwołania do obiektów mapują się na znane segmenty modelu przepływu proxy, co zostało opisane w sekcji Wizualizacja przepływu serwera proxy interfejsu API.

Obiekt context odpowiada „globalnym” dostępnym zmiennym, takim jak zmienne systemowe. Możesz na przykład wywołać getVariable() w obiekcie context, aby uzyskać bieżący rok:

var year = context.getVariable('system.time.year');

Możesz też wywołać setVariable(), aby ustawić wartość zmiennej niestandardowej lub dowolnych zmiennych możliwych do zapisu. Tworzymy tutaj zmienną niestandardową o nazwie organization.name.myorg i przypisujemy do niej wartość.

var org = context.setVariable('organization.name.myorg', value);

Ponieważ ta zmienna została utworzona za pomocą obiektu context, będzie dostępna dla wszystkich segmentów przepływu (w zasadzie działa to jak tworzenie zmiennej globalnej).

Zmienne przepływu proxy możesz też pobierać w kodzie Java, które uruchamiasz za pomocą zasady JavaCallout.

Uzyskiwanie dostępu do zmiennych przepływu w aplikacjach Node.js

Możesz pobierać, ustawiać i usuwać zmienne przepływu z kodu Node.js wdrożonego w Edge. Musisz tylko „wymagać” modułu dostępu apigee w kodzie. Więcej informacji znajdziesz w artykule na temat uzyskiwania dostępu do zmiennych przepływu w środowisku Node.js.

O czym musisz pamiętać

Oto kilka ważnych kwestii dotyczących zmiennych przepływu, o których należy pamiętać:

  • Niektóre gotowe zmienne są tworzone automatycznie i wypełniane automatycznie przez serwer proxy. Ich opis znajdziesz w dokumentacji zmiennych przepływu.
  • Możesz tworzyć zmienne niestandardowe dostępne do użycia w procesie proxy. Można tworzyć zmienne przy użyciu zasad takich jak zasada AssignMessage i zasada JavaScript oraz w kodzie Node.js.
  • Zmienne mają zakres. Na przykład niektóre zmienne są wypełniane automatycznie, gdy pierwszy serwer proxy otrzyma żądanie z aplikacji. Inne zmienne są wypełniane w segmencie przepływu odpowiedzi serwera proxy. Te zmienne odpowiedzi pozostają niezdefiniowane, dopóki segment odpowiedzi nie zostanie wykonany.
  • Po uruchomieniu zasad mogą tworzyć i wypełniać zmienne związane z daną zasadą. Wszystkie te zmienne związane z zasadami znajdziesz w dokumentacji poszczególnych zasad.
  • W ramach przepływu warunkowego zwykle oceniana jest co najmniej 1 zmienna. Jeśli chcesz tworzyć przepływy warunkowe, musisz znać zmienne.
  • Wiele zasad używa zmiennych jako danych wejściowych lub wyjściowych. Być może zmienna tworzona przez jedną zasadę jest później używana przez inną.
  • Wiele zmiennych przepływu możesz pobierać i ustawiać w Node.js za pomocą prostego JavaScriptu (i naszego obiektowego modelu JavaScript) lub zasady JavaCallout, która wykonuje kod w Edge.

Przykłady powiązanego kodu

Przykładowe serwery proxy interfejsów API są dostępne na GitHubie. Można je łatwo pobrać i z nich korzystać. Informacje o pobieraniu i używaniu przykładów znajdziesz w artykule Korzystanie z przykładowych serwerów proxy interfejsu API. W sekcji Lista przykładów znajdziesz opis przykładowych usług proxy interfejsu API i ich działania.

Przykładowe serwery proxy, które wykorzystują zmienne i przetwarzanie zmiennych, to:

  • zmienne – demonstruje, jak wyodrębniać i ustawiać zmienne na podstawie treści wiadomości w formacie transportu oraz danych JSON i XML.
  • policy-mashup-cookbook – pełna aplikacja, która używa kompozycji zasad do wywoływania 2 publicznych interfejsów API, łącząc wyniki i generując wzbogacone odpowiedzi dla aplikacji klienckiej. Więcej informacji o tym przykładzie znajdziesz w sekcji Korzystanie z kompozycji zasad.
  • zasady-warunkowe – implementuje proste egzekwowanie zasad warunkowych na podstawie wartości zmiennych.

Powiązane artykuły

  • Wszystkie zmienne, które są automatycznie wypełniane w serwerze proxy interfejsu API, znajdziesz w dokumentacji zmiennych przepływu. Dokumentacja zawiera też informacje o typie i zakresie każdej zmiennej.
  • Aby dowiedzieć się, jakie zmienne wypełnia dana zasada, zapoznaj się z odpowiednim tematem. Na przykład przeczytaj sekcję o zmiennych przepływu w dokumentacji zasad limitów.