Zasady dotyczące kodu JavaScript

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

  1. W interfejsie Edge otwórz serwer proxy utworzony w edytorze proxy.
  2. Kliknij kartę Develop.
  3. W menu Nowy wybierz Nowy skrypt.
  4. W oknie wybierz JavaScript i nadaj skryptowi nazwę, js-example
  5. 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ływu target.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);
    }
    
  6. W menu Nowe zasady wybierz JavaScript.
  7. Nazwij zasadę, na przykład target-rewrite. Zaakceptuj ustawienia domyślne i zapisz ustawienia zasady.
  8. Jeśli w Nawigatorze wybierzesz ustawienie wstępne punktu końcowego serwera proxy, zasada został dodany do tego procesu.
  9. W nawigatorze kliknij ikonę Target Endpoint PreFlow.
  10. Z Nawigatora przeciągnij zasadę JavaScript na stronę żądania Punkt końcowy w edytorze przepływu.
  11. Zapisz.
  12. 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>

&lt;Javascript&gt; 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: 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

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 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> do oznaczenia zasady jako edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

Nie dotyczy Wymagane
continueOnError

Ustaw jako false, aby w przypadku niepowodzenia zasady zwracany był błąd. To normalne w przypadku większości zasad.

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

fałsz Opcjonalnie
enabled

Aby egzekwować zasadę, ustaw wartość true.

Aby wyłączyć zasadę, ustaw wartość false. Te zasady nie będą jest wymuszane nawet wtedy, gdy jest ono połączone z przepływem.

prawda Opcjonalnie
async

Ten atrybut został wycofany.

fałsz Wycofano

&lt;DisplayName&gt; 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 name zasady otrzyma wartość .

Obecność Opcjonalnie
Typ Ciąg znaków

&lt;IncludeURL&gt; 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.

&lt;Property&gt; 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.

&lt;ResourceURL&gt; 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.

&lt;Source&gt; 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>

&lt;SSLInfo&gt; 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:

  1. Otwórz narzędzie Trace i rozpocznij sesję śledzenia dla serwera proxy zawierającego Twój JavaScript .
  2. Wywołaj serwer proxy.
  3. W narzędziu do śledzenia kliknij Wyniki ze wszystkich transakcji, aby wyświetlić dane wyjściowe. panel.

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

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

Artykuły społeczności Apigee

Te powiązane artykuły znajdziesz w Apigee Społeczność: