JavaCallout-Richtlinie

<ph type="x-smartling-placeholder"></ph> Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie 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 finden Sie 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 Implementieren von benutzerdefiniertem Verhalten, das nicht von anderen standardmäßigen Edge-Richtlinien abgedeckt wird.

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.

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

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

 N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

 false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

 true Optional
async

This attribute is deprecated.

 false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.
Presence Optional
Type 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: –
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: –
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 Edge 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. See also Supported software and supported versions.
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-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 für die Funktionen des Edge-Produkts. Es gibt keine Garantie, dass eine Bibliothek von Release zu Release verfügbar sein.
  • 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