JavaScript-Richtlinie

<ph type="x-smartling-placeholder"></ph> Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie 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. In Ihrem benutzerdefinierten JavaScript-Code können Sie die Objekte, Methoden und Eigenschaften von das JavaScript-Objektmodell von Apigee Edge. 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 Ablaufvariablen abrufen und festlegen, benutzerdefinierte Logik ausführen und Fehlerbehandlung durchführen, Daten aus Anfragen oder Antworten extrahieren, die Back-End-Ziel-URL dynamisch bearbeiten und vieles mehr. Mit dieser Richtlinie können Sie Implementieren von benutzerdefiniertem Verhalten, das nicht von anderen standardmäßigen Edge-Richtlinien abgedeckt wird. 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.

Beispiele

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

    <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. Siehe Konfigurieren von TLS von Edge zum Back-End .

Verwendungshinweise

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 Laden Sie Ihr Skript über den Proxy-Editor der Verwaltungsoberfläche hoch oder fügen Sie es in den Verzeichnis /resources/jsc in API-Proxys, 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 Output from transactions (Ausgabe von 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

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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