JavaScript-Richtlinie

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

Was

Mit dieser Richtlinie können Sie benutzerdefinierten JavaScript-Code hinzufügen, der im Kontext eines API-Proxy-Ablauf ausgeführt wird. Sie können in Ihrem benutzerdefinierten JavaScript-Code die Objekte, Methoden und Attribute des JavaScript-Objektmodells von Apigee Edge verwenden. Mit dem Objektmodell können Sie Variablen im Kontext des Proxyablaufs abrufen, festlegen und entfernen. Sie können auch grundlegende kryptografische Funktionen verwenden, die mit dem Objektmodell bereitgestellt werden.

Info

Es gibt viele Anwendungsfälle für die JavaScript-Richtlinie. Sie können beispielsweise Flussvariablen abrufen und festlegen, benutzerdefinierte Logik ausführen und Fehler beheben, Daten aus Anfragen oder Antworten extrahieren, die Back-End-Ziel-URL dynamisch bearbeiten und vieles mehr. Mit dieser Richtlinie können Sie benutzerdefiniertes Verhalten implementieren, das von keiner anderen Edge-Standardrichtlinie abgedeckt ist. Tatsächlich können Sie eine JavaScript-Richtlinie verwenden, um das gleiche Verhalten zu erreichen, das von anderen Richtlinien implementiert wird, wie z. B. AssignMessage und ExtractVariable.

Ein Anwendungsfall, den wir für die JavaScript-Richtlinie nicht empfehlen, ist die Protokollierung. Die Message Logging-Richtlinie eignet sich viel besser für das Logging auf Logging-Plattformen von Drittanbietern wie Splunk, Sumo und Loggly. Sie können die API-Proxy-Leistung verbessern, indem Sie die Message Logging-Richtlinie in PostClientFlow ausführen nachdem die Antwort an den Client zurückgesendet wurde.

In der JavaScript-Richtlinie können Sie eine auszuführende JavaScript-Quelldatei angeben oder den JavaScript-Code direkt mit dem Element <Source> in die Konfiguration der Richtlinie einbinden. In beiden Fällen wird der JavaScript-Code ausgeführt, wenn der Schritt ausgeführt wird, an den die Richtlinie angehängt ist. Bei der Option der Quelldatei wird der Quellcode immer an einem Standardspeicherort im Proxy-Bundle gespeichert: apiproxy/resources/jsc. Sie können den Quellcode auch in einer Ressourcendatei auf der Umgebungsebene oder auf Organisationsebene speichern. Eine Anleitung dazu finden Sie unter Ressourcendateien. Sie können JavaScript auch über den Proxy-Editor der Apigee-Benutzeroberfläche hochladen.

JavaScript-Quelldateien müssen immer die Erweiterung .js haben.

Informationen zur derzeit unterstützten Version von JavaScript finden Sie unter Unterstützte Software und unterstützte Versionen.

Video

In einem kurzen Video erfahren Sie, wie Sie mithilfe der JavaScript-Richtlinie eine benutzerdefinierte Richtlinienerweiterung erstellen.

Samples

curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

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

Elementverweis

In der Elementreferenz werden die Elemente und Attribute der JavaScript-Richtlinie beschrieben.

<?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>-Attribute

<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

Die folgenden Attribute sind spezifisch für diese Richtlinie.

In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:

<DisplayName>-Element

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

<DisplayName>Policy Display Name</DisplayName>

<IncludeURL>-Element

Gibt eine JavaScript-Bibliotheksdatei an, die als Abhängigkeit der mit dem Element <ResourceURL> oder <Source> angegebenen JavaScript-Hauptdatei geladen werden soll. Die Skripts werden in der Reihenfolge ausgewertet, in der sie in der Richtlinie aufgeführt sind. Ihr Code kann die Objekte, Methoden und Attribute des JavaScript-Objektmodells verwenden.

Mehr als eine JavaScript-Abhängigkeitsressource mit zusätzlichen <IncludeURL>-Elementen hinzufügen.

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>

Beispiel

Sehen Sie sich das grundlegende Beispiel im Abschnitt Beispiele an.

<Property>-Element

Gibt ein Attribut an, das auf die Laufzeit vom JavaScript-Code aus zugegriffen werden kann.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

Attribute

Beispiel

Sehen Sie sich das Beispiel im Abschnitt Beispiele an.

<ResourceURL> -Element

Gibt die JavaScript-Hauptdatei an, die im API-Ablauf ausgeführt wird. Sie können diese Datei im API-Proxy-Bereich (unter /apiproxy/resources/jsc im API-Proxy-Bundle oder im Abschnitt "Skripts" im Navigationsbereich des API-Proxy-Editors) oder in den Organisations- oder Umgebungsbereichen zur Wiederverwendung in mehreren API-Proxys speichern unter Ressourcendateien beschrieben. Ihr Code kann die Objekte, Methoden und Eigenschaften des JavaScript-Objektmodells verwenden.

<ResourceURL>jsc://my-javascript.js</ResourceURL>

Beispiel

Sehen Sie sich das grundlegende Beispiel im Abschnitt Beispiele an.

<Source>-Element

Damit können Sie JavaScript direkt in die XML-Konfiguration der Richtlinie einfügen. Der eingefügte JavaScript-Code wird ausgeführt, wenn die Richtlinie im API-Ablauf ausgeführt wird.

Beispiel

<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

Gibt die Attribute an, die zum Konfigurieren von TLS für alle HTTP-Clientinstanzen verwendet werden, die von der JavaScript-Richtlinie erstellt werden.

    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>

Die Konfiguration von TLS für einen HTTP-Client entspricht der Vorgehensweise, mit der Sie TLS für einen TargetEndpoint/TargetServer konfigurieren. Weitere Informationen finden Sie unter TLS von Edge zum Back-End konfigurieren.

Hinweise zur Verwendung

Eine JavaScript-Richtlinie enthält keinen tatsächlichen Code. Stattdessen verweist eine JavaScript-Richtlinie auf eine JavaScript-Ressource und definiert den Schritt im API-Ablauf, in dem der JavaScript-Code ausgeführt wird. Sie können das Skript über den Proxy-Editor der Verwaltungs-UI hochladen oder es in das Verzeichnis /resources/jsc in API-Proxys einfügen, die Sie lokal entwickeln.

JavaScript-Richtliniencode debuggen

Mit der Funktion print() können Sie Debugging-Informationen an das Transaktionsausgabebereich des Trace ausgeben. Weitere Informationen und Beispiele finden Sie unter Debugging mit JavaScript-Anweisungen.

So rufen Sie Druckanweisungen in Trace auf:

1. Öffnen Sie das Trace-Tool und starten Sie eine Trace-Sitzung für einen Proxy, der Ihre JavaScript-Richtlinie enthält.
2. Rufen Sie den Proxy auf.
3. Klicken Sie im Trace-Tool auf Ausgabe aus allen Transaktionen, um das Ausgabefeld zu öffnen.

   

4. Ihre Druckberichte werden in diesem Feld angezeigt.

Sie können die Funktion print() verwenden, um Informationen zur Fehlerbehebung an das Trace-Tool zu senden. Diese Funktion ist direkt über das JavaScript-Objektmodell verfügbar. Weitere Informationen finden Sie unter "JavaScript mit print()-Anweisungen debuggen".

Ablaufvariablen

Diese Richtlinie füllt keine Variablen standardmäßig aus. Sie können jedoch Ablaufvariablen in Ihrem JavaScript-Code festlegen (und abrufen), indem Sie Methoden für das Kontextobjekt aufrufen. Ein typisches Muster sieht so aus:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))

Das Kontextobjekt ist Teil des JavaScript-Objektmodells von Apigee Edge.

Fehlerreferenz

In diesem Abschnitt werden die Fehlercodes und Fehlermeldungen beschrieben, die zurückgegeben werden, sowie die Fehlervariablen, die von Edge festgelegt werden, wenn diese Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy bereitstellen, der diese Richtlinie enthält.

Fehlervariablen

Diese Variablen werden festgelegt, wenn diese Richtlinie zur Laufzeit einen Fehler auslöst. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Beispiel für eine Fehlerantwort

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

Beispiel für eine Fehlerregel

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

Schema

Jeder Richtlinientyp wird durch ein XML-Schema (.xsd) definiert. Zu Referenzzwecken sind Richtlinienschemas auf GitHub verfügbar.

Weitere Informationen

• JavaScript-Objektmodell
• Eine Anleitung, Richtlinienbeispiele und JavaScript-Beispiele finden Sie unter API-Proxys mit JavaScript programmieren.

Apigee Community-Artikel

Sie finden diese entsprechenden Artikel in der Apigee Community:

• Weitere Informationen zum Umgang mit Headern mit mehreren Werten in JavaScript