Programowanie proxy interfejsu API za pomocą JavaScriptu

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

Z tego tematu dowiesz się, jak używać JavaScriptu do dynamicznego dodawania nagłówków HTTP do wiadomości z odpowiedzią oraz jak analizować odpowiedź JSON i zwrócić podzbiór jej właściwości do aplikacji wysyłającej żądanie.

Pobierz i wypróbuj przykładowy kod

Informacje o książce kucharskiej

Ten przykład książki kucharskiej pokazuje wzorzec serwera proxy interfejsu API, w którym implementujesz działanie interfejsu API w JavaScripcie. Z przykładów JavaScriptu dowiesz się, jak korzystać z prostych zmiennych i treści wiadomości. W jednym z przykładów pokazujemy, jak pobierać i ustawiać zmienne. Drugi przykład pokazuje, jak przeanalizować plik JSON i utworzyć wiadomość na podstawie wyniku.

Serwer proxy interfejsu API zawiera 2 przykłady kodu JavaScript:

  • setHeaders.js: ten kod JavaScript pobiera wartości kilku zmiennych ustawianych przy wywołaniu serwera proxy interfejsu API. JavaScript dodaje te zmienne do wiadomości z odpowiedzią, dzięki czemu możesz zobaczyć ich wartości w przypadku każdego wysyłanego żądania.
  • minimize.js: ten kod JavaScript pokazuje, jak pracować z treścią wiadomości. W przypadku tego przykładu usługa często zwraca więcej danych, niż jest to konieczne. JavaScript analizuje więc wiadomość z odpowiedzią, wyodrębnia kilka interesujących właściwości, a potem używa ich do utworzenia treści tej wiadomości.

Kod dla firmy setHeader.js:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

Kod dla firmy minimize.js:

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

Dostęp do zmiennych przepływu w JavaScripcie możesz uzyskać za pomocą obiektu kontekstu. Ten obiekt jest częścią modelu obiektu JavaScript Edge. Szczegółowe informacje o modelu obiektowym znajdziesz w sekcji Obiektowy model JavaScript.

Zanim zaczniesz

Zanim zapoznasz się z przykładem z książki kucharskiej, zapoznaj się z podstawowymi pojęciami:

  • Czym są zasady i jak podłączyć je do serwerów proxy. Szczegółowe informacje o zasadach znajdziesz w artykule Czym jest zasada?
  • Struktura przepływu proxy została opisana w sekcji Konfigurowanie przepływów. Przepływy pozwalają określić kolejność wykonywania zasad przez serwer proxy interfejsu API. W tym przykładzie tworzymy kilka zasad i dodaje się je do przepływu pracy serwera proxy interfejsu API.
  • Organizacja projektu serwera proxy interfejsu API w systemie plików zgodnie z opisem w dokumentacji dotyczącej konfiguracji serwera proxy interfejsu API.
  • Praktyczna znajomość języka XML, JSON i JavaScript. W tym przykładzie utworzysz serwer proxy interfejsu API i jego zasady za pomocą plików XML znajdujących się w systemie plików.

Jeśli masz już pobrany przykładowy kod, wszystkie pliki omówione w tym temacie znajdziesz w folderze javascript-cookbook. W poniższych sekcjach szczegółowo omawiamy przykładowy kod.

Omówienie przepływu serwera proxy

Aby skrypt JavaScript był wykonywany przez serwer proxy interfejsu API, musisz dołączyć go do procesu za pomocą załącznika zasad o nazwie „Step”. Zasada typu JavaScript (zwróć uwagę na wielkość liter) zawiera tylko odwołanie do nazwy pliku JavaScript. Kierujesz zasadę na plik JavaScript za pomocą elementu ResourceURL.

Na przykład ta zasada odwołuje się do pliku JavaScript o nazwie setHeader.js.

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

Możesz dołączyć tę zasadę do procesu serwera proxy interfejsu API tak jak w przypadku każdego innego typu zasad. Dołączając zasadę do procesu serwera proxy interfejsu API, wskazujesz miejsce wykonywania JavaScriptu. Dzięki temu możesz uruchomić kod JavaScript, który wchodzi w interakcję z komunikatami żądań lub odpowiedzią, gdy te wiadomości „przepływają” przez serwer proxy interfejsu API. W tym przykładzie oba skrypty JavaScript są wykonywane w przepływie odpowiedzi, ponieważ zasady wykonują 2 czynności: ustawiają nagłówki HTTP w wiadomości z odpowiedzią i „minimalizują” komunikat z odpowiedzią, który Apigee Edge zwraca do aplikacji żądającej.

Jeśli otworzysz tę konfigurację przepływu w interfejsie zarządzania, zobaczysz poniższą konfigurację przepływu.

W panelu Navigator wybierz Proxy Endpoints > default > PostFlow.

Poniżej znajduje się odpowiednia konfiguracja XML dla punktu końcowego ProxyEndpoint o nazwie „default”. 

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Oto podsumowanie elementów przepływu.

  • <Request> – element <Request> składa się z kilku elementów <Step>. Każdy krok wywołuje jedną z zasad, które utworzysz w pozostałej części tego tematu. Te zasady dołączają JavaScript do procesu serwera proxy interfejsu API, a lokalizacja załącznika zasad określa, kiedy JavaScript jest wykonywany.
  • <Response> – element <Response> zawiera też element <Steps>. Te kroki wywołują także zasady odpowiedzialne za przetwarzanie ostatecznej odpowiedzi ze środowiska docelowego (w tym przykładzie jest to próbny cel usługi Apigee – zwróć uwagę na ustawienie HTTPTargetConnection w /apiproxy/targets/default.xml).
  • <HTTPProxyConnection> – określa ścieżkę hosta i identyfikator URI, które definiują adres sieciowy wywoływany przez aplikacje w celu korzystania z tego interfejsu API.
  • <RouteRule> – ten element określa, która konfiguracja TargetEndpoint jest wywoływana przez ProxyEndpoint.

Dodawanie kodu JavaScript do serwera proxy

Kod JavaScript (np. skrypty Python, pliki Java JAR, pliki SDF itd.) są przechowywane jako zasoby. Gdy dopiero zaczynasz korzystać z JavaScriptu, najprościej będzie przechowywać pliki JavaScript na serwerze proxy interfejsu API. W miarę postępów język JavaScript powinien być jak najbardziej ogólny i przydatny do wielokrotnego użytku, a potem przechowywać go na poziomie środowiska lub organizacji. Zapobiega to konieczności przechowywania tych samych plików JavaScript na wielu serwerach proxy interfejsów API, którymi łatwo zarządzać.

Więcej informacji o przechowywaniu zasobów na poziomie organizacji i środowiska znajdziesz w artykule Pliki zasobów.

Wypróbuj

Instrukcje wdrażania i wywoływania serwera proxy znajdziesz w pliku README książki kucharskiej JavaScript.

Importowanie i wdrażanie serwera proxy interfejsu API

Po wprowadzeniu zmian możesz zapisać serwer proxy interfejsu API w narzędziu do tworzenia serwerów proxy interfejsów API w interfejsie zarządzania.

Możesz też uruchomić to polecenie w katalogu /api-platform-samples/doc-samples/javascript-cookbook.

$ sh deploy.sh

Testowanie JavaScriptu

Uruchom to polecenie w katalogu /api-platform-samples/doc-samples/javascript-cookbook.

$ sh invoke.sh

Flaga curl -v jest używana w skrypcie powłoki do wyświetlania nagłówków HTTP w wiadomości z odpowiedzią zmodyfikowaną przez JavaScript.

Możesz przesłać prośbę bezpośrednio w ten sposób:

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook

Jeśli kod JavaScript będzie wykonywany prawidłowo, zobaczysz odpowiedź podobną do tej:

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

Możesz teraz zmodyfikować JavaScript, aby testować nowe rzeczy, ponownie wdrożyć serwer proxy interfejsu API i zweryfikować wyniki, przesyłając to samo żądanie. Aby zmiany zostały wprowadzone, zawsze pamiętaj o wdrażaniu serwera proxy interfejsu API zawierającego kod JavaScript.

Błędy skryptu

Podczas pisania JavaScriptu często występują błędy. Poniżej znajdziesz format błędów JavaScriptu wywoływanych przez serwer proxy interfejsu API.

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

Kiedy używać JavaScriptu

W Apigee Edge zwykle można wdrożyć określone funkcje na kilka sposobów. W miarę możliwości używaj gotowych zasad i unikaj pokusy kodowania całej logiki serwera proxy interfejsu API w języku JavaScript. Mimo że Apigee Edge korzysta ze skompilowanego kodu JavaScript do zwiększenia wydajności, mało prawdopodobne jest, że JavaScript będzie działać tak samo jak w przypadku zasad. Obsługa JavaScriptu i jego debugowanie może być trudniejsza do obsługi. Zarezerwuj JavaScript na potrzeby funkcji dopasowanych do Twoich wymagań.

Jeśli wydajność dotyczy niestandardowych funkcji, w miarę możliwości używaj Javy.

Podsumowanie

W tym temacie z książki kucharskiej omówiliśmy, jak dodać JavaScript do konfiguracji serwera proxy interfejsu API, aby wdrożyć działanie niestandardowe. Niestandardowe zachowanie zaimplementowane z przykładów pokazuje, jak pobierać i zmienne oraz analizować JSON i tworzyć niestandardowe wiadomości z odpowiedziami.