JavaCallout-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Mit der JavaCallout-Richtlinie können Sie Java verwenden, um benutzerdefiniertes Verhalten zu implementieren, das von den Apigee-Richtlinien nicht vorkonfiguriert ist. In Ihrem Java-Code können Sie auf Nachrichtenattribute (Header, Abfrageparameter, Inhalt) zugreifen, Ablaufvariablen abrufen und festlegen, benutzerdefinierte Logik ausführen und Fehlerbehandlung durchführen, Daten aus Anfragen oder Antworten extrahieren und vieles mehr. Wenn Sie diese Richtlinie zum ersten Mal verwenden, lesen Sie die Informationen unter Java-Erweiterung erstellen.

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

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.

Beispiele

Allgemeine Beispiele

Ein einfaches Beispiel für die Verwendung eines Java-Callouts finden Sie unter Java-Callout erstellen.

Informationen zum Festlegen von Ablaufvariablen in Ihrem Java-Code finden Sie in diesem Apigee-Community-Beitrag zum Debuggen von Java-Callouts.

Attribute in Ihrem Java-Code abrufen

In diesem Beispiel wird gezeigt, wie Sie mit dem name-Attribut des <Property>-Elements den Namen angeben, mit dem über Java-Code auf das Attribut zugegriffen werden soll.

Der Wert des <Property>-Elements (der Wert zwischen dem öffnenden und dem schließenden 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.

Für die Konfiguration sind zwei Teile erforderlich:

  • 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>
</JavaCallout>
  • Implementieren Sie in Ihrem Java-Code den folgenden Konstruktor für die Ausführungsklasse:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

            // Extract property values from map.
    }
    ...
}

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 Präsenz
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:

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

 wahr 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.
Präsenz Optional
Typ String

<ClassName>-Element

Gibt den Namen der Java-Klasse an, die beim Ausführen der JavaCallout-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 einer JavaCallout-Richtlinie verwenden.

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

<ResourceURL>-Element

Dieses Element gibt die Java JAR-Datei an, die ausgeführt wird, wenn die JavaCallout-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

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.

Fault code HTTP status Cause Fix
steps.javacallout.ExecutionError 500 Occurs when Java code throws an exception or returns null during the execution of a JavaCallout policy.

Deployment errors

These errors can occur when the proxy containing the policy is deployed.

Error name Fault string HTTP status Occurs when
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A The file specified in the <ResourceURL> element does not exist.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A The class file specified in the <ClassName> element is not in the jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A See fault string. Supported Java versions include: Oracle JDK 7/8 and OpenJDK 7/8
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A See fault string.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A See fault string.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A See fault string.
NoResourceForURL Could not locate a resource with URL [string] N/A See fault string.

Fault variables

These variables are set when this policy triggers an error. 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 "ExecutionError"
javacallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javacallout.JC-GetUserData.failed = true

Example error response

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

Example fault rule

<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-Callout-Code 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 JavaCallout-Code 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 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 JavaCallout-Richtlinien mit Maven oder Javac verpackt und bereitgestellt werden, 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 JavaCallout-Richtlinien 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 JavaCallout-Richtlinie enthält keinen tatsächlichen Code. Stattdessen verweist die 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.