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

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.

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

Apigee unterstützt JavaScript, das auf der Rhino JavaScript-Engine 1.7.13 ausgeführt wird.

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

Fehlerbehebung

Beispiele und eine Erläuterung der Fehlerbehandlungstechniken, die Sie in einem JavaScript-Callout verwenden können, finden Sie unter Richtige Methode zum Zurückgeben von Fehlern aus der JavaScript-Richtlinie. Die in der Apigee-Community bereitgestellten Vorschläge dienen nur Informationszwecken und entsprechen nicht zwangsläufig den von Google empfohlenen Best Practices.

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

Verwendungshinweise

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 Ausgabe von allen Transaktionen, um das Ausgabefeld zu öffnen.

    Das Feld „Output from all Transactions“ (Ausgabe von allen Transaktionen) im Apigee Trace Tool mit print-Anweisungen.

  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

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die 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.

Fehlercode HTTP-Status Ursache Diverse Fehlerkorrekturen
steps.javascript.ScriptExecutionFailed 500 Die Richtlinie JavaScript kann viele verschiedene Arten von ScriptExecutionFailed-Fehlern verursachen. Häufig auftretende Fehler sind unter anderem:RangeError ,ReferenceError ,SyntaxError ,TypeError und URIError.
steps.javascript.ScriptExecutionFailedLineNumber 500 Im Code JavaScript ist ein Fehler aufgetreten. Weitere Informationen finden Sie im Fehlerstring. –
steps.javascript.ScriptSecurityError 500 Beim Ausführen von JavaScript ist ein Sicherheitsfehler aufgetreten. Weitere Informationen finden Sie im Fehlerstring. –

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlername Ursache Diverse Fehlerkorrekturen
InvalidResourceUrlFormat Wenn das Format der Ressourcen-URL im <ResourceURL>-Element oder im <IncludeURL>-Element der JavaScriptPythonScript-Richtlinie ungültig ist, schlägt die Bereitstellung des API-Proxys fehl.
InvalidResourceUrlReference Wenn <ResourceURL> oder <IncludeURL> auf eine JavaScript-Datei verweist, die nicht vorhanden ist, schlägt die Bereitstellung des API-Proxys fehl. Die referenzierte Quelldatei muss entweder in der API-Proxy, der Umgebung oder auf Organisationsebene vorhanden sein.
WrongResourceType Dieser Fehler tritt während der Bereitstellung auf, wenn die Elemente <ResourceURL> oder <IncludeURL> der Richtlinie JavaScript auf einen anderen Ressourcentyp als jsc (JavaScript-Datei) verweisen.
NoResourceURLOrSource Die Bereitstellung der Richtlinie JavaScript kann mit diesem Fehler fehlschlagen, wenn das Element <ResourceURL> nicht deklariert ist oder die Ressourcen-URL nicht innerhalb dieses Elements definiert ist. <ResourceURL> ist ein erforderliches Element. Oder das Element <IncludeURL> wird deklariert, aber die Ressourcen-URL ist in diesem Element nicht definiert. Das Element <IncludeURL> ist optional, aber wenn es deklariert wird, muss die Ressourcen-URL im Element <IncludeURL> angegeben werden.

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.

Variablen Wo Beispiel
fault.name="fault_name" fault_name ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. javascript.JavaScript-1.failed = true

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

Apigee Community-Artikel

Sie finden diese entsprechenden Artikel in der Apigee Community: