JavaScript-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

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 des JavaScript-Objektmodells von Apigee 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.

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.

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 benutzerdefiniertes Verhalten implementieren, das nicht durch andere Apigee-Standardrichtlinien 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 MessageLogging-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. Führen Sie dazu die MessageLogging-Richtlinie in PostClientFlow aus, 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.

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

Video

Hinweis: Das folgende Video zeigt den klassischen Proxy-Editor in der Apigee-UI. Apigee führt eine neue Version des Proxy-Editors ein, die ein anderes Design als die im Video gezeigte klassische Version hat.

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

Beispiele

Geben Sie die Ziel-URL ein

Dies ist ein häufiger Anwendungsfall: Daten aus einem Anfragetext extrahieren, in einer Ablaufvariablen speichern und diese Ablaufvariable an anderer Stelle im Proxyablauf verwenden. Angenommen, Ihre Anwendung gibt ihren Namen in einem HTML-Formular ein und sendet es. Sie möchten, dass der API-Proxy die Formulardaten extrahiert und der URL, mit der der Back-End-Dienst aufgerufen wird, dynamisch hinzugefügt. Wie gehen Sie dazu in einer JavsScript-Richtlinie vor?

Hinweis: Wenn Sie dieses Beispiel ausprobieren möchten, gehen wir davon aus, dass Sie einen neuen Proxy im Proxy-Editor erstellt haben. Geben Sie dazu einfach eine Back-End-Dienst-URL an: http://www.example.com. In diesem Beispiel ändern wir die Back-End-URL dynamisch um. Wenn Sie nicht wissen, wie ein neuer Proxy erstellt wird, lesen Sie die Anleitung „Erste Schritte“.

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 einen Namen, z. B. js-example.
5. Fügen Sie den folgenden Code in den Codeeditor ein und speichern Sie den Proxy. Beachten Sie unbedingt das context-Objekt. Dieses Objekt ist an einer beliebigen Stelle im Proxyablauf im JavaScript-Code verfügbar. Es wird verwendet, um ablaufspezifische Konstanten abzurufen, nützliche Get- und Set-Methoden aufzurufen und für weitere Vorgänge zu verwenden. Dieser Objektteil ist Teil des JavaScript-Objektmodells von Apigee. Beachten Sie auch, dass die Ablaufvariable target.url eine integrierte Lese-/Schreibvariable ist, auf die Sie im Ablauf der Zielanfrage zugreifen können. Wenn wir diese Variable mit der API-URL festlegen, führt Apigee ihren Back-End-Aufruf an diese URL aus. Wir haben 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. Geben Sie der Richtlinie einen Namen, z. B. target-rewrite. Übernehmen Sie die Standardwerte und speichern Sie die Richtlinie.
8. Wenn Sie den Proxy-Endpunkt-Preflow im Navigator auswählen, werden Sie sehen, dass die Richtlinie diesem Ablauf hinzugefügt wurde.
9. Wählen Sie im Navigator das Symbol Zielendpunkt-PreFlow aus.
10. Ziehen Sie die JavaScript-Richtlinie aus dem Navigator im Request-Editor auf die Anfrageseite des Zielendpunkts.
11. Speichern.
12. Rufen Sie die API so auf und ersetzen Sie dabei den korrekten Organisationsnamen und den Proxy-Namen entsprechend:

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

Betrachten wir schließlich die XML-Definition für die in diesem Beispiel verwendete JavaScript-Richtlinie. Wichtig ist, dass mit dem Element <ResourceURL> die JavaScript-Quelldatei angegeben wird, die ausgeführt werden soll. Dasselbe Muster wird für jede JavaScript-Quelldatei verwendet: jsc://filename.js. Wenn Ihr JavaScript-Code erforderlich ist, können Sie dazu ein oder mehrere <IncludeURL>-Elemente verwenden, wie weiter unten in dieser Referenz 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.

Verwende 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. Hier ist der Attributwert 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. Hier wird der abgerufene Wert, ein Variablenname, dann von der Funktion getVariable zum Abrufen des Variablenwerts verwendet.

  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.

In einer JavaScript-Richtlinie führt der Zugriff auf request.content.asJSON in einer schreibgeschützten Kapazität dazu, dass ganze Ganzzahlen im Nachrichtentext in exponentielle Notation konvertiert werden. Dadurch wird die Nachricht mit den konvertierten Werten überschrieben.

---

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.

Attribut	Beschreibung	Standard	Presence
timeLimit	Gibt die maximale Zeit in Millisekunden an, die das 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. Hinweis: Bei kostenlosen Testkonten ist die Ausführungszeit auf 200 ms beschränkt.	–	Erforderlich

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
name	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
continueOnError	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
enabled	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
async	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default	N/A If you omit this element, the value of the policy's name attribute is used.
Presence	Optional
Type	String

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

Warnung: Ihre JavaScript-Dateien werden auf Organisations- oder Umgebungsebene gespeichert. Achten Sie darauf, dass sie mit cURL mit der Option -F oder als Datei hochgeladen wurden. Anhang über einen REST-Client senden. Der Inhaltstyp ist multipart/form-data. Weitere Informationen finden Sie unter Ressourcen verwalten.

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

Standard:	–
Präsenz:	Optional
Typ:	String

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>

Standard:	–
Präsenz:	Optional
Typ:	String

Attribute

Attribut	Beschreibung	Standard	Presence
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 Navigationsbereich des API-Proxy-Editors) oder 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 ist, wird <ResourceURL> ignoriert.
Typ:	String

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.

Standard:	–
Präsenz:	<ResourceURL> oder <Source> ist erforderlich. Wenn sowohl <ResourceURL> als auch <Source> vorhanden ist, wird <ResourceURL> 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

Warnung: Systemaufrufe sind vom Sicherheitsmodell nicht zulässig. Beispiel: Das interne Dateisystem liest oder liest oder liest aktuelle Nutzerinformationen, die Prozessliste oder die CPU-/Speicherauslastung. Auch wenn einige dieser Aufrufe 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.

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 „Debugging mit JavaScript-print()-Anweisungen“.

So rufen Sie Druckanweisungen in Debug 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.

   

4. Ihre Druckberichte werden in diesem Feld angezeigt.

Mit der Funktion print() können Sie Debugging-Informationen an das Debug-Tool ausgeben. 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 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.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

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.

Tip: Need help resolving an error? Click next to the error's cause description to visit the troubleshooting page.

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

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Apigee Community-Artikel

Sie finden diese entsprechenden Artikel in der Apigee Community:

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