API-Proxys mit JavaScript programmieren

Sie lesen gerade die Dokumentation zu Apigee Edge.
Zur Dokumentation zu Apigee X. info

In diesem Thema erfahren Sie, wie Sie mit JavaScript dynamisch HTTP-Header zu einer Antwortnachricht hinzufügen, eine JSON-Antwort parsen und eine Teilmenge ihrer Eigenschaften an die anfragende App zurückgeben.

Beispielcode herunterladen und ausprobieren

Informationen zu diesem Cookbook-Beispiel

Dieses Cookbook-Beispiel veranschaulicht ein API-Proxy-Muster, bei dem Sie das API-Verhalten in JavaScript implementieren. Die JavaScript-Beispiele sollen Ihnen zeigen, wie Sie mit einfachen Variablen und Nachrichteninhalten arbeiten. Ein Beispiel zeigt, wie Sie Variablen abrufen und festlegen. Das zweite Beispiel zeigt, wie Sie JSON parsen und eine Nachricht aus dem Ergebnis erstellen.

Im API-Proxy sind zwei JavaScript-Beispiele enthalten:

  • setHeaders.js: Dieses JavaScript ruft die Werte einiger Variablen ab, die beim Aufrufen eines API-Proxys festgelegt werden. Das JavaScript fügt diese Variablen der Antwort Nachricht hinzu, sodass Sie ihre Werte für jede Anfrage sehen können.
  • minimize.js: Dieses JavaScript zeigt, wie Sie mit Nachrichteninhalten arbeiten. Die Idee hinter diesem Beispiel ist, dass ein Dienst oft mehr Daten zurückgibt als notwendig. Das JavaScript parst also die Antwortnachricht, extrahiert einige interessante Eigenschaften und verwendet sie dann, um den Inhalt der Antwortnachricht zu erstellen.

Der Code für setHeader.js:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

Der Code für minimize.js:

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

Sie können über das Kontextobjekt in JavaScript auf Ablaufvariablen zugreifen. Dieses Objekt ist Teil von dem JavaScript-Objektmodell von Edge. Weitere Informationen zum Objektmodell finden Sie unter JavaScript-Objektmodell.

Hinweis

Bevor Sie sich dieses Cookbook-Beispiel ansehen, sollten Sie auch mit den folgenden grundlegenden Konzepten vertraut sein:

  • Was Richtlinien sind und wie Sie sie an Proxys anhängen. Eine gute Einführung in Richtlinien finden Sie unter Was sind Richtlinien?.
  • Die Struktur eines Proxy-Ablaufs, wie unter Abläufe konfigurieren beschrieben. Mit Abläufen können Sie die Reihenfolge angeben, in der Richtlinien von einem API-Proxy ausgeführt werden. In diesem Beispiel werden mehrere Richtlinien erstellt und einem API-Proxy-Ablauf hinzugefügt.
  • Wie ein API-Proxy-Projekt auf Ihrem Dateisystem organisiert ist, wie unter API-Proxy-Konfigurationsreferenz beschrieben.
  • Grundlegende Kenntnisse in XML, JSON und JavaScript. In diesem Beispiel erstellen Sie den API Proxy und seine Richtlinien mit XML-Dateien, die sich im Dateisystem befinden.

Wenn Sie den Beispielcode heruntergeladen haben, finden Sie alle in diesem Thema besprochenen Dateien im javascript-cookbook Beispielordner. In den folgenden Abschnitten wird der Beispielcode im Detail erläutert.

Informationen zum Proxy-Ablauf

Damit JavaScript in einem API-Proxy ausgeführt werden kann, müssen Sie es mit einer Richtlinien anhängung, einem sogenannten Schritt, an einen Ablauf anhängen. Eine Richtlinie vom Typ Javascript (Groß-/Kleinschreibung beachten) enthält einfach einen Verweis auf den Namen einer JavaScript-Datei. Sie verweisen mit dem Element ResourceURL auf eine JavaScript-Datei.

Die folgende Richtlinie verweist beispielsweise auf die JavaScript-Datei namens setHeader.js.

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

Sie können diese Richtlinie wie jeden anderen Richtlinientyp an einen API-Proxy-Ablauf anhängen. Wenn Sie die Richtlinie an den API-Proxy-Ablauf anhängen, geben Sie an, wo das JavaScript ausgeführt werden soll. So können Sie JavaScript ausführen, das mit Anfrage- oder Antwortnachrichten interagiert, während diese Nachrichten den API-Proxy durchlaufen. In diesem Beispiel werden beide JavaScripts im Antwortablauf ausgeführt, da die Richtlinien zwei Aufgaben haben: HTTP-Header in der Antwortnachricht festlegen und die Antwortnachricht, die Apigee Edge an die anfragende App zurückgibt, „minimieren“.

Wenn Sie diese Ablaufkonfiguration in der Verwaltungs-UI öffnen, sehen Sie die folgende Ablaufkonfiguration unten.

Wählen Sie im Bereich Navigator die Option Proxy-Endpunkte > Standard > PostFlow aus.

Die entsprechende XML-Konfiguration für den ProxyEndpoint mit dem Namen „default“ ist unten dargestellt. 

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Hier eine Zusammenfassung der Elemente des Ablaufs.

  • <Request> : Das Element <Request> besteht aus mehreren <Step>-Elementen. Jeder Schritt ruft eine der Richtlinien auf, die Sie im Rest dieses Themas erstellen. Diese Richtlinien hängen ein JavaScript an den API-Proxy-Ablauf an. Die Position der Richtlinienanhängung bestimmt, wann das JavaScript ausgeführt wird.
  • <Response> – Das Element <Response> enthält auch <Steps>. Diese Schritte rufen auch Richtlinien auf, die für die Verarbeitung der endgültigen Antwort vom Ziel verantwortlich sind. In diesem Beispiel ist das Ziel der Mock-Dienst von Apigee. Beachten Sie die Einstellung HTTPTargetConnection in /apiproxy/targets/default.xml.
  • <HTTPProxyConnection> : Gibt den Host und den URI-Pfad an, die die Netzwerkadresse definieren, die Apps aufrufen, um diese API zu verwenden.
  • <RouteRule> : Dieses Element gibt an, welche TargetEndpoint Konfiguration vom ProxyEndpoint aufgerufen wird.

JavaScript-Code zu einem Proxy hinzufügen

JavaScript (wie Python-Skripts, Java-JAR-Dateien, XSLT-Dateien usw.) werden als Ressourcen gespeichert. Wenn Sie gerade erst mit JavaScript arbeiten, ist es am einfachsten, Ihre JavaScript-Dateien im API-Proxy zu speichern. Im Laufe der Zeit sollte JavaScript so allgemein und wiederverwendbar wie möglich sein und dann auf Umgebungs oder Organisationsebene gespeichert werden. So vermeiden Sie, dass Sie dieselben JavaScript-Dateien in mehreren API-Proxys speichern müssen, was schnell unübersichtlich werden kann.

Informationen zum Speichern von Ressourcen auf Organisations- und Umgebungsebene finden Sie unter Ressourcendateien.

Jetzt ausprobieren

Eine Anleitung zum Bereitstellen und Aufrufen des Proxys finden Sie in der README-Datei des JavaScript-Cookbooks.

API-Proxy importieren und bereitstellen

Nachdem Sie Änderungen vorgenommen haben, können Sie den API-Proxy im API-Proxy-Builder Tool in der Verwaltungs-UI speichern.

Alternativ können Sie den folgenden Befehl im Verzeichnis /api-platform-samples/doc-samples/javascript-cookbook ausführen.

$ sh deploy.sh

JavaScript testen

Führen Sie den folgenden Befehl im Verzeichnis /api-platform-samples/doc-samples/javascript-cookbook aus.

$ sh invoke.sh

Das curl-Flag -v wird im Shell-Skript verwendet, um HTTP-Header in der Antwort nachricht anzuzeigen, die von JavaScript geändert wurden.

Sie können eine Anfrage direkt so senden:

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook

Wenn das JavaScript ordnungsgemäß ausgeführt wird, sehen Sie eine Antwort wie die folgende:

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

Sie können das JavaScript jetzt ändern, um neue Dinge auszuprobieren, den API-Proxy noch einmal bereitstellen und die Ergebnisse überprüfen, indem Sie dieselbe Anfrage senden. Achten Sie immer darauf, dass Sie den API-Proxy bereitstellen, der Ihr JavaScript enthält, damit Ihre Änderungen wirksam werden.

Skriptfehler

Beim Schreiben von JavaScript treten unweigerlich Fehler auf. Das Format von JavaScript-Fehlern, die von einem API-Proxy ausgegeben werden, ist unten dargestellt.

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

Wann sollte JavaScript verwendet werden?

In Apigee Edge gibt es in der Regel mehr als eine Möglichkeit, bestimmte Funktionen zu implementieren. Verwenden Sie nach Möglichkeit sofort einsatzbereite Richtlinien und vermeiden Sie es, die gesamte API-Proxy Logik in JavaScript zu codieren. Obwohl Apigee Edge kompiliertes JavaScript verwendet, um die Leistung zu verbessern , ist es unwahrscheinlich, dass JavaScript so gut funktioniert wie Richtlinien. JavaScript ist möglicherweise schwieriger zu warten und zu debuggen. Verwenden Sie JavaScript nur für Funktionen, die für Ihre Anforderungen spezifisch sind.

Wenn die Leistung für benutzerdefinierte Funktionen wichtig ist, verwenden Sie nach Möglichkeit Java.

Zusammenfassung

In diesem Cookbook-Thema haben Sie erfahren, wie JavaScript in eine API-Proxy Konfiguration eingebunden werden kann, um benutzerdefiniertes Verhalten zu implementieren. Das benutzerdefinierte Verhalten, das von den Beispielen implementiert wird , zeigt, wie Sie Variablen abrufen und festlegen sowie JSON parsen und benutzerdefinierte Antwortnachrichten erstellen.