Programowanie proxy interfejsu API za pomocą JavaScriptu

Wyświetlasz dokumentację Apigee Edge.
Przejdź do dokumentacji Apigee X. info

Z tego artykułu dowiesz się, jak za pomocą JavaScriptu dynamicznie dodawać nagłówki HTTP do wiadomości z odpowiedzią oraz jak analizować odpowiedź JSON i zwracać podzbiór jej właściwości do aplikacji wysyłającej żądanie.

Pobieranie i testowanie przykładowego kodu

Informacje o tym przykładzie

Ten przykład ilustruje wzorzec serwera proxy interfejsu API, w którym implementujesz działanie interfejsu API w JavaScript. Przykłady JavaScriptu mają na celu pokazanie, jak pracować z prostymi zmiennymi i treścią wiadomości. Jeden przykład pokazuje, jak pobierać i ustawiać zmienne. Drugi przykład pokazuje, jak analizować JSON i tworzyć wiadomość na podstawie wyniku.

W serwerze proxy interfejsu API znajdują się 2 przykłady JavaScriptu:

  • setHeaders.js: ten kod JavaScript pobiera wartości kilku zmiennych, które są ustawiane podczas wywoływania serwera proxy interfejsu API. JavaScript dodaje te zmienne do wiadomości z odpowiedzią , dzięki czemu możesz zobaczyć ich wartości dla każdego wysyłanego żądania.
  • minimize.js: ten kod JavaScript pokazuje, jak pracować z treścią wiadomości. Założenie tego przykładu jest takie, że usługa często zwraca więcej danych niż jest to konieczne. Dlatego JavaScript analizuje wiadomość z odpowiedzią, wyodrębnia kilka interesujących właściwości, a następnie używa ich do utworzenia treści wiadomości z odpowiedzią.

Kod 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 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 JavaScript możesz uzyskać za pomocą obiektu context. Ten obiekt jest częścią modelu obiektów JavaScript Edge. Szczegółowe informacje o modelu obiektów znajdziesz w artykule Model obiektów JavaScript.

Zanim zaczniesz

Zanim zapoznasz się z tym przykładem, musisz też znać te podstawowe pojęcia:

  • Czym są zasady i jak je dołączać do serwerów proxy. Wprowadzenie do zasad znajdziesz w artykule Czym jest zasada?.
  • Struktura przepływu serwera proxy, jak wyjaśniono w artykule Konfigurowanie przepływów. Przepływy umożliwiają określenie kolejności wykonywania zasad przez serwer proxy interfejsu API. W tym przykładzie tworzymy kilka zasad i dodajemy je do przepływu serwera proxy interfejsu API.
  • Jak projekt serwera proxy interfejsu API jest zorganizowany w systemie plików, jak wyjaśniono w artykule Odwołanie do konfiguracji serwera proxy interfejsu API.
  • Praktyczna znajomość XML, JSON i JavaScript. W tym przykładzie tworzysz serwer proxy interfejsu API i jego zasady za pomocą plików XML znajdujących się w systemie plików.

Jeśli masz pobrany przykładowy kod, wszystkie pliki omówione w tym artykule znajdziesz w folderze javascript-cookbook. W kolejnych sekcjach szczegółowo omówimy przykładowy kod.

Informacje o przepływie serwera proxy

Aby JavaScript był wykonywany w serwerze proxy interfejsu API, musisz dołączyć go do przepływu za pomocą dołączenia zasady o nazwie „Krok”. Zasada typu Javascript (pamiętaj o wielkich literach) zawiera tylko odwołanie do nazwy pliku JavaScript. Wskaż 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>

Tę zasadę możesz dołączyć do przepływu serwera proxy interfejsu API tak samo jak każdy inny typ zasady. Dołączając zasadę do przepływu serwera proxy interfejsu API, wskazujesz, gdzie ma być wykonywany kod JavaScript. Dzięki temu możesz wykonywać kod JavaScript, który wchodzi w interakcję z wiadomościami z żądaniami lub wiadomościami z odpowiedziami 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ą” wiadomość z odpowiedzią, którą Apigee Edge zwraca do aplikacji wysyłającej żądanie.

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

W panelu nawigacji wybierz Punkty końcowe serwera proxy > domyślne > PostFlow.

Poniżej znajdziesz odpowiednią konfigurację XML dla ProxyEndpoint o nazwie „default”. Jest ona pokazana poniżej. 

<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 tworzysz w dalszej części tego tego artykułu. Te zasady dołączają JavaScript do przepływu serwera proxy interfejsu API, a lokalizacja dołączenia zasady określa, kiedy JavaScript jest wykonywany.
  • <Response> – element <Response> też zawiera <Steps>. Te kroki też wywołują zasady, które odpowiadają za przetwarzanie ostatecznej odpowiedzi z miejsca docelowego (w tym przykładzie jest to miejsce docelowe usługi pozorowanej Apigee – zwróć uwagę na ustawienie HTTPTargetConnection w sekcji /apiproxy/targets/default.xml).
  • <HTTPProxyConnection> – określa hosta i ścieżkę URI, które definiują adres sieciowy, pod którym aplikacje wywołują ten interfejs API.
  • <RouteRule> – ten element określa, która konfiguracja TargetEndpoint jest wywoływana przez ProxyEndpoint.

Dodawanie kodu JavaScript do serwera proxy

JavaScript (podobnie jak skrypty w Pythonie, pliki JAR w Javie, pliki XSLT itp.) są przechowywane jako zasoby. Gdy dopiero zaczynasz pracę z JavaScriptem, najłatwiej jest przechowywać pliki JavaScript w serwerze proxy interfejsu API. W miarę postępów JavaScript powinien być jak najbardziej ogólny i wielokrotnego użytku, a następnie przechowywany na poziomie środowiska lub organizacji. Dzięki temu nie musisz przechowywać tych samych plików JavaScript w wielu serwerach proxy interfejsu API, co może szybko stać się trudne do zarządzania.

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 dołączonym do przykładu 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 interfejsu 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

W skrypcie powłoki używamy flagi `curl -v` -v, aby wyświetlić nagłówki HTTP w wiadomości z odpowiedzią zmodyfikowanej przez JavaScript.

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

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

Jeśli JavaScript zostanie wykonany 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 wypróbować nowe funkcje, wdrożyć ponownie proxy interfejsu API i sprawdzić wyniki, przesyłając to samo żądanie. Aby zmiany zostały wprowadzone, zawsze wdrażaj serwer proxy interfejsu API, który zawiera Twój kod JavaScript.

Błędy skryptów

Podczas pisania kodu JavaScript nieuchronnie pojawią się błędy. Poniżej znajdziesz format błędów JavaScriptu, które będą wyświetlane 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 istnieje więcej niż 1 sposób na zaimplementowanie określonej funkcji. Jeśli to możliwe, używaj gotowych zasad i unikaj pokusy kodowania całej logiki serwera proxy interfejsu API w JavaScript. Chociaż Apigee Edge wykorzystuje skompilowany kod JavaScript, aby zwiększyć wydajność, jest mało prawdopodobne, że JavaScript będzie działać tak dobrze jak zasady. JavaScript może być trudniejszy w utrzymaniu i debugowaniu. JavaScript należy rezerwować do funkcji, które są unikalne dla Twoich wymagań.

Jeśli wydajność jest ważna w przypadku funkcji niestandardowych, w miarę możliwości używaj Javy.

Podsumowanie

Z tego artykułu dowiesz się, jak uwzględnić JavaScript w konfiguracji serwera proxy interfejsu API , aby zaimplementować niestandardowe działanie. Niestandardowe działanie zaimplementowane w przykładach pokazuje, jak pobierać i ustawiać zmienne oraz jak analizować JSON i tworzyć niestandardowe wiadomości z odpowiedziami.