Korzystanie ze zmiennych

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

Zasadniczo zmienne przepływu to obiekty, do których masz dostęp w zasadach lub narzędziach (np. Narzędzie śledzenia). Pozwalają one zachować 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 interfejsu API w taki sposób, w jaki zmienne nazwane śledzą stan w programie. Zmienne przepływu przechowują informacje takie jak:

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

Niektóre zmienne są „wbudowane” w Edge i są automatycznie wypełniane po otrzymaniu żądania do interfejsu API. Są one dostępne podczas całej transakcji interfejsu API. Możesz też utworzyć własne zmienne niestandardowe za pomocą zasad takich jak PolicyMessage lub JavaScript, Node.js lub kod Java.

Jak widzisz, zmienne mają zakres i miejsce, w którym są dostępne, zależy częściowo od tego, kiedy zostały utworzone w interfejsie serwera proxy interfejsu API. Ogólnie rzecz biorąc, utworzona zmienna jest dostępna dla wszystkich zasad i kodu, które później są wykonywane w ramach procesu interfejsu API.

Jak używane są zmienne przepływu?

Zmienna przepływu jest używana 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 WeryfikacjaJWT może pobierać token do weryfikacji ze zmiennej przepływu, a następnie wykonywać na nim weryfikację. Innym przykładem jest zasada JavaScript, która może pobierać zmienne przepływu i kodować zawarte w nich dane.

  • Przepływy warunkowe mogą odwoływać się do zmiennych przepływu w celu skierowania przepływu interfejsu API przez Edge, na przykład w postaci instrukcji instrukcji Switch.

    Na przykład zasada zwracania błędu może być uruchamiana tylko wtedy, gdy określona jest 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 pobierają zmienne przepływu jako dane wejściowe.

Na przykład poniższe zasada MessagingMessage pobiera wartość zmiennej przepływu client.ip i umieszcza ją w nagłówku żądania o nazwie My-Client-IP. Jeśli dodasz ją do przepływu żądania, ta zasada ustawia nagłówek, który jest przekazywany do środowiska docelowego backendu. Jeśli jest ustawiony w przepływie odpowiedzi, nagłówek jest zwracany 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>

Inny przykład: gdy uruchomisz zasadę limitu, kilka zmiennych przepływu zostanie wypełnionych wartościami powiązanymi z zasadami. Jedna z tych zmiennych nosi nazwę ratelimit.my-quota-policy.used.count (gdzie my-quota-policy to nazwa interesującej Cię zasady limitu).

Później możesz wykonać przepływ warunkowy, który brzmi: „Jeśli obecna liczba limitów wynosi mniej niż 50%, a godz. 9:00–17:00, wymuszaj inny limit”. Ten warunek 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 brzegowych.

Zmienne przepływu w przepływach warunkowych

Przepływy warunkowe oceniają zmienne przepływu i pozwalają serwerom proxy działać dynamicznie. Warunki zwykle służą do zmiany działania przepływów, kroków i reguł trasy.

Oto przepływ warunkowy, który ocenia wartość zmiennej request.verb w kroku przepływu proxy. W takim przypadku, jeśli czasownik żądania ma postać POST, wykonywane jest zasadyVerifyAPIKey. 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>

Być może zastanawiasz się, skąd pochodzą zmienne takie jak request.verb, client.ip i system.time? Kiedy są tworzone wystąpienia i wypełniane wartością? Aby dowiedzieć się, kiedy są tworzone zmienne i kiedy są dla Ciebie dostępne, przeczytaj artykuł Omówienie zakresu zmiennych przepływu.

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

Korzystając z zasad dotyczących kodu JavaScript, możesz uruchamiać kod JavaScript z poziomu kontekstu serwera proxy interfejsu API. JavaScript wykonywany przez tę zasadę wykorzystuje model obiektów Apigee, który zapewnia dostęp do niestandardowego kodu z żądaniami, odpowiedziami i kontekstami związanymi z przebiegiem serwera proxy interfejsu API, w którym jest wykonywany kod. Na przykład ten kod ustawia nagłówek odpowiedzi z wartością uzyskaną ze zmiennej przepływu celu target.name.

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

Technika korzystania z kodu JavaScript do odczytu i ustawiania zmiennych jest podobna do pracy, którą można wykonać z zasadami PrzypiszMessage (pokazanymi wcześniej). To po prostu kolejny sposób, w jaki można osiągnąć te same rzeczy w Edge. Należy pamiętać, że JavaScript wykonywany przez zasadę JavaScript ma dostęp do wszystkich istniejących zmiennych przepływu, które znajdują się w zakresie w procesie proxy serwera API.

Zmienne przepływu w kodzie Node.js

Wymaganie modułu apigee-access umożliwia ustawianie zmiennych przepływu i dostęp do nich 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. Gdy to zrobisz, nowa zmienna stanie się dostępna dla wszystkich zasad i innego kodu, który wystąpi w procesie serwera proxy po wykonaniu kodu w 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 Uzyskiwanie dostępu do zmiennych przepływu w Node.js.

Omówienie zakresu zmiennych przepływu

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

Wizualizacja przepływu pracy serwera proxy interfejsu API

Aby zrozumieć, jak zmienia się zakres zmiennej przepływu, trzeba poznać lub zwizualizować przepływ wiadomości przez serwer proxy interfejsu API. Serwer proxy interfejsu API składa się z serii kroków przetwarzania wiadomości uporządkowanych według przepływu. Na każdym etapie procesu proxy serwer proxy ocenia dostępne informacje i decyduje, co zrobić dalej. Serwer proxy może wykonać kod zasady lub wykonać rozgałęzienie warunkowe.

Poniższa ilustracja przedstawia sekwencję przepływów. Zwróć uwagę na to, że przepływy składają się z 4 głównych segmentów: żądanie ProxyEndpoint, żądanie Docelowego punktu końcowego, odpowiedź Punktu końcowego Celu i odpowiedź ProxyEndpoint.

Pamiętaj o tej strukturze, gdy zaczynamy badać zmienne przepływu dotyczące pozostałej części tego tematu.

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

Gdy tylko zwizualizujesz przepływ wiadomości przez serwer proxy, jak opisano powyżej, możesz zacząć poznawać zakres zmiennych. Zakres oznacza punkt w cyklu życia serwera proxy, gdy zmienna jest uruchamiana po raz pierwszy.

Jeśli na przykład do zasady dołączone są segment żądań ProxyEndpoint, ta zasada nie będzie miała dostępu do żadnych zmiennych ograniczonych do segmentu żądania Docelowa brama. Wynika to z faktu, że w ramach tego żądania nie został jeszcze wykonany segment żądania TargetEndpoint, tak więc serwer proxy interfejsu API nie miał jeszcze możliwości wypełnienia zmiennych w tym zakresie.

W tabeli poniżej znajdziesz kompletny zestaw zakresów zmiennych, który wskazuje, kiedy na serwerze proxy staną się one dostępne.

Zakres zmiennej Gdzie są wypełniane te zmienne
żądanie serwera proxy Segment żądań ProxyEndpoint
żądanie docelowe Segment żądań TargetPoint
odpowiedź docelowa Segment reakcji na punkt końcowy
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 serwera proxy.

Masz na przykład wbudowaną zmienną Edge o nazwie client.ip. Ta zmienna ma zakres „żądania serwera proxy”. Jest automatycznie wypełniany adresem IP klienta, który wywołał serwer proxy. Wartość jest wypełniana, gdy żądanie najpierw dociera do ProxyEndpoint i pozostaje dostępne przez cały cykl życia serwera proxy.

Istnieje też inna wbudowana zmienna o nazwie target.url. Zakres tej zmiennej to „żądanie docelowe”. Wartość jest uzupełniana w segmencie żądania Docelowa wartość docelowa z adresem URL żądania wysyłanym do docelowego backendu. Jeśli spróbujesz uzyskać dostęp do target.url w segmencie żądań ProxyEndpoint, otrzymasz wartość NULL. Jeśli spróbujesz ustawić tę zmienną, zanim znajdzie się w zakresie, serwer proxy nic nie robi – nie wygeneruje błędu ani nie ustawi zmiennej.

Oto prosty przykład, który pokazuje, jak myśleć o zakresie zmiennych. Załóżmy, że chcesz skopiować całą zawartość obiektu żądania (nagłówki, parametry, treść) i przypisać go do ładunku odpowiedzi, aby przesłać go z powrotem do aplikacji do wykonywania połączeń. W tym zadaniu możesz użyć zasad usługi MessagingMessage. Wygląda to tak:

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

Ta zasada tylko kopiuje obiekt request i przypisuje go do obiektu response. Gdzie należy umieścić tę zasadę w procesie serwera proxy? Należy go umieścić w odpowiedzi TargetPoint, bo zakres zmiennej odpowiedzi to „target odpowiedzi”.

Odwoływania się do zmiennych przepływu

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

Apigee rezerwuje różne prefiksy, aby odpowiednio porzą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ższe zasada MessagingMessage 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ą potrzebne. 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 dokładnie zdefiniowany typ danych, np. Ciąg, Długi, Liczba całkowita, Wartość logiczna lub Kolekcja. Typy danych znajdziesz w dokumentacji zmiennych zmiennych. Informacje o zmiennych utworzonych przez zasadę znajdziesz w odpowiednim temacie referencyjnym zasad.

Zmienne tworzone przez Ciebie 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 wartości liczbowych, ciągów znaków, wartości logicznych, wartości null lub nieokreślenia.

Używanie zmiennych przepływu w zasadach

Wiele zasad tworzy zmienne przepływu w ramach normalnego wykonywania. W dokumentacji zasady znajdziesz informacje o wszystkich zmiennych.

Podczas pracy z serwerami proxy i zasadami zapoznaj się z informacjami o zasadach, aby dowiedzieć się, jakie zmienne są tworzone i do czego są używane. Zasada limitu tworzy na przykład zestaw zmiennych zawierających informacje o liczbie i limitach, czasie wygaśnięcia itd.

Niektóre zmienne zasady przydają się do debugowania. Możesz na przykład użyć narzędzia śledzenia, aby zobaczyć, które zmienne zostały skonfigurowane w konkretnej instancji w procesie 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 przeanalizować wiadomości z żądaniami i odpowiedziami za pomocą wzorców, aby wyodrębnić z nich określone dane.

W tym przykładzie wyodrębnione zmienne analizują komunikat odpowiedzi i przechowują określone dane pobrane w odpowiedzi. Ta zasada tworzy 2 zmienne niestandardowe 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. Dostęp do tych zmiennych możesz uzyskać w kontekście procesu proxy, a informacje na ten temat znajdziesz w dokumentacji dotyczącej poszczególnych tematów zasad.

Praca ze zmiennymi przepływu w kodzie JavaScript

Możesz uzyskać dostęp do zmiennych i ustawić je bezpośrednio w kodzie JavaScript, który wykonuje się w kontekście serwera proxy interfejsu API. Za pomocą modelu obiektu JavaScript Apigee kod JavaScript wykonujący 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 dowolnego z tych obiektów:

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

Jak widać, odwołania do tych obiektów są mapowane na znane segmenty modelu przepływu pracy zgodnie z opisem w sekcji Wizualizacja przepływu pracy serwera proxy interfejsu API.

Obiekt context odpowiada „dostępnym globalnie” 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ć metodę setVariable(), by ustawić wartość zmiennej niestandardowej lub dowolnych zmiennych możliwych do zapisu. Tworzymy w nim zmienną niestandardową o nazwie organization.name.myorg i przypisujemy do niej wartość.

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

Ta zmienna jest tworzona za pomocą obiektu context, dlatego będzie dostępna dla wszystkich segmentów przepływu (zasadniczo przypomina to utworzenie zmiennej globalnej).

Możesz też pobierać/ustawiać zmienne przepływu proxy w kodzie Java, które są wykonywane za pomocą zasad JavaJava.

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 dodasz „wymaganie” modułu dostępu Apigee. Szczegółowe informacje znajdziesz w artykule o uzyskiwaniu dostępu do zmiennych przepływu w Node.js.

O czym musisz pamiętać

Oto kilka ważnych informacji o zmiennych przepływu:

  • Niektóre gotowe zmienne są tworzone automatycznie i automatycznie uzupełniane przez serwer proxy. Ich listę znajdziesz w przewodniku po zmiennych zmiennych.
  • Możesz utworzyć zmienne niestandardowe, których będzie można używać w ramach wzorca serwera proxy. Możesz tworzyć zmienne, korzystając z zasad takich jak Przypisz zasady czy zasady JavaScript oraz kodu Node.js.
  • Zmienne mają zakres. Na przykład niektóre zmienne są automatycznie wypełniane, gdy pierwszy serwer proxy otrzymuje żądanie z aplikacji. Inne zmienne są wypełniane w segmencie przepływu pracy serwera proxy. Zmienne odpowiedzi pozostaną niezdefiniowane, dopóki segment odpowiedzi nie zostanie uruchomiony.
  • Podczas wykonywania zasad mogą oni tworzyć i wypełniać zmienne powiązane z zasadami. Dokumentacja poszczególnych zasad zawiera listę wszystkich odpowiednich zmiennych związanych z zasadami.
  • Przepływy warunkowe zwykle oceniają co najmniej jedną zmienną. Jeśli chcesz tworzyć przepływy warunkowe, musisz znać zmienne.
  • Wiele zasad używa danych wejściowych 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 za pomocą prostego kodu JavaScript (i naszego modelu obiektu JavaScript) lub zasad JavaJava, które wykonują kod na Edge.

Przykładowe fragmenty kodu

Próbki serwera proxy interfejsu API znajdują się na GitHubie. Można je łatwo pobrać i używać. Informacje o pobieraniu i korzystaniu z przykładów znajdziesz w artykule Korzystanie z przykładowych serwerów proxy interfejsu API. Opis próbek serwera proxy interfejsu API i ich zastosowania znajdziesz w liście przykładów.

Przykładowe serwery proxy, które umożliwiają korzystanie ze zmiennych i przetwarzania zmiennych, to:

  • Zmienne – 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.
  • warunkowo-zasady – wdraża proste warunkowe stosowanie zasad na podstawie wartości zmiennych.

Powiązane artykuły