JavaCallout-Richtlinie

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

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.

Informationen zu den unterstützten Java-Versionen findest du unter Unterstützte Software und unterstützte Versionen.

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 von keiner anderen Edge-Standardrichtlinie 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.

Samples

Einfaches Beispiel

Java-Callouts 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 den folgenden Konstruktor so in Ihrem Java-Code für die Implementierung der Ausführungsklasse:
    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.

Elementreferenz

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 das erwartete Verhalten.

Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird.

 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 Eingestellte Funktionen

<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 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>
Standardwert: –
Präsenz: Erforderlich
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>
Standardwert: Keine
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 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>
Standardwert: Keine
Präsenz: Erforderlich
Typ: String

Fehlerreferenz

In diesem Abschnitt werden die Fehlercodes und Fehlermeldungen beschrieben, die zurückgegeben werden, sowie die Fehlervariablen, die von Edge festgelegt werden, wenn diese 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 Problembehebung
steps.javacallout.ExecutionError 500 Tritt auf, wenn der Java-Code während der Ausführung einer JavaCallout-Richtlinie eine Ausnahme auslöst oder Null 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. Siehe auch Unterstützte Software und unterstützte Versionen.
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 Edge enthalten sind, wird nicht unterstützt. Diese Bibliotheken dienen nur der Funktion von Edge-Produkten. Es gibt keine Garantie, dass eine Bibliothek von Release zu 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

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

Weitere Informationen