Przeglądasz dokumentację Apigee Edge.
Przejdź do
Dokumentacja Apigee X. informacje.
Co
Ta zasada pozwala dodawać niestandardowy kod JavaScript, który jest wykonywany w kontekście interfejsu API z serwera proxy. W niestandardowym kodzie JavaScript możesz używać obiektów, metod i właściwości modelu obiektów JavaScript Apigee Edge. Model obiektów umożliwia pobieranie, ustawianie i usuwanie w kontekście procesu proxy. Ty może też używać podstawowych funkcji kryptograficznych udostępnianych przez model obiektowy.
Informacje
Istnieje wiele przypadków użycia zasad JavaScript. Możesz na przykład pobrać i ustawić przepływ zmiennych, uruchamiać niestandardową logikę i usuwać błędy, wyodrębniać dane z żądań lub odpowiedzi, dynamicznej edycji docelowego adresu URL backendu i nie tylko. Ta zasada umożliwia: zaimplementować niestandardowe zachowanie, którego nie obejmują inne standardowe zasady Edge. Tak naprawdę mogą używać zasad JavaScriptu, aby osiągnąć podobny efekt za pomocą innych zasad np. AssignMessage i ExtractVariable.
Jednym z przypadków, których nie zalecamy w przypadku zasad JavaScriptu, jest logowanie. Zasada logowania wiadomości na potrzeby logowania na zewnętrznych platformach logowania, takich jak Splunk, Sumo czy Loggly, poprawia wydajność serwera proxy API przez uruchomienie zasad logowania komunikatów w PostClientFlow, który jest wykonywany po wysłaniu odpowiedzi do klienta.
Zasada JavaScript pozwala określić źródłowy plik JavaScript do wykonania lub
możesz umieścić kod JavaScript bezpośrednio w konfiguracji zasady za pomocą interfejsu <Source>
.
W obu przypadkach kod JavaScript jest wykonywany po wykonaniu kroku, do którego przyłączona jest zasada.
W przypadku opcji pliku źródłowego kod źródłowy jest zawsze przechowywany w
standardowa lokalizacja w pakiecie proxy: apiproxy/resources/jsc
. Możesz też
przechowywać kod źródłowy w pliku zasobów na poziomie środowiska lub organizacji. Dla:
instrukcji znajdziesz w artykule Pliki zasobów. Dostępne opcje
możesz też przesłać JavaScript za pomocą edytora serwera proxy interfejsu Apigee.
Źródłowe pliki JavaScript muszą zawsze mieć rozszerzenie .js
.
Zobacz Obsługiwane oprogramowanie i obsługiwane wersje dla obecnie obsługiwanej wersji JavaScriptu.
Wideo
Obejrzyj krótki film, aby dowiedzieć się, jak utworzyć niestandardowe rozszerzenie zasad za pomocą JavaScriptu .
Przykłady
Ponownie zapisz docelowy adres URL
Typowy przypadek użycia: wyodrębnianie danych z treści żądania i przechowywanie ich w przepływie i używać jej w innym miejscu procesu proxy. Załóżmy, że masz aplikację w którym użytkownik wpisuje swoje imię i nazwisko w formularzu HTML i przesyła je. Serwer proxy interfejsu API ma wyodrębniania danych formularza i dynamicznego dodawania ich do adresu URL używanego do wywoływania usługi backendu. Jak czy to w zasadach JavsScriptu?
Uwaga: jeśli chcesz wypróbować ten przykład, zakładamy, że masz już utworzoną nową w edytorze proxy. Gdy ją utworzysz, nadaj jej adres URL usługi backendu: http://www.example.com W tym przykładzie zmienimy dynamicznie URL backendu. Jeśli nie wiesz, jak utworzyć nowy serwer proxy, skorzystaj z samouczka dla początkujących. .
- W interfejsie Edge otwórz serwer proxy utworzony w edytorze proxy.
- Kliknij kartę Develop.
- W menu Nowy wybierz Nowy skrypt.
- W oknie wybierz JavaScript i nadaj skryptowi nazwę,
js-example
- Wklej ten kod w edytorze kodu i zapisz serwer proxy. Ważne jest, aby
jest obiekt
context
. Ten obiekt jest dostępny dla kodu JavaScript w dowolnym miejscu procesu proxy. Służy do uzyskiwania stałych stałych dla przepływu get/set (metody get/set) oraz więcej operacji. Ta część obiektu należy do Edge Obiektowy model JavaScript. Uwaga: , że zmienna przepływutarget.url
jest wbudowaną zmienną odczytu/zapisu, która jest dostępny w przepływie żądania docelowego. Gdy ustawisz tę zmienną za pomocą adresu URL interfejsu API, Edge wysyła wywołanie backendu do tego adresu URL. Zasadniczo zmieniliśmy pierwotny docelowy URL, czyli elementy określone 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 Nowe zasady wybierz JavaScript.
- Nazwij zasadę, na przykład
target-rewrite
. Zaakceptuj ustawienia domyślne i zapisz ustawienia zasady. - Jeśli w Nawigatorze wybierzesz ustawienie wstępne punktu końcowego serwera proxy, zasada został dodany do tego procesu.
- W nawigatorze kliknij ikonę Target Endpoint PreFlow.
- Z Nawigatora przeciągnij zasadę JavaScript na stronę żądania Punkt końcowy w edytorze przepływu.
- Zapisz.
- Wywołaj ten interfejs API, zastępując poprawną nazwę organizacji i nazwę serwera proxy odpowiednie:
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 zasad JavaScript używanych w
w tym przykładzie. Ważne jest, aby pamiętać, że <ResourceURL>
jest używany do określania źródłowego pliku JavaScript do wykonania. Ten sam wzór jest używany
dla dowolnego pliku źródłowego JavaScript: jsc://filename.js
. Jeśli używasz kodu JavaScript
wymaga uwzględnienia, możesz użyć co najmniej 1 elementu <IncludeURL>
jak to opisano w dalszej części tego artykułu.
<?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 potem pobrać
za pomocą JavaScriptu w czasie działania.
Użyj atrybutu name
elementu, aby określić nazwę służącą do uzyskiwania dostępu do elementu
z kodu JavaScript. Wartość elementu <Property>
(wartość
między tagiem otwierającym i zamykającym) to wartość literału, która zostanie odebrana
JavaScriptu.
W JavaScripcie wartość właściwości zasady pobiera się, uzyskując do niej dostęp jako właściwość
Properties
jak poniżej:
- 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. Tutaj pobrana wartość – nazwa zmiennej –
jest następnie używany 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óre można wykorzystać Objaśnienie JavaScript, patrz tego posta w społeczności Apigee. Sugestie oferowane przez społeczność Apigee dotyczą mają wyłącznie informacje i nie muszą być zgodne ze sprawdzonymi metodami zalecanymi przez Apigee.
Odwołanie do elementu
Dokumentacja elementu opisuje elementy i atrybuty zasad 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>
<Javascript> Atrybuty
<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">
Poniższe atrybuty są charakterystyczne dla tej zasady.
Atrybut | Opis | Domyślny | Obecność |
---|---|---|---|
timeLimit |
Określa maksymalny czas (w milisekundach), jaki skrypt może wykonywać
. Jeśli np. zostanie przekroczony limit 200 ms, zasada zgłasza ten błąd:
Uwaga: w przypadku bezpłatnych kont próbnych czas wykonania jest ograniczony do 200. ms |
Nie dotyczy | Wymagane |
W tej tabeli opisano atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:
Atrybut | Opis | Domyślny | Obecność |
---|---|---|---|
name |
Wewnętrzna nazwa zasady. Wartość atrybutu Opcjonalnie możesz użyć elementu |
Nie dotyczy | Wymagane |
continueOnError |
Ustaw jako Ustaw jako |
fałsz | Opcjonalnie |
enabled |
Aby egzekwować zasadę, ustaw wartość Aby wyłączyć zasadę, ustaw wartość |
prawda | Opcjonalnie |
async |
Ten atrybut został wycofany. |
fałsz | Wycofano |
<DisplayName> element
Używaj oprócz atrybutu name
do oznaczania zasady w
edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.
<DisplayName>Policy Display Name</DisplayName>
Domyślny |
Nie dotyczy Jeśli pominiesz ten element, atrybut |
---|---|
Obecność | Opcjonalnie |
Typ | Ciąg znaków |
<IncludeURL> element
Określa plik biblioteki JavaScript, który ma być wczytywany jako zależność od głównego pliku JavaScript
określona za pomocą elementu <ResourceURL>
lub <Source>
. Skrypty zostaną ocenione w
w takiej kolejności, w jakiej są wymienione w zasadach. W kodzie możesz używać obiektów, metod
właściwości obiektowego modelu JavaScript.
Uwzględnij więcej niż jeden zasób zależności JavaScript oraz dodatkowe
<IncludeURL>
elementów.
<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>
Domyślne: | Brak |
Obecność: | Opcjonalnie |
Typ: | Ciąg znaków |
Przykład
Przykład podstawowy znajdziesz w sekcji Sample.
<Property> element
Wskazuje właściwość, do której masz dostęp z kodu JavaScript w czasie działania.
<Properties> <Property name="propName">propertyValue</Property> </Properties>
Domyślne: | Brak |
Obecność: | Opcjonalnie |
Typ: | Ciąg znaków |
Atrybuty
Atrybut | Opis | Domyślny | Obecność |
---|---|---|---|
nazwa |
Określa nazwę właściwości. |
Nie dotyczy | Wymagane. |
Przykład
Przykład znajdziesz w sekcji Sample.
<ResourceURL> element
Określa główny plik JavaScript, który zostanie uruchomiony w przepływie interfejsu API. Możesz zapisać ten plik
w zakresie serwera proxy interfejsu API (w sekcji /apiproxy/resources/jsc
w pakiecie proxy API lub w
sekcji Skrypty w panelu Nawigator edytora serwera proxy interfejsu API) albo w organizacji lub
zakresy środowiskowe do ponownego wykorzystania na wielu serwerach proxy interfejsu API, zgodnie z opisem w artykule Pliki zasobów. Twój kod może używać obiektów,
i metodach obiektowego modelu JavaScript.
<ResourceURL>jsc://my-javascript.js</ResourceURL>
Domyślne: | Brak |
Obecność: | Wymagana jest wartość <ResourceURL> lub <Source> . Jeśli
Zarówno <ResourceURL> , jak i <Source> są obecne, <ResourceURL> jest ignorowane. |
Typ: | Ciąg znaków |
Przykład
Przykład podstawowy znajdziesz w sekcji Sample.
<Source> element
Umożliwia wstawienie kodu JavaScript bezpośrednio do konfiguracji XML zasady. Wstawione Kod JavaScript jest wykonywany, gdy zasada jest wykonywana w przepływie interfejsu API.
Domyślne: | Brak |
Obecność: | Wymagana jest wartość <ResourceURL> lub <Source> . Jeśli
Zarówno <ResourceURL> , jak i <Source> są obecne, <ResourceURL> jest ignorowane. |
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>
<SSLInfo> element
Określa właściwości używane do konfigurowania TLS we wszystkich instancjach klienta HTTP utworzonych przez zasady JavaScript.
<SSLInfo> <Enabled>trueFalse</Enabled> <ClientAuthEnabled>trueFalse</ClientAuthEnabled> <KeyStore>ref://keystoreRef</KeyStore> <KeyAlias>keyAlias</KeyAlias> <TrustStore>ref://truststoreRef</TrustStore> </SSLInfo>
Domyślne: | Brak |
Obecność: | Opcjonalnie |
Typ: | Ciąg znaków |
Proces konfigurowania protokołu TLS w przypadku klienta HTTP jest taki sam jak w przypadku konfigurowania Protokół TLS dla punktu końcowego lub serwera docelowego. Zobacz Konfigurowanie TLS z Edge do backendu. .
Zastosowanie
Zasada JavaScript nie zawiera rzeczywistego kodu. Zamiast tego zasada JavaScript odwołuje się do
„zasób” JavaScriptu i definiuje krok w przepływie interfejsu API, w którym wykonuje się JavaScript. Dostępne opcje
prześlij skrypt za pomocą edytora serwera proxy interfejsu zarządzania, ale możesz go też umieścić w
Katalog /resources/jsc
na serwerach proxy interfejsu API, które tworzysz lokalnie.
Debugowanie kodu zasad JavaScript
Użyj funkcji print(), by wysłać informacje o debugowaniu transakcji. panelu wyjściowego w narzędziu Trace. Szczegółowe informacje i przykłady znajdziesz w artykule Debugowanie z użyciem JavaScriptu print().
Aby wyświetlić instrukcje wydruku w Trace:
- Otwórz narzędzie Trace i rozpocznij sesję śledzenia dla serwera proxy zawierającego Twój JavaScript .
- Wywołaj serwer proxy.
- W narzędziu do śledzenia kliknij Wyniki ze wszystkich transakcji, aby wyświetlić dane wyjściowe. panel.
- W tym panelu pojawią się oświadczenia dotyczące drukowania.
Możesz użyć funkcji Print(), aby wyświetlić w narzędziu do śledzenia informacje o debugowaniu. Ta funkcja jest dostępna bezpośrednio za pomocą obiektowego modelu JavaScript. Aby dowiedzieć się więcej, zapoznaj się z sekcją „Debugowanie JavaScriptu za pomocą funkcji Print()” wyciągi”.
Zmienne przepływu
Ta zasada domyślnie nie uzupełnia żadnych zmiennych. możesz jednak ustawić (i uzyskać) przepływ, w kodzie JavaScript przez wywołanie metod w obiekcie kontekstu. Typowy wzór 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łędzie
W tej sekcji opisano zwracane kody błędów i komunikaty o błędach oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wywołuje błąd. To ważna informacja jeśli tworzysz reguły błędów obsługi błędów. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z zasadami i postępowaniu z błędami
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. Powszechnie widoczne typy błędów to RangeError, ReferenceError, SyntaxError, TypeError oraz URIError. | build |
steps.javascript.ScriptExecutionFailedLineNumber |
500 | Wystąpił błąd w kodzie JavaScript. Szczegóły znajdziesz w ciągu znaków z błędem. | Nie dotyczy |
steps.javascript.ScriptSecurityError |
500 | Podczas wykonywania skryptu JavaScript wystąpił błąd zabezpieczeń. Zobacz ciąg błędu dla . | Nie dotyczy |
Błędy wdrażania
Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego tę zasadę.
Nazwa błędu | Przyczyna | Napraw |
---|---|---|
InvalidResourceUrlFormat |
Jeśli format adresu URL zasobu określony w elemencie <ResourceURL> lub <IncludeURL> zasady JavaScript jest nieprawidłowy, wdrożenie serwera proxy interfejsu API się nie uda. |
build |
InvalidResourceUrlReference |
Jeśli elementy <ResourceURL> lub <IncludeURL>
do pliku JavaScript, który nie istnieje, wdrożenie serwera proxy interfejsu API się nie uda.
Wskazany 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 <ResourceURL> lub <IncludeURL>
elementy zasady JavaScript odwołują się do dowolnego typu zasobu innego niż jsc (plik JavaScript). |
build |
NoResourceURLOrSource |
Wdrożenie zasady JavaScript może się nie udać z tym błędem, jeśli <ResourceURL>
element nie jest zadeklarowany lub adres URL zasobu nie jest zdefiniowany w tym elemencie.
Element <ResourceURL> jest wymaganym elementem. lub element <IncludeURL> jest zadeklarowany.
ale URL zasobu nie jest zdefiniowany w tym elemencie. Element <IncludeURL> jest opcjonalny.
ale jeśli zadeklarowano, URL zasobu musi być określony w elemencie <IncludeURL> . |
build |
Zmienne błędów
Te zmienne są ustawiane, gdy ta zasada wywołuje błąd w czasie działania. Aby dowiedzieć się więcej, zapoznaj się z artykułem Co musisz wiedzieć o błędach związanych z naruszeniem zasad.
Zmienne | Gdzie | Przykład |
---|---|---|
fault.name="fault_name" |
fault_name to nazwa błędu podana w tabeli Błędy czasu działania powyżej. Nazwa błędu to ostatnia część kodu błędu. | 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 zasad 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 JavaScriptu znajdziesz na stronie Programming API i serwery proxy z JavaScriptem.
Artykuły społeczności Apigee
Te powiązane artykuły znajdziesz w Apigee Społeczność: