Korzystanie ze zmiennych przepływu

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

Zmienna przepływu to obiekt, do którego możesz uzyskać dostęp w ramach zasad lub narzędzi (np. narzędzia śledzenia). Umożliwiają one utrzymanie stanu powiązanego z transakcją interfejsu API przetwarzaną przez Apigee Edge.

Co to są zmienne przepływu?

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

  • adres IP, nagłówki, ścieżka URL i dane przesłane z aplikacji przesyłającej żądanie;
  • Informacje systemowe, na przykład data i godzina otrzymania żądania przez Edge
  • Dane uzyskane podczas wykonywania zasady. Na przykład po wykonaniu zasady, która weryfikuje token OAuth, Edge tworzy zmienne przepływu z informacjami takimi jak nazwa aplikacji żądającej.
  • informacje o odpowiedzi z systemu docelowego.

Niektóre zmienne są „wbudowane” w Edge i automatycznie wypełniane po otrzymaniu żądania interfejsu API. Są one dostępne w ramach transakcji API. Możesz też tworzyć własne zmienne niestandardowe za pomocą zasad takich jak Reguła przypisywania wiadomości lub w kodzie JavaScript, Node.js i Java.

Jak widać, zmienne mają zakres, a miejsce ich dostępności zależy częściowo od czasu ich utworzenia w procesie serwera proxy interfejsu API. Ogólnie po utworzeniu zmienna jest dostępna dla wszystkich zasad i kodu, które są wykonywane później w ramach przepływu transakcji w interfejsie API.

Jak są używane zmienne przepływu?

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

  • Zasady mogą pobierać stan z przepływu zmiennych i wykorzystywać go do działania.

    Na przykład zasada VerifyJWT może pobierać token do weryfikacji z zmiennej przepływu, a następnie przeprowadzać weryfikację. Innym przykładem jest polityka JavaScriptu, która 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ływ interfejsu API przez Edge, podobnie jak instrukcja switch w programowaniu.

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

Spójrzmy na przykłady użycia zmiennych w każdym z tych kontekstów.

Zmienne przepływu w zasadach

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

Na przykład zasada AssignMessage pobiera wartość zmiennej przepływu client.ip i umieszcza ją w nagłówku żądania o nazwie My-Client-IP. Jeśli zostanie dodana do przepływu żądania, ta zasada ustawia nagłówek, który jest przekazywany do celu w backendzie. Jeśli nagłówek jest ustawiony w obrębie ścieżki odpowiedzi, jest on wysyłany z powrotem do aplikacji klienta.

<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 po wykonaniu zasady limitów kilka zmiennych przepływu zostaje uzupełnionych wartościami związanymi z tą zasadą. Jedna z tych zmiennych nazywa się 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ć przepływ warunkowy, który mówi: „Jeśli bieżąca liczba limitów jest niższa niż 50% maksymalnej wartości, a godzina jest między 9:00 a 17:00, zastosuj inny limit”. To kryterium może zależeć od wartości bieżącej liczby limitów oraz 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ł trasy.

Oto przepływ danych warunkowy, który ocenia wartość zmiennej request.verb w kroku przepływu danych zastępczego. W takim przypadku, gdy czasownik żądania to POST, jest wykonywana zasadaVerifyAPIKey. To typowy wzorzec używany w konfiguracjach serwera proxy interfejsów API.

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

Zastanawiasz się pewnie, skąd pochodzą zmienne takie jak request.verb, client.ip i system.time. Kiedy są tworzone i wypełniane wartością? Jeśli chcesz się dowiedzieć, kiedy zmienne są tworzone i dostępne dla Ciebie, przeczytaj artykuł Omówienie zakresu zmiennej przepływu.

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

Dzięki polityce JavaScript możesz wykonywać kod JavaScript w kontekście przepływu danych przez serwer proxy API. Kod JavaScriptu wykonywany przez tę zasadę korzysta z modelu obiektów JavaScriptu Apigee, który zapewnia dostęp do obiektów żądania, odpowiedzi i kontekstu powiązanych z przepływem danych przez serwer WWW w interfejsie API, w którym jest wykonywany 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 metoda używania JavaScriptu do odczytywania i ustawiania zmiennych jest podobna do tej, którą możesz stosować w przypadku polityki przypisywania wiadomości (przedstawionej wcześniej). To tylko inny sposób osiągania tych samych celów w programie 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 dostępować do nich w kodzie Node.js wdrożonym w Edge.

Oto prosty przykład, w którym zmienna o nazwie custom.foo ma wartość Bar. Po ustawieniu ta nowa zmienna staje się dostępna dla wszystkich zasad i 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 funkcji apigee-access do pracy ze zmiennymi znajdziesz w artykule Dostęp do zmiennych przepływu w Node.js.

Omówienie zakresu zmiennych procesu

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

Wizualizacja przepływu danych w proxy interfejsu API

Aby zrozumieć zakres zmiennej przepływu, musisz wiedzieć, jak wiadomości przepływają przez serwer proxy interfejsu API. Pośrednik interfejsu API składa się z sekwencji kroków przetwarzania wiadomości, które są zorganizowane w ramach przepływu. Na każdym etapie przepływu danych przez serwer proxy serwer ten analizuje dostępne informacje i podejmuje decyzję, co zrobić dalej. W trakcie przetwarzania serwer proxy może wykonać kod zasad lub przeprowadzić odgałęzienie warunkowe.

Na rysunku poniżej pokazano tę sekwencję przepływów. Zwróć uwagę, że przepływy składają się z 4 głównych segmentów: żądanie ProxyEndpoint, żądanie punktu docelowego punktu końcowego, odpowiedź i odpowiedź w punkcie końcowym TargetEndpoint.

Pamiętaj o tej strukturze przepływu danych, gdy zaczniemy omawiać zmienne przepływu danych w dalszej części tego tematu.

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 w sposób opisany powyżej, możesz zacząć rozumieć zakres zmiennych. Przez zakres rozumiemy punkt w cyklu życia przepływu danych w usłudze proxy, w którym zmienna jest po raz pierwszy tworzona.

Jeśli na przykład masz zasadę powiązaną z segmentem żądań ProxyEndpoint, zasada ta nie będzie mieć dostępu do żadnych zmiennych ograniczonych do segmentu żądań TargetEndpoint. Dzieje się tak, ponieważ segment żądania TargetEndpoint w ramach przepływu nie został jeszcze wykonany, więc serwer proxy interfejsu API nie miał możliwości wypełnić zmiennych w tym zakresie.

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

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

Na przykład istnieje wbudowana zmienna Edge o nazwie client.ip. Ta zmienna ma zakres „żądanie serwera proxy”. Jest on automatycznie wypełniany adresem IP klienta, który wywołał serwer proxy. Jest zapełniane, gdy żądanie po raz pierwszy trafia do punktu końcowego serwera proxy i pozostaje dostępne przez cały cykl życia przepływu serwera proxy.

Istnieje też inna wbudowana zmienna o nazwie target.url. Zakres tej zmiennej to „target request”. Jest wypełniana w segmencie żądania punktu docelowego punktu końcowego adresem URL żądania wysłanym do celu 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ę ona w zakresie, serwer proxy nie zrobi nic – nie wygeneruje błędu ani nie ustawi zmiennej.

Oto prosty przykład, który pokazuje, jak rozpatrywać zasięg zmiennej. Załóżmy, że chcesz skopiować całą zawartość obiektu żądania (nagłówki, parametry, treść) i przypisać go do ładunku odpowiedzi, który ma zostać odesłany do aplikacji wywołującej. W tym zadaniu możesz użyć zasady przypisaniaMessage. Kod zasad 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 w procesie proxy należy umieścić tę zasadę? Odpowiedź brzmi, że musi on być umieszczony w odpowiedzi na żądanie 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 użyciem kropki. Ta konwencja ułatwia określenie celu zmiennej. Na przykład:system.time.hour i request.content.

Apigee rezerwuje różne prefiksy, aby odpowiednio organizować odpowiednie zmienne. Do tych prefiksów należą:

  • 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 okrągłe nie są wymagane. Ten przykładowy warunek 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. Aby dowiedzieć się więcej, zobacz:

Typ danych zmiennych przepływu

Każda właściwość zmiennej przepływu ma dobrze zdefiniowany typ danych, np. ciąg znaków, liczbę całkowitą, liczbę binarną, wartość logiczną lub kolekcję. Typy danych znajdziesz w dokumentacji dotyczącej zmiennych przepływu. W przypadku zmiennych utworzonych przez zasadę zapoznaj się z informacjami o typach danych w odpowiednim temacie pomocy dotyczącym zasad.

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

Korzystanie ze zmiennych przepływu w zasadach

Wiele zasad tworzy zmienne przepływu w ramach normalnego wykonania. W Informacjach o zasadach znajdziesz informacje o wszystkich zmiennych związanych z tymi zasadami.

Podczas pracy z serwerami proxy i zasadami zapoznaj się z informacjami na temat zasad, aby dowiedzieć się, które zmienne są tworzone i do czego służą. Na przykład zasada limitów tworzy zbiór zmiennych z informacjami o liczbie limitów, czasie ich wygaśnięcia itp.

Niektóre zmienne zasad są przydatne podczas debugowania. Aby sprawdzić, które zmienne zostały ustawione w konkretnym przypadku w przepływie danych przez serwer proxy, możesz użyć na przykład narzędzia do śledzenia.

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 analizować wiadomości z zapytaniami i odpowiedziami, używając wzorów do wyodrębniania określonych danych z tych wiadomości.

W tym przykładzie funkcja Extract Variables analizuje wiadomość z odpowiedzią i przechowuje określone dane pochodzące z tej odpowiedzi. Zasada tworzy 2 zmiennych niestandardowych, geocoderesponse.latitude i geocoderesponse.longitude, oraz 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 danych w usłudze proxy. Są one opisane w nawiązaniu do poszczególnych tematów zasad w naszej dokumentacji zasad.

Praca ze zmiennymi przepływu w kodzie JavaScript

Zmiennych możesz używać i je konfigurować bezpośrednio w kodzie JavaScript, który jest wykonywany w kontekście serwera proxy interfejsu API. Dzięki modelowi obiektów JavaScript Apigee wykonywanie kodu JavaScript 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 na dowolnym z tych obiektów:

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

Jak widać, odwołania do obiektów są mapowane na znane segmenty modelu przepływu serwera proxy, jak opisano to wcześniej w sekcji Wizualizacja przepływu serwera proxy interfejsu API.

Obiekt context odpowiada „globalnie” dostępnym zmiennym, takim jak zmienne systemowe. Aby uzyskać bieżący rok, możesz na przykład wywołać funkcję getVariable() obiektu context:

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

Podobnie możesz wywołać funkcję setVariable(), aby ustawić wartość zmiennej niestandardowej lub dowolnej zmiennej domyślnej, którą można modyfikować. Tutaj tworzymy zmienną niestandardową o nazwieorganization.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 ona dostępna dla wszystkich segmentów przepływu (w ten sposób przypomina tworzenie zmiennej globalnej).

Zmienne przepływu proxy możesz też pobierać i ustawiać w kodzie Java, który wykonujesz za pomocą specyfikacji 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” użycia modułu apigee-access. Więcej informacji znajdziesz w artykule Uzyskiwanie dostępu do zmiennych przepływu w Node.js.

O czym musisz pamiętać

Oto kilka ważnych kwestii związanych ze zmiennymi przepływu:

  • Niektóre gotowe zmienne są instancjonowane i wypełniane automatycznie przez samą usługę proxy. Dokumentację tę znajdziesz w dokumentacji zmiennych przepływu.
  • Możesz utworzyć zmienne niestandardowe, które będą dostępne do użycia w przepływie danych w usłudze proxy. Zmienne można tworzyć za pomocą zasad takich jak Reguła przypisywania wiadomości i Reguła 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 sekcji przepływu odpowiedzi serwera proxy. Te zmienne odpowiedzi pozostają nieokreślone, dopóki nie zostanie wykonany segment odpowiedzi.
  • Podczas wykonywania zasad mogą one tworzyć i wypełniać zmienne związane z poszczególnymi zasadami. Dokumentacja dotycząca każdej zasady zawiera listę wszystkich odpowiednich zmiennych dotyczących danej zasady.
  • Przepływy warunkowe zwykle oceniają co najmniej 1 zmienną. Aby utworzyć przepływy warunkowe, musisz znać 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ć w Node.js, używając zwykłego kodu JavaScriptu (i naszego modelu obiektów JavaScriptu) lub polityki JavaCallout, która wykonuje kod w Edge.

Powiązane przykładowe fragmenty kodu

Przykłady proxy API są dostępne na GitHubie i są łatwe do pobrania i zastosowania. Informacje o pobieraniu i korzystaniu z przykładów znajdziesz w sekcji Korzystanie z przykładowych serwerów proxy interfejsu API. Opis przykładów serwerów proxy interfejsu API i sposobu ich działania znajdziesz na stronie Lista przykładów.

Przykładowe serwery proxy, które korzystają ze zmiennych i ich przetwarzania, to m.in.:

  • variables (Zmienna) – pokazuje, jak wyodrębniać i ustawiać zmienne na podstawie transportu oraz zawartości wiadomości JSON i XML.
  • policy-mashup-cookbook – kompletna aplikacja, która używa składania reguł do wywołania 2 publicznych interfejsów API, łączy wyniki i generuje wzbogaconą odpowiedź dla aplikacji klienckiej. Więcej informacji o tym szablonie znajdziesz w artykule Korzystanie ze składania reguł.
  • conditional-policy – implementuje proste zasady warunkowego egzekwowania zasad na podstawie wartości zmiennych.

Powiązane artykuły