Zasady dotyczące kodu JavaScript

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

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

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

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

Nie dotyczy Wymagany
continueOnError

Ustaw wartość false, aby wyświetlać błąd, gdy zasada nie działa. To prawidłowy proces w przypadku większości zasad.

Ustaw wartość true, aby kontynuować wykonywanie przepływu nawet po naruszeniu zasady.

fałsz Opcjonalnie
enabled

Ustaw jako true, aby egzekwować zasadę.

Ustaw zasadę false, aby wyłączyć tę zasadę. Zasada nie będzie egzekwowana, nawet jeśli pozostanie powiązana z przepływem.

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 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ą 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:

  1. Otwórz narzędzie śledzenia i rozpocznij sesję śledzenia dla serwera proxy, który zawiera zasadę JavaScript.
  2. Wywołaj serwer proxy.
  3. W narzędziu śledzenia kliknij Wyniki ze wszystkich transakcji, aby otworzyć panel wyjściowy.

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

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

Artykuły dotyczące społeczności Apigee

Więcej powiązanych artykułów znajdziesz na stronie społeczności Apigee: