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

Co
Ta zasada umożliwia dodanie niestandardowego kodu JavaScriptu, który będzie wykonywany w kontekście przepływu pracy przez serwer proxy interfejsu API. W niestandardowym kodzie JavaScript możesz używać obiektów, metod i właściwości modelu JavaScript Apigee Edge. Model obiektu umożliwia pobieranie, ustawianie i usuwanie zmiennych w kontekście przepływu proxy. Możesz też używać podstawowych funkcji kryptograficznych dostępnych w modelu obiektu.
Informacje
Zasady JavaScript mają wiele zastosowań. Możesz na przykład pobierać i ustawiać zmienne przepływu, uruchamiać niestandardowe funkcje logiczne i obsługiwać błędy, wyodrębniać dane z żądań lub odpowiedzi, dynamicznie edytować docelowy adres URL backendu i nie tylko. Ta zasada pozwala wdrożyć niestandardowe zachowanie, które nie jest objęte innymi standardowymi zasadami Edge. Właściwie możesz użyć zasady JavaScript, aby osiągnąć wiele takich samych zachowań, które są zaimplementowane w innych zasadach, takich jak przypisywanie wiadomości i wyodrębnianie zmiennej.
Jednym z przypadków użycia, którego nie zalecamy w przypadku zasady dotyczącej języka JavaScript, jest rejestrowanie. Zasada logowania wiadomości o wiele lepiej nadaje się do logowania na zewnętrzne platformy logowania, takie jak Splunk, Sumo i Loggly, oraz zwiększa wydajność serwera proxy interfejsu API przez wykonanie zasady Message Logging w PostClientFlow, która jest wykonywana po wysłaniu odpowiedzi do klienta.
Zasada JavaScript umożliwia określenie pliku źródłowego JavaScriptu. Możesz też umieścić kod JavaScript bezpośrednio w konfiguracji zasady za pomocą elementu <Source>
.
W obu przypadkach kod JavaScript jest uruchamiany w trakcie wykonywania kroku, do którego jest dołączona zasada.
W przypadku pliku źródłowego kod źródłowy jest zawsze przechowywany w standardowej lokalizacji w pakiecie pakietów serwera proxy: apiproxy/resources/jsc
. Możesz też przechowywać 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ć kod JavaScript za pomocą edytora proxy interfejsu Apigee UI.
Pliki źródłowe JavaScript muszą zawsze mieć rozszerzenie .js
.
W artykule Obsługiwane oprogramowanie i obsługiwane wersje znajdziesz obecną wersję JavaScriptu.
Wideo
Obejrzyj krótki film, aby dowiedzieć się, jak utworzyć niestandardowe rozszerzenie zasad przy użyciu zasady JavaScript.
Sample
Przepisanie docelowego adresu URL
Oto 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 w procesie proxy. Załóżmy, że masz aplikację, w której użytkownik wpisuje swoje imię i nazwisko w formularzu HTML i przesyła ją. Chcesz, aby serwer proxy interfejsu API wyodrębnił dane formularza i dynamicznie dodał je do adresu URL służącego do wywoływania usługi backendu. Jak można 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 URL-a backendu wybierz adres 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ę Develop.
- W menu New (Nowy) wybierz New Script (Nowy skrypt).
- W oknie wybierz JavaScript i nadaj skryptowi nazwę, np.
js-example
. - Wklej ten kod w edytorze kodu i zapisz serwer proxy. Warto zwrócić uwagę na obiekt
context
. Ten obiekt jest dostępny dla kodu JavaScript w dowolnym miejscu w procesie proxy. Służy do uzyskiwania stałych związanych z przepływem, wywoływania przydatnych metod get/set i większej liczby operacji. Ta część obiektu należy do modelu obiektu JavaScript Edge. Pamiętaj też, że zmienna przepływutarget.url
to wbudowana zmienna do odczytu i zapisu, dostępna w ramach przepływu żądania docelowego. Gdy ustawisz tę zmienną za pomocą adresu URL interfejsu API, Edge wywoła jej backend. Zasadniczo przepisaliśmy pierwotny docelowy URL, który został określony przez Ciebie 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.
- Nadaj zasadzie nazwę, np.
target-rewrite
. Zaakceptuj wartości domyślne i zapisz zasady. - Jeśli wybierzesz Nawigator punktów końcowych serwera proxy, zobaczysz, że zasada została dodana do tego procesu.
- W Nawigatorze kliknij ikonę Target Prenlow PreFlow (Docelowy punkt końcowy punktu końcowego).
- W Nawigatorze przeciągnij zasadę JavaScript po stronie żądania docelowego punktu końcowego w edytorze przepływu.
- Zapisz.
- Wywołuj interfejs API tak:
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example
Na koniec przyjrzymy się definicji XML dla zasady JavaScriptu użytej w tym przykładzie. Pamiętaj, że element <ResourceURL>
jest używany do określenia pliku źródłowego JavaScriptu do wykonania. Ten sam wzorzec jest używany w przypadku dowolnego pliku źródłowego JavaScript: jsc://filename.js
. Jeśli musisz uwzględnić kod JavaScript, możesz w tym celu użyć co najmniej 1 elementu <IncludeURL>
, jak opisano to 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 następnie pobierać jego wartość przy użyciu kodu JavaScript w czasie działania.
Użyj atrybutu name
elementu, aby określić nazwę dostępu do właściwości z kodu JavaScript. Wartość elementu <Property>
(wartość między otwierającym a zamykającym tagiem) to wartość literału, którą otrzyma kod JavaScript.
W kodzie JavaScript wartość właściwości zasady pobierzesz, uzyskując do niej dostęp jako właściwość obiektu Properties
w ten sposób:
- Skonfiguruj usługę. W tym miejscu 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ą kodu JavaScript. Pobierana wartość – nazwa zmiennej – jest następnie używana przez funkcję
getVariable
do pobierania 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 technik obsługi błędów, które możesz wykorzystać w wywołaniu JavaScript, znajdziesz w tym poście na forum Apigee. Propozycje dostępne w społeczności Apigee mają charakter informacyjny i niekoniecznie reprezentują sprawdzone metody polecane przez Apigee.
Dokumentacja 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>
Atrybuty <Javascript>
<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">
Poniższe atrybuty dotyczą tej zasady.
Atrybut | Opis | Domyślna | Obecność |
---|---|---|---|
limit czasu |
Określa maksymalny czas (w milisekundach), przez jaki skrypt może wykonać skrypt. Jeśli na przykład limit 200 ms jest przekroczony, zasada zwraca ten błąd: Uwaga: w przypadku bezpłatnych kont próbnych czas wykonywania jest ograniczony do 200 ms. |
Nie dotyczy | Wymagany |
Tabela poniżej opisuje atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:
Atrybut | Opis | Domyślnie | Obecność |
---|---|---|---|
name |
Wewnętrzna nazwa zasady. Wartość atrybutu Opcjonalnie użyj elementu |
Nie dotyczy | Wymagany |
continueOnError |
Ustaw wartość Ustaw wartość |
fałsz | Opcjonalnie |
enabled |
Ustaw jako Ustaw zasadę |
prawda | Opcjonalnie |
async |
Ten atrybut został wycofany. |
fałsz | Wycofano |
Element <DisplayName>
Używaj atrybutu name
tak, aby oznaczyć zasadę w edytorze proxy interfejsu zarządzania inną nazwą w języku naturalnym.
<DisplayName>Policy Display Name</DisplayName>
Domyślnie |
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ą sprawdzane w kolejności, w której są wymienione w zasadzie. Kod może korzystać z obiektów, metod i właściwości modelu JavaScriptu.
Uwzględnij więcej niż jeden zasób zależności JavaScript z dodatkowymi elementami <IncludeURL>
.
<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>
Domyślne: | Brak |
Obecność: | Opcjonalnie |
Typ: | Ciąg znaków |
Przykład
Zobacz podstawowy przykład w sekcji Przykłady.
Element <Property>
Określa właściwość, do której możesz uzyskać 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ślna | Obecność |
---|---|---|---|
nazwa |
Określa nazwę właściwości. |
Nie dotyczy | Wymagany. |
Przykład
Zobacz ten przykład w sekcji Przykłady.
Element <ResourceURL>
Określa główny plik JavaScript, który będzie wykonywany w ramach interfejsu API. Możesz przechowywać ten plik w zakresie serwera proxy interfejsu API (w sekcji /apiproxy/resources/jsc
w pakiecie proxy interfejsu API, w sekcji Skrypty w panelu nawigatora proxy interfejsu API) albo w zakresie organizacji lub środowiska do ponownego użycia na wielu serwerach proxy interfejsu API zgodnie z opisem w plikach zasobów. Kod może korzystać z obiektów, metod i właściwości modelu JavaScriptu.
<ResourceURL>jsc://my-javascript.js</ResourceURL>
Domyślne: | Brak |
Obecność: | Wymagana jest właściwość <ResourceURL> lub <Source> . Jeśli <ResourceURL> i <Source> są obecne, <ResourceURL> jest ignorowany. |
Typ: | Ciąg znaków |
Przykład
Zobacz podstawowy przykład w sekcji Przykłady.
Element <Source>
Umożliwia wstawianie kodu JavaScript bezpośrednio do konfiguracji XML zasady. Wstawiony kod JavaScript jest wywoływany, gdy zasada wykonuje się podczas przepływu API.
Domyślne: | Brak |
Obecność: | Wymagana jest właściwość <ResourceURL> lub <Source> . Jeśli <ResourceURL> i <Source> są obecne, <ResourceURL> jest ignorowany. |
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 służące do konfigurowania TLS we wszystkich instancjach klienta HTTP utworzonych przez zasadę 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 dla klienta HTTP to ten sam proces, który służy do konfigurowania protokołu TLS dla serwera docelowego/serwera docelowego. Więcej informacji znajdziesz w sekcji Konfigurowanie TLS z Edge do backendu.
Zastosowanie
Zasada JavaScript nie zawiera rzeczywistego kodu. Zasada JavaScript odwołuje się do „zasobu” JavaScriptu i definiuje krok w jego trakcie, gdzie wykonywany jest kod JavaScript. Skrypt możesz przesłać za pomocą edytora proxy interfejsu zarządzania, ale możesz też umieścić go w katalogu /resources/jsc
na serwerach proxy interfejsu API, które tworzysz lokalnie.
Debugowanie kodu zasad JavaScript
Użyj funkcji print(), aby wyświetlać dane debugowania w panelu wyników transakcji w narzędziu śledzenia. Szczegółowe informacje i przykłady znajdziesz w instrukcji Debug with JavaScript print().
Aby wyświetlić wyciągi drukowane w Trace:
- Otwórz narzędzie śledzenia i rozpocznij sesję śledzenia dla serwera proxy, który zawiera zasadę JavaScript.
- Wywołaj serwer proxy.
- W narzędziu śledzenia kliknij Wyniki ze wszystkich transakcji, aby otworzyć panel wyjściowy.
- Wyciągi drukowane pojawią się w tym panelu.
Możesz użyć funkcjiprint(), by przesłać dane debugowania do narzędzia śledzenia. Ta funkcja jest dostępna bezpośrednio przez model obiektu JavaScript. Więcej informacji znajdziesz w sekcji Debugowanie JavaScript za pomocą instrukcji instrukcji()().
Zmienne przepływu
Ta zasada domyślnie nie uzupełnia żadnych zmiennych. Możesz jednak ustawiać (i pobierać) 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 kontekstowy jest częścią modelu obiektu JavaScript Apigee Edge.
Dokumentacja błędu
W tej sekcji opisano kody błędów i zwracane komunikaty o błędach, które są zmieniane przez Edge po wywołaniu tej zasady. Ta informacja jest ważna, gdy opracowujesz reguły obsługi błędów. Więcej informacji znajdziesz w artykułach Co musisz wiedzieć o błędach zasad i Obsługa 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 zwracać wiele różnych typów błędów ScriptExecutionFailed. Do najczęściej występujących typów błędów należą RangeError, ReferenceError, SkładniaError, TypeError i URIError. | build |
steps.javascript.ScriptExecutionFailedLineNumber |
500 | W kodzie JavaScript wystąpił błąd. Aby dowiedzieć się więcej, sprawdź ciąg błędu. | Nie dotyczy |
steps.javascript.ScriptSecurityError |
500 | Podczas wykonywania kodu JavaScript wystąpił błąd zabezpieczeń. Więcej informacji znajdziesz w tekście błędu. | Nie dotyczy |
Błędy wdrażania
Te błędy mogą wystąpić, gdy wdrażasz serwer proxy zawierający tę zasadę.
Nazwa błędu | Przyczyna | Napraw |
---|---|---|
InvalidResourceUrlFormat |
Jeśli format adresu URL zasobu określony w elemencie <ResourceURL> lub <IncludeURL> w zasadzie 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ę.
Wskazany plik źródłowy musi istnieć na poziomie serwera proxy, środowiska lub organizacji. |
build |
WrongResourceType |
Ten błąd występuje podczas wdrażania, jeśli elementy <ResourceURL> lub <IncludeURL> w zasadach JavaScript odwołują się do innych typów zasobów niż jsc (plik JavaScript). |
build |
NoResourceURLOrSource |
Wdrożenie zasady JavaScript może się nie powieść w przypadku tego błędu, jeśli nie zadeklarowano elementu <ResourceURL> lub w tym elemencie nie określono adresu URL zasobu.
Element <ResourceURL> jest wymagany. Albo element <IncludeURL> jest zadeklarowany, ale nie określono w nim adresu URL zasobu. Element <IncludeURL> jest opcjonalny, ale jeśli zostanie zadeklarowany, adres URL zasobu musi być określony w elemencie <IncludeURL> . |
build |
Zmienne błędów
Zmienne te są ustawiane, gdy ta zasada powoduje błąd w czasie działania. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach zasad.
Zmienne | Gdzie | Przykład |
---|---|---|
fault.name="fault_name" |
fault_name to nazwa błędu, zgodnie z tabelą Błędy środowiska wykonawczego. Nazwa błędu jest ostatnią częścią 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 awarii
<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 zdefiniowany za pomocą schematu XML (.xsd
). Informacje o schematach zasad są dostępne na GitHubie.
Powiązane artykuły
- Model obiektu JavaScript
- Instrukcje, przykłady zasad i przykłady JavaScript znajdziesz w artykule Programowanie serwerów proxy interfejsu API za pomocą JavaScriptu.
Artykuły dotyczące społeczności Apigee
Więcej powiązanych artykułów znajdziesz na stronie społeczności Apigee: