Korzystanie ze zmiennych przepływu

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Zmienne przepływu to obiekty, do których możesz uzyskać dostęp z poziomu zasad lub narzędzi (np. narzędzia Trace). Umożliwiają one utrzymywanie stanu powiązanego z transakcją API przetwarzaną przez Apigee Edge.

Czym są zmienne przepływu?

Zmienne przepływu istnieją w kontekście przepływu proxy interfejsu API i śledzą stan transakcji API w taki sam sposób, jak nazwane zmienne śledzą stan w programie. Zmienne przepływu przechowują takie informacje jak:

  • adres IP, nagłówki, ścieżka adresu URL i ładunek wysłany z aplikacji wysyłającej żądanie;
  • informacje o systemie, takie jak data i godzina otrzymania żądania przez Edge;
  • dane pochodne, które są generowane podczas wykonywania zasady. Na przykład po wykonaniu zasady, która weryfikuje token OAuth, Edge tworzy zmienne przepływu zawierające informacje takie jak nazwa aplikacji wysyłającej żądanie.
  • informacje o odpowiedzi z systemu docelowego.

Niektóre zmienne są "wbudowane" w Edge i są automatycznie wypełniane za każdym razem, gdy zostanie odebrane żądanie do interfejsu API. Są one dostępne w całej transakcji API. Możesz też tworzyć własne zmienne niestandardowe za pomocą zasad, takich jak zasada AssignMessage, lub w kodzie JavaScript, Node.js i Java.

Jak zobaczysz, zmienne mają zakres, a ich dostępność zależy częściowo od tego, kiedy zostały utworzone w przepływie proxy interfejsu API. Ogólnie rzecz biorąc, gdy zmienna zostanie utworzona, jest dostępna dla wszystkich zasad i kodu, które są wykonywane później w przepływie transakcji API.

Jak używać zmiennych przepływu?

Zmienne przepływu są używane w zasadach i przepływach warunkowych:

  • Zasady mogą pobierać stan ze zmiennych przepływu i używać ich do wykonywania swoich zadań.

    Na przykład zasada VerifyJWT może pobrać token do zweryfikowania ze zmiennej przepływu, a następnie przeprowadzić jego weryfikację. Innym przykładem jest to, że a zasada JavaScript może pobierać zmienne przepływu i kodować dane zawarte w tych zmiennych.

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

    Na przykład zasada zwracania błędu może być wykonywana tylko wtedy, gdy ustawiona jest określona zmienna przepływu. Na koniec możesz pobierać i ustawiać zmienne przepływu w aplikacji docelowej Node.js.

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

Zmienne przepływu w zasadach

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

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 ta zasada zostanie dodana do przepływu żądania , ustawi nagłówek , który zostanie przekazany do docelowego backendu. Jeśli zasada zostanie ustawiona w przepływie odpowiedzi, nagłówek zostanie odesłany 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>

Innym przykładem jest to, że gdy wykonywana jest zasada Quota, kilka zmiennych przepływu jest wypełnianych wartościami związanymi z zasadą. Jedna z tych zmiennych is called ratelimit.my-quota-policy.used.count (where my-quota-policy is the name of the quota policy you're interested in).

Możesz później wykonać przepływ warunkowy który mówi: „Jeśli bieżąca liczba limitów jest mniejsza niż 50% maksymalnej wartości i jest między 9:00 a 17:00, zastosuj inny limit”. Ten warunek może zależeć od wartości bieżącej liczby limitów i 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 działanie serwerów proxy. Warunki są zwykle używane do zmiany zachowania przepływów, kroków i reguł tras.

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

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

Możesz się teraz zastanawiać, skąd pochodzą zmienne takie jak request.verb, client.ip, i system.time. Kiedy są tworzone i wypełniane wartością? Aby dowiedzieć się, kiedy zmienne są tworzone i kiedy są dostępne, przeczytaj artykuł Określanie zakresu zmiennej przepływu.

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

Za pomocą zasady JavaScript możesz wykonywać kod JavaScript w kontekście przepływu proxy interfejsu API. Kod JavaScript wykonywany przez tę zasadę używa modelu obiektów JavaScript Apigee , który zapewnia Twojemu kodowi niestandardowemu dostęp do obiektów żądania, odpowiedzi i kontekstu powiązanych z przepływem proxy interfejsu API, w którym jest wykonywany 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 używania JavaScriptu do odczytywania i ustawiania zmiennych jest podobna do pracy, którą można wykonać za pomocą zasady AssignMessage (opisanej wcześniej). Jest to po prostu inny sposób na wykonywanie tych samych czynności w Edge. Pamiętaj, że kod JavaScript wykonywany przez zasadę JavaScript ma dostęp do wszystkich zmiennych przepływu, które istnieją i znajdują się w zakresie przepływu 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 który występuje w przepływie 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 używaniu apigee-access do pracy ze zmiennymi znajdziesz w artykule Dostęp do zmiennych przepływu w Node.js.

Określanie zakresu zmiennej przepływu

Zakreszmiennej jest powiązany z przepływem lub ogólnym "cyklem życia" wywołania proxy interfejsu API.

Wizualizacja przepływu proxy interfejsu API

Aby zrozumieć zakres zmiennej przepływu, ważne jest, aby zrozumieć lub zwizualizować sposób przepływu wiadomości przez proxy interfejsu API. Proxy interfejsu API składa się z serii kroków przetwarzania wiadomości zorganizowanych jako przepływ. Na każdym etapie przepływu serwera proxy serwer proxy ocenia dostępne informacje i decyduje co zrobić dalej. W trakcie tego procesu serwer proxy może wykonywać kod zasady lub wykonywać rozgałęzianie warunkowe.

Na ilustracji poniżej przedstawiono tę sekwencję przepływów. Zwróć uwagę, że przepływy składają się z 4 głównych segmentów: ProxyEndpoint request, TargetEndpoint request, TargetEndpoint response i ProxyEndpoint response.

Pamiętaj o tej strukturze przepływu, gdy będziemy omawiać zmienne przepływu w dalszej części tego artykułu.

Jak zakres zmiennej jest powiązany z przepływem serwera proxy

Gdy tylko będziesz w stanie zwizualizować przepływ wiadomości przez serwer proxy, jak opisano wcześniej, możesz zacząć rozumieć zakres zmiennej. Zakres oznacza punkt w cyklu życia przepływu serwera proxy w którym zmienna jest po raz pierwszy tworzona.

Jeśli na przykład masz zasadę dołączoną do segmentu żądania ProxyEndpoint, ta zasada nie będzie mogła uzyskać dostępu do żadnych zmiennych, które są w zakresie segmentu żądania TargetEndpoint. Dzieje się tak, ponieważ segment żądania TargetEndpoint przepływu nie został jeszcze wykonany, więc proxy interfejsu API nie miał możliwości wypełnienia zmiennych w tym zakresie.

W tabeli poniżej znajdziesz pełny zestaw zakresów zmiennych oraz informacje o tym, kiedy stają się one dostępne w przepływie serwera proxy.

Zakres zmiennej Gdzie te zmienne są wypełniane
żądanie serwera proxy Segment żądania ProxyEndpoint
żądanie docelowe Segment żądania TargetEndpoint
odpowiedź docelowa Segment odpowiedzi TargetEndpoint
odpowiedź serwera proxy Segment odpowiedzi ProxyEndpoint
zawsze dostępna Gdy tylko serwer proxy otrzyma żądanie. Te zmienne są dostępne przez cały cykl życia przepływu serwera proxy.

Na przykład w Edge jest wbudowana zmienna o nazwie client.ip. Ta zmienna ma zakres „żądanie serwera proxy”. Jest ona automatycznie wypełniana adresem IP klienta, który wywołał serwer proxy. Jest ona wypełniana, gdy żądanie po raz pierwszy dociera do ProxyEndpoint, i pozostaje dostępna przez cały cykl życia przepływu serwera proxy.

Jest też inna wbudowana zmienna o nazwie target.url. Zakres tej zmiennej to „żądanie docelowe”. Jest ona wypełniana w segmencie żądania TargetEndpoint adresem URL żądania wysłanego do 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 nie wykona żadnej czynności – nie wygeneruje błędu ani nie ustawi zmiennej.

Oto prosty przykład, który pokazuje, jak myśleć o zakresie zmiennej. Załóżmy, że chcesz skopiować całą zawartość obiektu żądania (nagłówki, parametry, treść) i przypisać ją do ładunku odpowiedzi, który ma zostać odesłany do aplikacji wywołującej. Do tego zadania 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. Ale gdzie należy umieścić tę zasadę w przepływie serwera proxy? Odpowiedź brzmi: musi ona zostać umieszczona w odpowiedzi TargetEndpoint, ponieważ zakres zmiennej odpowiedzi to "odpowiedź docelowa".

Odwoływanie się do zmiennych przepływu

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

Apigee zastrzega różne prefiksy, aby odpowiednio organizować odpowiednie zmienne. Te prefiksy to:

  • request
  • response
  • system
  • target

Aby odwołać się do zmiennej w zasadzie, umieść ją w nawiasach klamrowych. Na przykład ta 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 przepływach warunkowych nawiasy klamrowe nie są konieczne. Ten przykład warunku ocenia zmienną request.header.accept:

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

Możesz też odwoływać się do zmiennych przepływu w kodzie JavaScript i Java. Więcej informacji znajdziesz w tych artykułach:

Typ danych zmiennych przepływu

Każda właściwość zmiennej przepływu ma dobrze zdefiniowany typ danych, taki jak String, Long, Integer, Boolean lub Collection. Typy danych znajdziesz w dokumentacji zmiennych przepływu. W przypadku zmiennych utworzonych przez zasadę, informacje o typie danych znajdziesz w odpowiednim artykule dotyczącym zasady.

Zmienne utworzone ręcznie przyjmują typ podany podczas ich tworzenia i zależą od typów wartości, które są dozwolone. Na przykład zmienne utworzone w kodzie Node.js są ograniczone do typów Number, String, Boolean, null lub undefined.

Używanie zmiennych przepływu w zasadach

Wiele zasad tworzy zmienne przepływu w ramach normalnego wykonywania. Dokumentacja zasad zawiera informacje o wszystkich tych zmiennych specyficznych dla zasad.

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

Niektóre zmienne zasad są przydatne do debugowania. Możesz na przykład użyć narzędzia Trace tool, aby sprawdzić, które zmienne zostały ustawione w określonym momencie przepływu serwera proxy.

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

W tym przykładzie zasada Extract Variables analizuje wiadomość z odpowiedzią i przechowuje określone dane z odpowiedzi. Zasada tworzy 2 zmienne niestandardowe, geocoderesponse.latitude i geocoderesponse.longitude, i przypisuje im 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>

Pamiętaj, że wiele zasad automatycznie tworzy zmienne. Możesz uzyskać dostęp do tych zmiennych w kontekście przepływu serwera proxy. Są one opisane w dokumentacji zasad w sekcji dotyczącej poszczególnych zasad.

Praca ze zmiennymi przepływu w kodzie JavaScript

Możesz uzyskiwać dostęp do zmiennych i ustawiać je bezpośrednio w kodzie JavaScript wykonywanym w kontekście proxy interfejsu API. Dzięki modelowi obiektów JavaScript Apigee kod JavaScript wykonywany w 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 widzisz, te odwołania do obiektów odpowiadają znanym segmentom modelu przepływu proxy interfejsu API jak wyjaśniono wcześniej w Wizualizacja przepływu proxy interfejsu API.

Obiekt context odpowiada zmiennym dostępnym "globalnie", 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');

Podobnie możesz wywołać setVariable(), aby ustawić wartość zmiennej niestandardowej lub dla dowolnej zapisywalnej zmiennej gotowej do użycia. W tym przypadku tworzymy zmienną niestandardową o nazwie organization.name.myorg i przypisujemy jej wartość.

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

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

Możesz też pobierać i ustawiać zmienne przepływu serwera proxy w kodzie Java wykonywanym za pomocą zasady JavaCallout.

Dostęp 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. Wystarczy, że w kodzie „wymagasz” modułu apigee-access. Szczegółowe informacje znajdziesz w artykule Dostęp do zmiennych przepływu w Node.js.

O czym musisz pamiętać

Oto kilka ważnych informacji, o których należy pamiętać w przypadku zmiennych przepływu:

  • Niektóre zmienne „gotowe do użycia” są tworzone i wypełniane automatycznie przez sam serwer proxy siebie. Są one opisane w dokumentacji zmiennych przepływu.
  • Możesz tworzyć zmienne niestandardowe, które są dostępne do użycia w przepływie serwera proxy. Zmienne można tworzyć za pomocą zasad, takich jak zasada AssignMessage i zasada JavaScript, oraz w kodzie Node.js.
  • Zmienne mają zakres. Na przykład niektóre zmienne są automatycznie wypełniane, 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 do momentu wykonania segmentu odpowiedzi wykonuje.
  • Gdy zasady są wykonywane, mogą tworzyć i wypełniać zmienne specyficzne dla zasad. Dokumentacja każdej zasady zawiera listę wszystkich odpowiednich zmiennych specyficznych dla zasad.
  • Przepływy warunkowe zwykle oceniają co najmniej 1 zmienną. Jeśli chcesz tworzyć przepływy warunkowe, musisz rozumieć zmienne.
  • Wiele zasad używa zmiennych jako danych wejściowych lub wyjściowych. Być może zmienna utworzona przez jedną zasadę jest później używana przez inną.
  • Wiele zmiennych przepływu możesz pobierać i ustawiać z poziomu Node.js za pomocą zwykłego JavaScriptu (i naszego modelu obiektów JavaScript) lub zasady JavaCallout, która wykonuje kod w Edge.

Powiązane przykłady kodu

Przykłady proxy interfejsu API są dostępne na GitHubie. Można je łatwo pobrać i używać. Informacje o pobieraniu i używaniu przykładów znajdziesz w artykule Korzystanie z przykładowych serwerów proxy API. Opis przykładów serwerów proxy API i ich działania znajdziesz na liście przykładów.

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

  • variables – pokazuje, jak wyodrębniać i ustawiać zmienne na podstawie transportu oraz treści wiadomości JSON i XML.
  • policy-mashup-cookbook – kompletna aplikacja, która używa kompozycji zasad do wywoływania 2 publicznych interfejsów API, łączy wyniki i generuje wzbogaconą odpowiedź dla aplikacji klienckiej. Więcej informacji o tym przykładzie znajdziesz w artykule Korzystanie z kompozycji zasad.
  • conditional-policy – implementuje proste egzekwowanie zasad warunkowych na podstawie wartości zmiennych.

Powiązane artykuły

  • Wszystkie zmienne, które są automatycznie wypełniane w proxy interfejsu API, są wymienione w dokumentacji zmiennych przepływu. Dokumentacja zawiera też typ i zakres każdej zmiennej.
  • Jeśli chcesz się dowiedzieć, które zmienne są wypełniane przez konkretną zasadę, zapoznaj się z dokumentacją tej zasady. Na przykład przeczytaj artykuł Zmienne przepływu w dokumentacji zasady Quota.