JavaScript-Richtlinie

Erweiterbare Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Mit der JavaScript-Richtlinie können Sie benutzerdefinierten JavaScript-Code hinzufügen, der im Kontext des API-Proxy-Ablaufs ausgeführt wird. Mit dieser Richtlinie können Sie benutzerdefiniertes Verhalten implementieren, das nicht durch andere Apigee-Richtlinien abgedeckt ist.

In Ihrem benutzerdefinierten JavaScript-Code können Sie die Objekte, Methoden und Eigenschaften des JavaScript-Objektmodells von Apigee verwenden. Sie können Variablen im Proxy-Ablaufkontext abrufen, festlegen und entfernen, benutzerdefinierte Logik ausführen, Fehlerbehandlung durchführen, Daten aus Anfragen oder Antworten extrahieren und die Back-End-Ziel-URL dynamisch bearbeiten. Sie können auch grundlegende kryptografische Funktionen verwenden, die im Objektmodell verfügbar sind.

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 die Erweiterung .js haben. Apigee unterstützt JavaScript, das auf der Rhino JavaScript-Engine 1.7.13 ausgeführt wird.

Apigee empfiehlt die Verwendung der JavaScript-Richtlinie für Folgendes nicht:

  • Logging: Die MessageLogging-Richtlinie eignet sich besser für die Protokollierung mit Protokollierungsplattformen von Drittanbietern wie Splunk, Sumo und Loggly. Diese Richtlinie verbessert auch die Leistung von API-Proxy, da sie im PostClientFlow ausgeführt wird, nachdem die Antwort an den Client zurückgegeben wurde.
  • Apigee-Richtlinien ersetzen Die JavaScript-Richtlinie ersetzt nicht die Funktionen von Apigee-Richtlinien. Wenn die benötigten Funktionen in einer Apigee-Richtlinie verfügbar sind, verwenden Sie diese Richtlinie anstelle einer benutzerdefinierten JavaScript-Lösung. Benutzerdefinierter JavaScript-Code entspricht möglicherweise nicht der Leistung und Optimierung von Apigee-Richtlinien.
  • Systemaufrufe auszuführen. Das Sicherheitsmodell lässt keine Systemaufrufe über die JavaScript-Richtlinie zu. Beispiele: Das interne Dateisystem liest oder schreibt aktuelle Nutzerinformationen, Prozesslisten oder die CPU-/Speicherauslastung. Auch wenn einige Anrufe funktional sein können, werden sie nicht unterstützt und können jederzeit deaktiviert werden. Aus Gründen der Aufwärtskompatibilität sollten Sie solche Aufrufe im Code vermeiden.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Beispiele

Geben Sie die Ziel-URL ein

Ein häufiger Anwendungsfall ist das Extrahieren von Daten aus einem Anfragetext, das Speichern der Daten in einer Ablaufvariablen und die Verwendung dieser Ablaufvariablen an anderer Stelle im Proxyablauf. Angenommen, ein Nutzer gibt seinen Namen in ein HTML-Formular ein und sendet es. Verwenden Sie eine JavaScript-Richtlinie, um die Formulardaten zu extrahieren und der Back-End-Dienst-URL dynamisch hinzuzufügen.

  1. Öffnen Sie in der Apigee-UI den Proxy, den Sie im Proxy-Editor erstellt haben.
  2. Wählen Sie den Tab Develop aus.
  3. Wählen Sie im Menü "New" (Neu) die Option New Script (Neues Skript) aus.
  4. Wählen Sie im Dialogfeld JavaScript aus und geben Sie dem Skript den Namen js-example.
  5. Fügen Sie den folgenden Code in den Codeeditor ein und speichern Sie den Proxy. Das Objekt context ist an einer beliebigen Stelle im Proxyablauf im JavaScript-Code verfügbar. Es ruft ablaufspezifische Konstanten ab, ruft nützliche get-/set-Methoden auf und führt andere Vorgänge aus. Dieses Objekt ist Teil des Apigee-JavaScript-Objektmodells. Die Ablaufvariable target.url ist eine integrierte Lese-/Schreibvariable, auf die Sie im Ablauf der Zielanfrage zugreifen können. Wenn Sie diese Variable mit der API-URL festlegen, ruft Apigee diese Back-End-URL auf. Dadurch wird die ursprüngliche Ziel-URL umgeschrieben, die Sie beim Erstellen des Proxys angegeben haben (z. B. 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ählen Sie im Menü "Neue Richtlinie" die Option JavaScript aus.
  7. Nennen Sie die Richtlinie target-rewrite. Übernehmen Sie die Standardwerte und speichern Sie die Richtlinie.
  8. Nachdem Sie im Navigator den Proxy-Endpunkt-Preflow ausgewählt haben, wird die Richtlinie diesem Ablauf hinzugefügt.
  9. Wählen Sie im Navigator die Option Zielendpunkt-PreFlow aus.
  10. Ziehen Sie die JavaScript-Richtlinie im Navigator im Ablaufeditor auf die Anfrageseite des Zielendpunkts.
  11. Speichern.
  12. Ersetzen Sie den Namen Ihrer Organisation und den Proxy-Namen, wenn Sie die API aufrufen: 
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

Sehen Sie sich die XML-Definition für die in diesem Beispiel verwendete JavaScript-Richtlinie an. Mit dem Element <ResourceURL> wird die auszuführende JavaScript-Quelldatei angegeben. Dieses Muster gilt für jede JavaScript-Quelldatei: jsc://filename.js. Wenn Ihr JavaScript-Code erforderlich ist, können Sie dazu ein oder mehrere <IncludeURL>-Elemente verwenden, wie weiter unten in diesem Dokument beschrieben.

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

Attributwert aus JavaScript abrufen

Sie können der Konfiguration ein <Property>-Element hinzufügen und dann den Wert des Elements mit JavaScript zur Laufzeit abrufen.

Verwenden Sie das Attribut name des Elements, um den Namen anzugeben, mit dem über das JavaScript-Code auf das Attribut zugegriffen werden soll. Der Wert des <Property>-Elements (der Wert zwischen dem öffnenden und dem schließenden Tag) ist der Literalwert, der vom JavaScript empfangen wird.

In JavaScript rufen Sie den Wert des Richtlinienattributs ab, indem Sie so auf das Attribut des Objekts Properties zugreifen:

  • Konfigurieren Sie das Attribut. Der Attributwert ist der Variablenname 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>
  • Rufen Sie das Attribut mit JavaScript ab. Die Funktion getVariable verwendet dann den abgerufenen Variablennamen, um den Wert der Variablen abzurufen. 
    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);

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

< languageVersion="VERSION_1_3" Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">
Attribut Beschreibung Standard Präsenz
languageVersion

Gibt die Version der JavaScript-Sprache an, in der der Code geschrieben ist. Mögliche Werte sind VERSION_DEFAULT, VERSION_1_0, VERSION_1_1, VERSION_1_2, VERSION_1_3, VERSION_1_4, VERSION_1_5, VERSION_1_6, VERSION_1_7, VERSION_1_8 und VERSION_ES6.

 VERSION_DEFAULT Optional
Zeitbeschränkung

Gibt die maximale Zeit in Millisekunden an, die ein Skript ausgeführt werden darf. Wenn beispielsweise ein Limit von 200 ms überschritten wird, gibt die Richtlinie diesen Fehler aus: Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms.

 – Erforderlich

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

Attribut Beschreibung Standard Presence
name

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

 – Erforderlich
continueOnError

Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten.

Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Siehe auch:

 false Optional
enabled

Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen.

Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.

 true Optional
async

Dieses Attribut wurde verworfen.

 false Verworfen

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

–

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Presence Optional
Typ String

<IncludeURL>-Element

Gibt eine JavaScript-Bibliotheksdatei an, die als Abhängigkeit für die mit dem Element <ResourceURL> oder <Source> angegebene JavaScript-Hauptdatei geladen werden soll. Die Richtlinie wertet die Skripts in der Reihenfolge aus, 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>
Standard: –
Präsenz: Optional
Typ: String

<Property>-Element

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

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Standard: –
Präsenz: Optional
Typ: String

Attribute

Attribut Beschreibung Standard Präsenz
Name

Gibt den Namen des Attributs an.

 – Erforderlich

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-Proxyset oder im Abschnitt Skripts im Bereich Navigator des API-Proxy-Editors) speichern. Alternativ können Sie sie auch in den Organisations- oder Umgebungsbereichen zur Wiederverwendung in mehreren API-Proxys speichern, wie unter Ressourcen verwalten beschrieben. Ihr Code kann die Objekte, Methoden und Eigenschaften des JavaScript-Objektmodells verwenden.

<ResourceURL>jsc://my-javascript.js</ResourceURL>
Standard: –
Präsenz: <ResourceURL> oder <Source> ist erforderlich. Wenn sowohl <ResourceURL> als auch <Source> vorhanden sind, wird <ResourceURL> von der Richtlinie ignoriert.
Typ: String

Beispiel

Sehen Sie sich das Beispiel im Abschnitt Beispiele an.

<Source>-Element

Sie können 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.

Standard: –
Präsenz: <ResourceURL> oder <Source> ist erforderlich. Wenn sowohl <ResourceURL> als auch <Source> vorhanden sind, wird <ResourceURL> von der Richtlinie ignoriert.
Typ: String

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>
Standard: –
Präsenz: Optional
Typ: String

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 Optionen für die TLS-Konfiguration.

Fehler mit JavaScript behandeln

Sie können die JavaScript-Richtlinie verwenden, um Fehler zu verarbeiten und zurückzugeben. Eine Diskussion zu diesem Thema finden Sie in der Apigee-Community unter Correct way to return an error from a JavaScript policy. Beiträge und Kommentare in der Community entsprechen nicht zwangsläufig den von Apigee empfohlenen Best Practices.

JavaScript-Richtliniencode debuggen

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

So rufen Sie Druckanweisungen im Debugging-Tool auf:

  1. Öffnen Sie das Debug-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 Debug-Tool auf die JavaScript-Richtlinie und dann auf den Tab Eigenschaften, um die Eigenschaft „stepExecution-stdout“ mit der Ausgabe der print-Anweisung zu sehen.

    Ausgabe des Debugging-Tools auf dem Tab „Eigenschaften“ mit Druckanweisungen.

  4. Ihre Druckberichte werden in diesem Feld angezeigt.

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 context-Objekt aufrufen. Beispiel:

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

Das Objekt context ist Teil des Apigee-JavaScript-Objektmodells.

Fehlerreferenz

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.

Fault code HTTP status Cause Fix
steps.javascript.ScriptExecutionFailed 500 The JavaScript policy can throw many different types of ScriptExecutionFailed errors. Commonly seen types of errors include RangeError, ReferenceError, SyntaxError, TypeError, and URIError.
steps.javascript.ScriptExecutionFailedLineNumber 500 An error occurred in the JavaScript code. See the fault string for details. N/A
steps.javascript.ScriptSecurityError 500 A security error occurred when the JavaScript executed. See the fault string for details. N/A

Deployment errors

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

Error name Cause Fix
InvalidResourceUrlFormat If the format of the resource URL specified within the <ResourceURL> or the <IncludeURL> element of the JavaScript policy is invalid, then the deployment of the API proxy fails.
InvalidResourceUrlReference If the <ResourceURL> or the <IncludeURL> elements refer to a JavaScript file that does not exist, then the deployment of the API proxy fails. The referenced source file must exist either the API proxy, environment, or organization level.
WrongResourceType This error occurs during deployment if the <ResourceURL> or the <IncludeURL> elements of the JavaScript policy refer to any resource type other than jsc (JavaScript file).
NoResourceURLOrSource The deployment of the JavaScript policy can fail with this error if the <ResourceURL> element is not declared or if the resource URL is not defined within this element. <ResourceURL> element is a mandatory element. Or, The <IncludeURL> element is declared but the resource URL is not defined within this element. The <IncludeURL> element is optional but if declared, the resource URL must be specified within the <IncludeURL> element.

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.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javascript.JavaScript-1.failed = true

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

Apigee Community-Artikel

Sie finden diese entsprechenden Artikel in der Apigee Community: