Zasady dotyczące kodu JavaScript

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. .

  1. W interfejsie użytkownika Edge otwórz serwer proxy utworzony w edytorze proxy.
  2. Wybierz kartę Programowanie.
  3. W menu Nowy wybierz Nowy skrypt.
  4. W oknie wybierz JavaScript i nadaj skryptowi nazwę, np. js-example.
  5. 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ływu target.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);
    }
    
  6. W menu Nowa zasada wybierz JavaScript.
  7. Nazwij zasadę np. target-rewrite. Zaakceptuj wartości domyślne i zapisz zasadę.
  8. Jeśli w nawigatorze wybierzesz wstępne przetwarzanie punktu końcowego serwera proxy, zobaczysz, że zasada została dodana do tego procesu.
  9. W nawigatorze kliknij ikonę Target Endpoint PreFlow.
  10. Z nawigatora przeciągnij zasadę JavaScriptu w edytorze przepływu po stronie żądania, na docelowy punkt końcowy.
  11. Zapisz.
  12. 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: Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms.

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 name może zawierać litery, cyfry, spacje, łączniki, podkreślenia i kropki. Ta wartość nie może przekraczać 255 znaków.

Opcjonalnie możesz użyć elementu <DisplayName>, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną nazwą w języku naturalnym.

Nie dotyczy Wymagane
continueOnError

Ustaw wartość false, aby zwracać błąd w przypadku niepowodzenia zasady. Jest to normalne działanie większości zasad.

Ustaw jako true, aby wykonywanie przepływu było kontynuowane nawet po awarii zasady.

false Opcjonalnie
enabled

Ustaw jako true, aby wymuszać zasadę.

Ustaw wartość false, aby wyłączyć tę zasadę. Zasada nie będzie egzekwowana, nawet jeśli pozostanie dołączona do procesu.

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 name zasady.

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:

  1. Otwórz narzędzie do śledzenia i rozpocznij sesję śledzenia dla serwera proxy z Twoją zasadą JavaScript.
  2. Wywołaj serwer proxy.
  3. W narzędziu do śledzenia kliknij Dane wyjściowe ze wszystkich transakcji, aby otworzyć panel wyników.

  4. 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.
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ę.
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.
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).
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>.

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

Artykuły na temat społeczności Apigee

Zapoznaj się z tymi artykułami w społeczności Apigee: