JavaCallout-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Richtliniensymbol

Was

Mit Java können Sie benutzerdefiniertes Verhalten implementieren, das von den Apigee-Richtlinien nicht vorkonfiguriert ist. In Ihrem Java-Code können Sie im Proxyablauf auf Nachrichtenattribute (Header, Abfrageparameter, Inhalt) und Ablaufvariablen zugreifen. Wenn Sie diese Richtlinie zum ersten Mal verwenden, lesen Sie die Informationen unter Java-Erweiterung erstellen.

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

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.

Wann

Weitere Informationen finden Sie im Abschnitt "Wann sollte ich Java-Callouts verwenden?" im Artikel zum Erstellen einer Java-Erweiterung.

Info

Mit der Java-Callout-Richtlinie können Sie Ablaufvariablen abrufen und festlegen, benutzerdefinierte Logik ausführen und Fehlerbehandlung ausführen, Daten aus Anfragen oder Antworten extrahieren und mehr. Mit dieser Richtlinie können Sie benutzerdefiniertes Verhalten implementieren, das nicht durch andere Apigee-Standardrichtlinien abgedeckt ist.

Sie können Ihre Java-Anwendung mit allen Paket-JAR-Dateien verpacken. Beachten Sie, dass es einige Einschränkungen gibt, was Sie mit einem Java-Callout tun können. Diese sind unten unter Einschränkungen aufgeführt.

Beispiele

Einfaches Beispiel

Java-Callout erstellen

Attribute in Ihrem Java-Code abrufen

Mit dem Element <Property> der Richtlinie können Sie ein Name/Wert-Paar angeben, das zur Laufzeit in Ihrem Java-Code abgerufen werden kann. Ein Praxisbeispiel, das Attribute verwendet, finden Sie unter Attribute in einem Java-Callout verwenden.

Geben Sie mit dem name-Attribut des <Property>-Elements den Namen an, von dem aus auf Java-Code auf das Attribut zugegriffen werden soll. Der Wert des Elements <Property> (Wert zwischen dem öffnen- und schließen-Tag) ist der Wert, der vom Java-Code empfangen wird. Der Wert muss ein String sein. Sie können nicht auf eine Ablaufvariable verweisen, um den Wert abzurufen.

  • Konfigurieren Sie das Attribut. Hier ist der Attributwert der Variablenname response.status.code. 
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
    <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
    <Properties>
        <Property name="source">response.status.code</Property>
    </Properties>
</Javascript>
  • Implementieren Sie in Ihrem Java-Code den folgenden Konstruktor für die Implementierung der Ausführungsklasse so:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

Ablaufvariablen in Ihrem Java-Code festlegen

Eine klare Beschreibung zum Festlegen von Variablen im Nachrichtenkontext (Ablaufvariablen) in Ihrem Java-Code finden Sie in diesem Apigee Community-Post.

Elementverweis

Die Elementreferenz beschreibt die Elemente und Attribute der JavaCallout-Richtlinie.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

<JavaCallout>-Attribute

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

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

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

<ClassName>-Element

Gibt den Namen der Java-Klasse an, die beim Ausführen der Java-Callout-Richtlinie ausgeführt wird. Die Klasse muss in der von <ResourceURL> angegebenen JAR-Datei enthalten sein. Siehe auch Java-Callout erstellen.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Standard: –
Präsenz: Erforderlich
Typ: String

<Properties>-Element

Fügt neue Attribute hinzu, auf die vom Java-Code zur Laufzeit zugegriffen werden kann.

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

<Property>-Element

Gibt ein Attribut an, das auf die Laufzeit vom Java-Code aus zugegriffen werden kann. Sie müssen für jedes Attribut einen literalen Stringwert angeben. Sie können in diesem Element nicht auf Ablaufvariablen verweisen. Ein Praxisbeispiel mit Attributen finden Sie unter Attribute in einem Java-Callout verwenden.

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

<ResourceURL>-Element

Dieses Element gibt die Java JAR-Datei an, die ausgeführt wird, wenn die Java-Callout-Richtlinie ausgeführt wird.

Sie können diese Datei im API-Proxy-Bereich (unter /apiproxy/resources/java 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 unter Ressourcendateien beschrieben.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Standard: –
Präsenz: Erforderlich
Typ: String

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 Beheben
steps.javacallout.ExecutionError 500 Tritt auf, wenn Java-Code eine Ausnahme auslöst oder null während der Ausführung eines JavaCallout policy zurückgibt.

Bereitstellungsfehler

Diese Fehler können bei der Bereitstellung des Proxy mit der Richtlinie auftreten.

Fehlername Fehlerstring HTTP-Status Tritt auf, wenn Folgendes eintritt
ResourceDoesNotExist Resource with name [name] and type [type] does not exist – Die im Element <ResourceURL> angegebene Datei ist nicht vorhanden.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] – Die im Element <ClassName> angegebene Klassendatei befindet sich nicht in der JAR-Datei.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] – Siehe Fehlerstring. Unterstützte Java-Versionen: Oracle JDK 7/8 und OpenJDK 7/8
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] – Siehe Fehlerstring.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] – Siehe Fehlerstring.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] – Siehe Fehlerstring.
NoResourceForURL Could not locate a resource with URL [string] – Siehe Fehlerstring.

Fehlervariablen

Diese Variablen werden festgelegt, wenn die Richtlinie einen Fehler auslöst. Weitere Informationen finden sich 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 "ExecutionError"
javacallout.policy_name.failed policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. javacallout.JC-GetUserData.failed = true

Beispiel für eine Fehlerantwort

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

Beispiel für eine Fehlerregel

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

Schemas

Kompilieren und bereitstellen

Ausführliche Informationen zum Kompilieren Ihres benutzerdefinierten Java-Codes und zum Bereitstellen mit einem Proxy finden Sie unter Java-Callout erstellen.

Beschränkungen

Im Folgenden finden Sie Einschränkungen, die Sie beim Schreiben von Java-Callouts beachten müssen:

  • Die meisten Systemaufrufe sind nicht zulässig. Sie können beispielsweise keine internen Lese- oder Schreibvorgänge im Dateisystem durchführen.
  • Zugriff auf das Netzwerk über Sockets. Apigee schränkt den Zugriff auf Sitelokal-, Anylokal-, Loopback- und Linklokaladressen ein.
  • Das Callout kann keine Informationen über den aktuellen Prozess, die Prozessliste oder die CPU-/Speicherauslastung auf dem Computer abrufen. 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.
  • Die Abhängigkeit von Java-Bibliotheken, die in Apigee enthalten sind, wird nicht unterstützt. Diese Bibliotheken beziehen sich nur auf die Produktfunktionalität von Apigee und es gibt keine Garantie dafür, dass eine Bibliothek vom Release bis zum Release verfügbar ist.
  • Verwenden Sie io.apigee oder com.apigee nicht als Paketnamen in Java-Callouts. Diese Namen sind reserviert und werden von anderen Apigee-Modulen verwendet.

Verpackung

Fügen Sie die JAR in einen API-Proxy unter /resources/java ein. 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 in das Verzeichnis /resources/java ab, damit sie zur Laufzeit ordnungsgemäß geladen werden.

Wenn Sie den Proxy über die Verwaltungsoberfläche erstellen oder ändern, fügen Sie eine neue Ressource hinzu und geben Sie eine zusätzliche abhängige JAR-Datei an. 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.

Ein detailliertes Beispiel, das zeigt, wie ein Java-Callout mit Maven oder Javac verpackt und bereitgestellt wird, finden Sie unter Java-Callout erstellen.

Javadoc

Javadoc zum Schreiben von Java-Callout-Code ist hier auf GitHub enthalten. Sie müssen den HTML-Code klonen oder auf Ihr System herunterladen und dann einfach die Datei index.html in einem Browser öffnen.

Verwendungshinweise und Best Practices

  • Wenn Sie mit mehreren Java-Callouts arbeiten, sollten Sie allgemeine JAR-Dateien als umgebungsbezogene Ressourcen hochladen. Diese Vorgehensweise ist effizienter als das Erstellen von Paketen aus den gleichen JAR-Dateien und mehreren Proxy-Bundles, wenn sie in einer Umgebung bereitgestellt werden.
  • Vermeiden Sie das Verpacken und die Bereitstellung mehrerer Kopien oder Versionen derselben JAR-Datei in einer Umgebung. Apigee empfiehlt beispielsweise, Folgendes zu vermeiden:
    • Die gleiche JAR-Datei als Teil eines Proxy-Bundles und als Umgebungsressource bereitzustellen.
    • Eine Version einer JAR-Datei als Umgebungsressource und eine andere als Teil eines Proxy-Bundles bereitzustellen

    Wenn mehrere Kopien einer JAR-Datei bereitgestellt werden, kann dies aufgrund der potenziellen ClassLoader-Konflikte zur Laufzeit zu einem nicht-deterministischen Verhalten führen.

  • Eine Java-Callout-Richtlinie enthält keinen tatsächlichen Code. Stattdessen verweist eine Java-Callout-Richtlinie auf eine Java- "Ressource" und definiert den Schritt im API-Ablauf, in dem der Java-Code ausgeführt wird. Sie können Ihre Java-JAR über den Proxy-Editor der Proxy-Benutzeroberfläche hochladen oder die Datei in das Verzeichnis /resources/java in API-Proxys aufnehmen, die Sie lokal entwickeln.
  • Für einfache Vorgänge wie API-Aufrufe an Remote-Dienste empfehlen wir die Verwendung der ServiceCallout-Richtlinie. Siehe Service Callout-Richtlinie.
  • Für relativ einfache Interaktionen mit Nachrichteninhalten, z. B. das Ändern oder Extrahieren von HTTP-Headern, Parametern oder Nachrichteninhalten, empfiehlt Apigee die Verwendung einer JavaScript-Richtlinie.