Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje
Co
Ta zasada pozwala dodać niestandardowy kod JavaScript, który jest wykonywany w kontekście przepływu pracy serwera proxy interfejsu API. W niestandardowym kodzie JavaScript możesz korzystać z obiektów, metod i właściwości obiektowego modelu JavaScript Apigee Edge. Model obiektowy umożliwia pobieranie, ustawianie i usuwanie zmiennych w kontekście przepływu serwera proxy. Możesz też używać podstawowych funkcji kryptograficznych udostępnianych przez model obiektowy.
Informacje
Zasady JavaScriptu mają wiele zastosowań. Możesz na przykład pobierać i ustawiać zmienne przepływu, wykonywać niestandardowe logiki i obsługiwać błędy, wyodrębniać dane z żądań lub odpowiedzi, dynamicznie edytować docelowy adres URL backendu i wykonywać wiele innych działań. Ta zasada umożliwia wdrożenie niestandardowego zachowania, którego nie obejmują żadne inne standardowe zasady brzegowe. W rzeczywistości można użyć zasady JavaScript, aby uzyskać wiele podobnych zachowań zaimplementowanych w innych zasadach, takich jak AssignMessage i ExtractVariable.
Jednym z przypadków użycia, których nie zalecamy w przypadku zasad JavaScriptu, jest logowanie. Zasada logowania wiadomości znacznie lepiej sprawdza się w przypadku logowania na zewnętrznych platformach logowania, takich jak Splunk, Sumo i Loggly, a także zwiększa wydajność serwera proxy interfejsu API przez uruchomienie zasady logowania wiadomości w PostClientFlow, która jest uruchamiana po zwróceniu odpowiedzi do klienta.
Zasada JavaScript pozwala wskazać plik źródłowy JavaScript do wykonania. Kod JavaScript możesz umieścić bezpośrednio w konfiguracji zasady za pomocą elementu <Source>
.
W obu przypadkach kod JavaScript jest uruchamiany podczas wykonywania kroku, do którego dołączono zasadę.
W przypadku pliku źródłowego kod źródłowy jest zawsze przechowywany w standardowej lokalizacji w pakiecie serwerów proxy: apiproxy/resources/jsc
. Możesz też zapisać kod źródłowy w pliku zasobów na poziomie środowiska lub organizacji. Instrukcje znajdziesz w artykule Pliki zasobów. Możesz też przesłać JavaScript za pomocą edytora proxy interfejsu Apigee.
Pliki źródłowe JavaScript muszą zawsze mieć rozszerzenie .js
.
Informacje o obecnie obsługiwanej wersji JavaScriptu znajdziesz na stronie z artykułem Obsługiwane i obsługiwane wersje.
Wideo
Obejrzyj krótki film, aby dowiedzieć się, jak utworzyć niestandardowe rozszerzenie zasad za pomocą zasady JavaScript.
Sample
Przepisywanie docelowego adresu URL
Typowy przypadek użycia: wyodrębnianie danych z treści żądania, przechowywanie ich w zmiennej przepływu i używanie tej zmiennej w innym miejscu procesu serwera proxy. Załóżmy, że masz aplikację, w której użytkownik wpisuje swoją nazwę w formularzu HTML i ją przesyła. Chcesz, aby serwer proxy interfejsu API wyodrębniał dane formularza i dynamicznie dodawał je do adresu URL używanego do wywoływania usługi backendu. Jak to zrobić w zasadzie JavsScript?
Uwaga: jeśli chcesz wypróbować ten przykład, zakładamy, że w edytorze proxy został utworzony nowy serwer proxy. Podczas tworzenia nadaj mu adres URL usługi backendu: http://www.example.com. W tym przykładzie będziemy dynamicznie przepisywać adres URL backendu. Jeśli nie wiesz, jak utworzyć nowy serwer proxy, zapoznaj się z samouczkiem dla początkujących. .
- W interfejsie użytkownika Edge otwórz serwer proxy utworzony w edytorze proxy.
- Wybierz kartę Programowanie.
- W menu Nowy wybierz Nowy skrypt.
- W oknie wybierz JavaScript i nadaj skryptowi nazwę, np.
js-example
. - Wklej poniższy kod w edytorze kodu i zapisz serwer proxy. Najważniejszą cechą jest obiekt
context
. Ten obiekt jest dostępny dla kodu JavaScript w dowolnym miejscu procesu serwera proxy. Służy do uzyskiwania stałych związanych z przepływem, wywoływania przydatnych metod get/set i na potrzeby większej liczby operacji. Ta część obiektu jest częścią obiektowego modelu JavaScript Edge. Pamiętaj też, że zmienna przepływutarget.url
jest wbudowaną zmienną do odczytu i zapisu, która jest dostępna w przepływie docelowego żądania. Gdy ustawiamy tę zmienną za pomocą adresu URL interfejsu API, Edge wysyła wywołanie backendu do tego adresu URL. Zasadniczo napisano od nowa oryginalny docelowy adres URL – czyli taki, jaki został określony podczas tworzenia serwera proxy (np. http://www.example.com).
if (context.flow=="PROXY_REQ_FLOW") { var username = context.getVariable("request.formparam.user"); context.setVariable("info.username", username); } if (context.flow=="TARGET_REQ_FLOW") { context.setVariable("request.verb", "GET"); var name = context.getVariable("info.username"); var url = "http://mocktarget.apigee.net/" context.setVariable("target.url", url + "?user=" + name); }
- W menu Nowa zasada wybierz JavaScript.
- Nazwij zasadę np.
target-rewrite
. Zaakceptuj wartości domyślne i zapisz zasadę. - Jeśli w nawigatorze wybierzesz wstępne przetwarzanie punktu końcowego serwera proxy, zobaczysz, że zasada została dodana do tego procesu.
- W nawigatorze kliknij ikonę Target Endpoint PreFlow.
- Z nawigatora przeciągnij zasadę JavaScriptu w edytorze przepływu po stronie żądania, na docelowy punkt końcowy.
- Zapisz.
- Wywołaj interfejs API w ten sposób, zastępując poprawną nazwę organizacji i serwer proxy:
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example
Na koniec przyjrzyjmy się definicji XML zasady JavaScriptu użytej w tym przykładzie. Pamiętaj, że element <ResourceURL>
służy do określenia pliku źródłowego JavaScript do wykonania. Ten sam wzorzec jest używany w przypadku każdego pliku źródłowego JavaScript: jsc://filename.js
. Jeśli kod JavaScript wymaga elementów uwzględnionych, możesz użyć do tego co najmniej 1 elementu <IncludeURL>
w sposób opisany w dalszej części tego przewodnika.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite"> <DisplayName>target-rewrite</DisplayName> <Properties/> <ResourceURL>jsc://js-example.js</ResourceURL> </Javascript>
Pobierz wartość właściwości z JavaScriptu
Możesz dodać element <Property>
w konfiguracji, a następnie pobierać jego wartość za pomocą kodu JavaScript w czasie działania.
Użyj atrybutu name
elementu, aby określić nazwę, za pomocą której chcesz uzyskać dostęp do właściwości z kodu JavaScript. Wartość elementu <Property>
(wartość między tagiem otwierającym i zamykającym) to literał, którą otrzyma JavaScript.
W JavaScripcie wartość właściwości zasady pobiera się, uzyskując do niej dostęp jako właściwość obiektu Properties
, jak w tym przykładzie:
- Skonfiguruj usługę. W tym przypadku wartością właściwości jest nazwa zmiennej
response.status.code
.<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavascriptURLRewrite"> <DisplayName>JavascriptURLRewrite</DisplayName> <Properties> <Property name="source">response.status.code</Property> </Properties> <ResourceURL>jsc://JavascriptURLRewrite.js</ResourceURL> </Javascript>
- Pobierz właściwość za pomocą JavaScriptu. W tym przypadku pobrana wartość (nazwa zmiennej) jest następnie używana przez funkcję
getVariable
do pobrania wartości zmiennej.var responseCode = properties.source; // Returns "response.status.code" var value = context.getVariable(responseCode); // Get the value of response.status.code context.setVariable("response.header.x-target-response-code", value);
Obsługa błędów
Przykłady i omówienie technik obsługi błędów, których możesz używać w objaśnieniach JavaScript, znajdziesz w tym poście w społeczności Apigee. Sugestie oferowane w społeczności Apigee mają charakter wyłącznie informacyjny i nie muszą być zgodne ze sprawdzonymi metodami rekomendowanymi przez Apigee.
Odwołanie do elementu
Dokumentacja elementów opisuje elementy i atrybuty zasady JavaScript.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavaScript-1"> <DisplayName>JavaScript 1</DisplayName> <Properties> <Property name="propName">propertyValue</Property> </Properties> <SSLInfo> <Enabled>trueFalse</Enabled> <ClientAuthEnabled>trueFalse</ClientAuthEnabled> <KeyStore>ref://keystoreRef</KeyStore> <KeyAlias>keyAlias</KeyAlias> <TrustStore>ref://truststoreRef</TrustStore> </SSLInfo> <IncludeURL>jsc://a-javascript-library-file</IncludeURL> <ResourceURL>jsc://my-javascript-source-file</ResourceURL> <Source>insert_js_code_here</Source> </Javascript>
Atrybuty <Javascript>
<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">
Poniższe atrybuty są specyficzne dla tych zasad.
Atrybut | Opis | Domyślne | Obecność |
---|---|---|---|
timeLimit |
Określa maksymalny dozwolony czas wykonania skryptu (w milisekundach). Jeśli na przykład przekroczono limit 200 ms, zasada spowoduje zgłoszenie tego błędu: Uwaga: w przypadku bezpłatnych kont próbnych czas wykonania jest ograniczony do 200 ms. |
Nie dotyczy | Wymagane |
Tabela poniżej zawiera opis atrybutów wspólnych dla wszystkich elementów nadrzędnych zasad:
Atrybut | Opis | Domyślne | Obecność |
---|---|---|---|
name |
Wewnętrzna nazwa zasady. Wartość atrybutu Opcjonalnie możesz użyć elementu |
Nie dotyczy | Wymagane |
continueOnError |
Ustaw wartość Ustaw jako |
false | Opcjonalnie |
enabled |
Ustaw jako Ustaw wartość |
prawda | Opcjonalnie |
async |
Ten atrybut został wycofany. |
false | Wycofano |
Element <DisplayName>
Użyj oprócz atrybutu name
, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną nazwą w języku naturalnym.
<DisplayName>Policy Display Name</DisplayName>
Domyślne |
Nie dotyczy Jeśli pominiesz ten element, zostanie użyta wartość atrybutu |
---|---|
Obecność | Opcjonalnie |
Typ | Ciąg znaków |
Element <IncludeURL>
Określa plik biblioteki JavaScript, który ma być wczytywany jako zależność od głównego pliku JavaScript określonego za pomocą elementu <ResourceURL>
lub <Source>
. Skrypty będą oceniane w kolejności, w jakiej są wymienione w zasadzie. Twój kod może korzystać z obiektów, metod i właściwości obiektowego modelu JavaScript.
Uwzględnij więcej niż 1 zasób zależności JavaScript z dodatkowymi elementami <IncludeURL>
.
<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>
Domyślnie: | Brak |
Obecność: | Opcjonalnie |
Typ: | Ciąg znaków |
Przykład
Zapoznaj się z podstawowym przykładem w sekcji Sample.
Element <Property>
Wskazuje właściwość, do której można uzyskać dostęp z kodu JavaScript w czasie działania.
<Properties> <Property name="propName">propertyValue</Property> </Properties>
Domyślnie: | Brak |
Obecność: | Opcjonalnie |
Typ: | Ciąg znaków |
Atrybuty
Atrybut | Opis | Domyślne | Obecność |
---|---|---|---|
nazwa |
Określa nazwę właściwości. |
Nie dotyczy | To pole jest wymagane. |
Przykład
Zobacz przykład w sekcji Sample.
Element <ResourceURL>
Określa główny plik JavaScript, który będzie wykonywany w ramach przepływu interfejsu API. Możesz zapisać ten plik na poziomie serwera proxy interfejsu API (w sekcji /apiproxy/resources/jsc
w pakiecie proxy API lub w sekcji Skrypty w panelu nawigacji edytora proxy interfejsu API) albo w zakresach organizacji lub środowisk do ponownego użycia w wielu serwerach proxy interfejsu API, jak opisano w Pliki zasobów. Twój kod może korzystać z obiektów, metod i właściwości obiektowego modelu JavaScript.
<ResourceURL>jsc://my-javascript.js</ResourceURL>
Domyślnie: | Brak |
Obecność: | Wymagana jest wartość <ResourceURL> lub <Source> . Jeśli obecne są zarówno <ResourceURL> , jak i <Source> , funkcja <ResourceURL> jest ignorowana. |
Typ: | Ciąg znaków |
Przykład
Zapoznaj się z podstawowym przykładem w sekcji Sample.
Element <Source>
Umożliwia wstawienie kodu JavaScript bezpośrednio do konfiguracji XML zasady. Wstawiony kod JavaScript jest uruchamiany podczas wykonywania zasady w przepływie interfejsu API.
Domyślnie: | Brak |
Obecność: | Wymagana jest wartość <ResourceURL> lub <Source> . Jeśli obecne są zarówno <ResourceURL> , jak i <Source> , funkcja <ResourceURL> jest ignorowana. |
Typ: | Ciąg znaków |
Przykład
<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' > <Properties> <Property name='inboundHeaderName'>specialheader</Property> <Property name='outboundVariableName'>json_stringified</Property> </Properties> <Source> var varname = 'request.header.' + properties.inboundHeaderName + '.values.string'; var h = context.getVariable(varname); if (h) { h = JSON.parse(h); h.augmented = (new Date()).valueOf(); var v = JSON.stringify(h, null, 2) + '\n'; // further indent var r = new RegExp('^(\S*)','mg'); v= v.replace(r,' $1'); context.setVariable(properties.outboundVariableName, v); } </Source> </Javascript>
Element <SSLInfo>
Określa właściwości używane do konfigurowania TLS w przypadku wszystkich instancji klienta HTTP tworzonych przez zasadę JavaScript.
<SSLInfo> <Enabled>trueFalse</Enabled> <ClientAuthEnabled>trueFalse</ClientAuthEnabled> <KeyStore>ref://keystoreRef</KeyStore> <KeyAlias>keyAlias</KeyAlias> <TrustStore>ref://truststoreRef</TrustStore> </SSLInfo>
Domyślnie: | Brak |
Obecność: | Opcjonalnie |
Typ: | Ciąg znaków |
Proces konfigurowania protokołu TLS dla klienta HTTP jest taki sam jak w przypadku konfigurowania protokołu TLS dla punktu końcowego docelowego lub serwera docelowego. Więcej informacji znajdziesz w artykule Konfigurowanie protokołu TLS z serwera Edge do backendu.
Zastosowanie
Zasada JavaScript nie zawiera rzeczywistego kodu. Zamiast tego zasada JavaScript odwołuje się do „zasobu” JavaScriptu i określa krok w przepływie interfejsu API, w którym wykonuje się JavaScript. Możesz przesłać skrypt za pomocą edytora serwera proxy w interfejsie zarządzania lub dodać go do katalogu /resources/jsc
na serwerach proxy interfejsu API utworzonych lokalnie.
Debugowanie kodu zasady JavaScript
Użyj funkcji print(), aby wyeksportować informacje o debugowaniu do panelu danych wyjściowych transakcji w narzędziu do śledzenia. Informacje i przykłady znajdziesz w artykule Debugowanie za pomocą instrukcji print() w języku JavaScript.
Aby wyświetlić wyciągi drukowane w Trace:
- Otwórz narzędzie do śledzenia i rozpocznij sesję śledzenia dla serwera proxy z Twoją zasadą JavaScript.
- Wywołaj serwer proxy.
- W narzędziu do śledzenia kliknij Dane wyjściowe ze wszystkich transakcji, aby otworzyć panel wyników.
- W tym panelu pojawią się wyciągi drukowane.
Możesz użyć funkcjiprint(), aby przekazać dane debugowania do narzędzia do śledzenia. Ta funkcja jest dostępna bezpośrednio w modelu obiektowym JavaScript. Więcej informacji znajdziesz w artykule „Debugowanie JavaScriptu przy użyciu instrukcji print()”.
Zmienne przepływu
Ta zasada nie wypełni domyślnie żadnych zmiennych. Możesz jednak ustawić (i pobrać) zmienne przepływu w kodzie JavaScript, wywołując metody w obiekcie kontekstu. Typowy wzorzec wygląda tak:
context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))
Obiekt kontekstu jest częścią modelu obiektów JavaScript Apigee Edge.
Informacje o błędach
W tej sekcji opisujemy kody błędów i komunikaty o błędach, które są zwracane, a także zmienne błędów ustawiane przez Edge, gdy ta zasada aktywuje błąd. Te informacje są ważne, jeśli opracowujesz reguły dotyczące błędów do obsługi błędów. Więcej informacji znajdziesz w sekcjach Co musisz wiedzieć o błędach zasad i Postępowanie w przypadku błędów.
Błędy w czasie wykonywania
Te błędy mogą wystąpić podczas wykonywania zasady.
Kod błędu | Stan HTTP | Przyczyna | Napraw |
---|---|---|---|
steps.javascript.ScriptExecutionFailed |
500 | Zasada JavaScript może generować wiele różnych typów błędów ScriptExecutionFailed. Typowe typy błędów to RangeError, ReferenceError, SyntaxError, TypeError i URIError. | build |
steps.javascript.ScriptExecutionFailedLineNumber |
500 | W kodzie JavaScript wystąpił błąd. Szczegółowe informacje znajdziesz w ciągu błędu. | Nie dotyczy |
steps.javascript.ScriptSecurityError |
500 | Podczas wykonywania JavaScriptu wystąpił błąd zabezpieczeń. Szczegółowe informacje znajdziesz w ciągu znaków błędu. | Nie dotyczy |
Błędy wdrażania
Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego te zasady.
Nazwa błędu | Przyczyna | Napraw |
---|---|---|
InvalidResourceUrlFormat |
Jeśli format adresu URL zasobu określony w elemencie <ResourceURL> lub w elemencie <IncludeURL> zasady JavaScript jest nieprawidłowy, wdrożenie serwera proxy interfejsu API nie powiedzie się. |
build |
InvalidResourceUrlReference |
Jeśli elementy <ResourceURL> lub <IncludeURL> odwołują się do nieistniejącego pliku JavaScript, wdrożenie serwera proxy interfejsu API nie powiedzie się.
Przywoływany plik źródłowy musi istnieć na poziomie serwera proxy interfejsu API, środowiska lub organizacji. |
build |
WrongResourceType |
Ten błąd występuje podczas wdrażania, jeśli elementy <ResourceURL> lub <IncludeURL> zasady JavaScript odnoszą się do dowolnego typu zasobu innego niż jsc (plik JavaScript). |
build |
NoResourceURLOrSource |
Wdrożenie zasady JavaScript może się nie powieść, jeśli element <ResourceURL> nie został zadeklarowany lub w przypadku tego elementu nie został zdefiniowany adres URL zasobu.
<ResourceURL> to element obowiązkowy. Inną możliwością jest zadeklarowanie elementu <IncludeURL> , ale adres URL zasobu nie jest w nim zdefiniowany. Element <IncludeURL> jest opcjonalny, ale jeśli został zadeklarowany, adres URL zasobu musisz określić w elemencie <IncludeURL> . |
build |
Zmienne błędów
Te zmienne są ustawiane, gdy zasada wywołuje błąd w czasie działania. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z zasadami.
Zmienne | Gdzie | Przykład |
---|---|---|
fault.name="fault_name" |
fault_name to nazwa błędu podana w tabeli Błędy środowiska wykonawczego powyżej. Nazwa błędu to ostatnia część kodu. | fault.name Matches "ScriptExecutionFailed" |
javascript.policy_name.failed |
policy_name to określona przez użytkownika nazwa zasady, która spowodowała błąd. | javascript.JavaScript-1.failed = true |
Przykładowa odpowiedź na błąd
{ "fault": { "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"", "detail": { "errorcode": "steps.javascript.ScriptExecutionFailed" } } }
Przykładowa reguła błędu
<FaultRule name="JavaScript Policy Faults"> <Step> <Name>AM-CustomErrorResponse</Name> <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition> </Step> <Condition>(javascript.JavaScript-1.failed = true) </Condition> </FaultRule>
Schemat
Każdy typ zasady jest definiowany przez schemat XML (.xsd
). Schematy zasad są dostępne na GitHubie.
Powiązane artykuły
- Obiektowy model JavaScript
- Instrukcje, przykłady zasad i przykłady kodu JavaScript znajdziesz w artykule o serwerach proxy interfejsu Programming API z JavaScriptem.
Artykuły na temat społeczności Apigee
Zapoznaj się z tymi artykułami w społeczności Apigee: