Java-Callout erstellen

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Was ist ein Java-Callout?

Apigee bietet eine Reihe von Richtlinien für allgemeine API-Verwaltungsanforderungen wie Sicherheit, Datentransformation und Trafficverwaltung.

Es gibt jedoch Fälle, in denen Ihre API benutzerdefiniertes Verhalten benötigt, das nicht in einer Standardrichtlinie implementiert ist. In diesen Fällen bietet Apigee verschiedene Optionen, mit denen Sie ein Skript- oder benutzerdefiniertes API-Verhalten erstellen können. Ein Ansatz besteht darin, das gewünschte Verhalten in Java zu implementieren.

Zu den unterstützten Java-Versionen zählen: Oracle JDK 11 und OpenJDK 11.

Wie verwende ich Java-Code in einem Proxy?

Mit einer Java-Callout-Richtlinie können Sie Java-Code aus einem ausgeführten Proxyablauf aufrufen. Ihr Java-Code muss bestimmte Apigee-spezifische Java-Schnittstellen implementieren, die eine Interaktion des Codes mit dem ausgeführten Proxy ermöglichen. Beispielsweise finden Sie Java-Methoden zum Abrufen und Festlegen von Headern, Abfrageparameter, Flussvariablen und anderen Entitäten im aktuellen Ablaufkontext des Proxys.

Wann sollte ich Java-Callouts verwenden?

Sehen wir uns nun Situationen an, in denen Java-Callouts nützlich sind, und Situationen, in denen Sie andere Ansätze berücksichtigen sollten.

Alternative Ansätze berücksichtigen

Bevor Sie ein Java-Callout verwenden, gibt es möglicherweise alternative Ansätze, die Sie stattdessen verwenden können. Beispiel:

  • Für einfache Vorgänge wie HTTP API-Aufrufe für Remote-Dienste sollten Sie die ServiceCallout-Richtlinie verwenden. Siehe Service Callout-Richtlinie.
  • Bei relativ einfachen Interaktionen mit Nachrichteninhalten, z. B. zum Ändern oder Extrahieren von HTTP-Headern, Parametern oder Nachrichteninhalten, können Sie JavaScript- oder PythonScript-Richtlinien verwenden.

Was in Java-Code möglich ist

Ein Java-Callout unterstützt die folgenden grundlegenden Vorgänge:

  • Anfrage- oder Antwortnachrichten untersuchen oder bearbeiten.
  • Ablaufvariablen abrufen und festlegen. Sie können Java-Methoden verwenden, um auf Apigee-Ablaufvariablen zuzugreifen. Wenn Sie auf Informationen zu Key Value Map (KVM) zugreifen möchten, verwenden Sie eine KVM-Richtlinie und weisen den Ablaufvariablen KVM-Werte zu. Daraufhin können Sie auf die Ablaufvariablen innerhalb des Java-Callouts zugreifen.
  • Externe Dienste aufrufen
  • Fehlerantworten generieren
  • Fehlermeldungen und Statuscodes bearbeiten

Was in Java-Code nicht möglich ist

Die meisten Systemaufrufe sind nicht zulässig. Das können Sie nicht tun:

  • Internes Dateisystem für Lese- oder Schreibvorgänge konfigurieren Das bedeutet, dass Sie keine Java-Pakete zum Lesen/Schreiben in interne Dateisysteme verwenden können. Sie können jedoch externe Remoteaufrufe ausführen.
  • Informationen zum aktuellen Prozess, zur Prozessliste oder zur CPU-/Speicherauslastung auf der Maschine abrufen.
  • Auf den Quellcode in expressions-1.0.0.jar und message-flow-1.0.0.jar zugreifen.

Auch wenn einige dieser Aufrufe funktionieren, werden sie nicht unterstützt und können jederzeit deaktiviert werden. Vermeiden Sie diese Aufrufe in Ihrem Code.

Verwenden Sie keine Java-Bibliotheken, die in Apigee enthalten sind. Diese Bibliotheken gelten nur für die Apigee-Produktfunktionen und es gibt keine Garantie, dass in jedem Release eine Bibliothek verfügbar ist. Wenn Sie diese Bibliotheken verwenden, dann nur in Demonstrationen; nicht in der Produktionsumgebung.

„Hello Java“-Callout

Sehen wir uns ein einfaches Beispiel für eine Java-Erweiterung mit „Hello World” an. In diesem Beispiel erstellen wir einen einfachen Proxy mit einem Java-Callout, der eine „Hello World”-Antwort zurückgibt. Der Proxy kann eine von zwei möglichen Antworten zurückgeben:

  • Wenn Sie einen „username“-Header mit einem „name“-Wert übergeben, gibt der Proxy Folgendes zurück:

    Hello, <name>!
  • Wenn Sie den Header weglassen, gibt der Proxy nur Folgendes zurück:

    "Hello, Guest!"

Startprojekt herunterladen

Der Einfachheit halber haben wir auf GitHub im Apigee-Repository api-platform-samples ein einfaches Projekt vorbereitet.

  1. Laden Sie api-platform-samples in Ihr System herunter oder klonen Sie es. Wenn Sie bereits api-platform-samples auf Ihrem System haben, führen Sie einen pull aus, um sicherzustellen, dass Sie die neueste Version haben.
  2. Wechseln Sie in einem Terminal oder Codeeditor Ihrer Wahl zum api-platform-samples/doc-samples/java-hello-Projekt.

Java-Code schreiben

  1. Öffnen Sie die Java-Quelldatei: java-hello/callout/src/main/java/HelloJava.java. Diese Datei ist eine Basisversion der Java-Hauptklasse, die wir implementieren werden. Die importierten Pakete sind für den Apigee-Java-Callout-Code erforderlich. Diese Klassen bieten Methoden zum Zugreifen auf den Kontext der Proxyausführung. Die Schritte zum Kompilieren und Bereitstellen dieses Codes werden weiter unten erläutert.
    package com.apigeesample;

import com.apigee.flow.execution.ExecutionContext;
import com.apigee.flow.execution.ExecutionResult;
import com.apigee.flow.execution.spi.Execution;
import com.apigee.flow.message.MessageContext;


public class HelloJava implements Execution {

        public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {

                try {

                        // Your code here.

            return ExecutionResult.SUCCESS;

                } catch (Exception e) {
                        return ExecutionResult.ABORT;
                }
        }

}
  2. Ersetzen Sie die kommentierte Zeile // Your code here durch den folgenden Code:

    String name = messageContext.getMessage().getHeader("username");

if (name != null && name.length()>0) {
        messageContext.getMessage().setContent("Hello, " + name + "!");
        messageContext.getMessage().removeHeader("username");
} else {
        messageContext.getMessage().setContent("Hello, Guest!");
}
  3. Speichern Sie die Datei.


Code mit Maven kompilieren

  1. Prüfen Sie, ob Maven installiert ist:

    mvn -version
  2. Installieren Sie die erforderlichen JAR-Abhängigkeiten in Ihrem lokalen Maven-Repository mit einer der folgenden Methoden:
    • Fügen Sie der Datei pom.xml das folgende Snippet hinzu, um die erforderlichen JAR-Abhängigkeiten aus Artifact Registry herunterzuladen: 
      <repositories>
  <repository>
    <id>artifact-registry</id>
    <url>https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.apigee.gateway.libraries</groupId>
    <artifactId>message-flow</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
  <dependency>
    <groupId>com.apigee.infra.libraries</groupId>
    <artifactId>expressions</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
</dependencies>
    • Verwenden Sie die folgenden curl-Aufrufe, um die erforderlichen JAR-Abhängigkeiten aus Artifact Registry herunterzuladen: 
      curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/gateway/libraries/message-flow/1.0.0/message-flow-1.0.0.jar" -v -L -o message-flow-1.0-0.jar
        
      curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/infra/libraries/expressions/1.0.0/expressions-1.0.0.jar" -v -L -o expressions-1.0.0.jar
    • Führen Sie das java-hello/buildsetup.sh-Skript aus: Mit diesem Script werden die erforderlichen JAR-Abhängigkeiten aus dem Apigee GitHub-Repository heruntergeladen.
  3. cd in das java-hello/callout-Verzeichnis.
  4. Führen Sie Maven aus:

    mvn clean package
  5. Prüfen Sie bei Bedarf, ob die edge-custom-policy-java-hello.jar-JAR-Datei nach java-hello/apiproxy/resources/java kopiert wurde. Dies ist der erforderliche Speicherort für JAR-Dateien, die Sie mit einem Proxy bereitstellen möchten.

Proxy bereitstellen und aufrufen

So stellen Sie den API-Proxy bereit und testen ihn:

  1. Wechseln Sie zum Verzeichnis java-hello.
  2. Komprimieren Sie das API-Proxy-Bundle in einer ZIP-Datei: 
    zip apiproxy-bundle.zip -r apiproxy -x \*.\*~
  3. Die einfachste Methode zum Bereitstellen des Proxys besteht darin, ihn in einer ZIP-Datei zu bündeln und das Proxy-Bundle in eine Umgebung in Ihrer Apigee-Organisation hochzuladen. Siehe API-Proxy erstellen. Verwenden Sie unbedingt die Option Proxyproxy hochladen. Weitere Informationen finden Sie auch unter Tipps und Tricks zum Hochladen eines API-Proxys in einem Proxy-Bundle in der Apigee-Community.
  4. Wenn der Proxy bereitgestellt ist, versuchen Sie, ihn aufzurufen:
    curl  https://$HOSTNAME/java-hello -H "username:Will"

    Daraufhin wird „Hello, Will!“ zurückgegeben.

Über den Proxy

Sehen wir uns kurz die Richtlinien an, die in diesem Proxy verwendet werden. Achten Sie darauf, wo die Richtlinien im Proxyablauf platziert sind und warum.

Richtlinie „AssignMessage“

Die Richtlinie „AssignMessage“ ist mit dem ProxyEndpoint-Anfrageablauf verknüpft. Sie kopiert den Nutzernamen-Header aus der Anfrage und weist ihn der Antwort zu. Aufgrund dieses Vorgangs kann die mit dem Antwortablauf verknüpfte JavaCallout-Richtlinie auf den Nutzernamen-Header zugreifen und einen benutzerdefinierten Antworttext mit dem Wert dieses Headers erstellen.

<AssignMessage async="false" continueOnError="false" enabled="true" name="CopyHeader">
    <DisplayName>CopyHeader</DisplayName>
    <Copy source="request">
        <Headers>
          <Header name="username"/>
        </Headers>
    </Copy>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

JavaCallout-Richtlinie

Die Java-Callout-Richtlinie ist an den Antwortablauf angehängt. Dies liegt daran, dass der benutzerdefinierte Java-Code Änderungen an den Antwortheadern und der Nachricht vornimmt. Das ClassName-Element der Richtlinie gibt die Hauptklasse an, die von der Richtlinie ausgeführt wird. Das ResourceURL-Element ist der Name der JAR-Datei, die Sie erstellt und dem Verzeichnis resources/java des Proxys hinzugefügt haben.

<JavaCallout name="hello-java">
    <ClassName>com.apigeesample.HelloJava</ClassName>
    <ResourceURL>java://edge-custom-policy-java-hello.jar</ResourceURL>
</JavaCallout>

Wissenswertes zu Java-Callouts

Wichtige Hinweise zur Implementierung eines Java-Callouts:

  • Importiert Klassen aus den Paketen com.apigee.flow.execution und com.apigee.flow.message. Diese Pakete müssen in der JAR-Datei enthalten sein und bereitgestellt werden. Sie können Ihre Java-JAR über den Management-UI-Proxy-Editor hochladen oder die Datei in das Verzeichnis /resources/java in API-Proxys aufnehmen, die Sie lokal entwickeln.
  • Implementiert die Ausführungsschnittstelle. Jeder Java-Code, der in einem API-Proxy ausgeführt wird, muss Ausführungen implementieren.
  • Eine Java-Callout-Richtlinie enthält keinen tatsächlichen Code. Stattdessen verweist eine Java-Callout-Richtlinie auf eine Java-„Ressource“, die Sie in eine JAR-Datei verpacken müssen.
  • Zu vermeidende Paketnamen: Verwenden Sie in Java-Callouts nicht io.apigee oder com.apigee als Paketnamen. Diese sind für die Verwendung durch andere Apigee-Module reserviert.
  • Wenn Ihr Java-Callout auf zusätzliche Bibliotheken von Drittanbietern verweist, die als unabhängige JAR-Dateien verpackt werden, legen Sie diese JAR-Dateien ebenfalls im Verzeichnis /resources/java ab, damit sie zur Laufzeit ordnungsgemäß geladen werden.
  • Wenn es mehrere JARs gibt, fügen Sie diese einfach als zusätzliche Ressourcen hinzu. Sie müssen die Richtlinienkonfiguration nicht ändern, um auf zusätzliche JAR-Dateien zu verweisen. Es ist ausreichend, sie in /resources/java aufzunehmen.
  • Informationen zum Hochladen von Java-JARs finden Sie unter Ressourcendateien.