Règle JavaCallout

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

La règle JavaCallout vous permet d'utiliser Java pour mettre en œuvre un comportement personnalisé non prédéfini dans les règles Apigee. Dans votre code Java, vous pouvez accéder aux propriétés des messages (en-têtes, paramètres de requête, contenu), obtenir et définir des variables de flux, exécuter une logique personnalisée et gestion des exceptions, extraire des données à partir de requêtes ou de réponses, et plus encore. Si vous débutez avec cette règle, consultez Créer un appel Java.

Vous pouvez empaqueter votre application Java avec les fichiers JAR de package dont vous avez besoin. Notez qu'il existe certaines restrictions sur ce que vous pouvez faire avec JavaCallout. Elles sont répertoriées dans la section Restrictions.

Les versions de Java compatibles incluent : Oracle JDK 11 et OpenJDK 11.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Exemples

Exemples généraux

Pour obtenir un exemple simple d'utilisation d'un appel Java, consultez Créer un appel Java.

Pour savoir comment définir des variables de flux dans votre code Java, consultez cet article de la communauté Apigee sur le débogage des appels Java.

Récupérer les propriétés dans votre code Java

Cet exemple montre comment utiliser l'attribut name de l'élément <Property> pour spécifier le nom permettant d'accéder à la propriété à partir du code Java.

La valeur de l'élément <Property> (la valeur entre les balises d'ouverture et de fermeture) correspond à la valeur qui sera reçue par le code Java. La valeur doit être une chaîne. Vous ne pouvez pas référencer une variable de flux pour obtenir la valeur.

La configuration nécessite deux éléments :

  • Configurez la propriété. Ici, la valeur de la propriété est le nom de la variable 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>
  • Dans votre code Java, implémentez le constructeur suivant sur la classe Execution :
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

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

Documentation de référence des éléments

La documentation de référence des éléments décrit les éléments et les attributs de la règle JavaCallout.

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

Attributs <JavaCallout>

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

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Attribut Description Par défaut Présence
name

Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères.

Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.

 Non disponible Obligatoire
continueOnError

Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles.

Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir également :

 false Facultatif
enabled

Définissez sur true pour appliquer la règle.

Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée, même si elle reste associée à un flux.

 true Facultatif
async

Cet attribut est obsolète.

 faux Obsolète

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour ajouter un libellé à la règle dans l'éditeur de proxys de l'interface utilisateur de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>
Par défaut

Non disponible

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.
Présence Facultatif
Type Chaîne

Élément <ClassName>

Spécifie le nom de la classe Java qui s'exécute lors de l'application de la règle JavaCallout. La classe doit être incluse dans le fichier JAR spécifié par <ResourceURL>. Consultez également Créer un appel Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Valeur par défaut : N/A
Présence : Requis
Type : Chaîne

Élément <Properties>

Ajoute des propriétés auxquelles vous pouvez accéder à partir du code Java lors de l'exécution.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Valeur par défaut : Aucun
Présence : Facultatif
Type : Chaîne

Élement <Property>

Spécifie une propriété à laquelle vous pouvez accéder à partir du code Java lors de l'exécution. Vous devez spécifier une valeur de chaîne littérale pour chaque propriété. Vous ne pouvez pas référencer des variables de flux dans cet élément. Pour obtenir un exemple fonctionnel utilisant des propriétés, consultez la section Utiliser des propriétés dans une règle JavaCallout.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Valeur par défaut : Aucun
Présence : Facultatif
Type : Chaîne

Attributs

Attribut Description Par défaut Présence
nom

Spécifie le nom de la propriété.

 N/A Obligatoire.

Élément <ResourceURL>

Cet élément spécifie le fichier Java JAR qui s'exécutera lors de l'exécution de la règle JavaCallout.

Vous pouvez stocker ce fichier au niveau du proxy d'API (sous /apiproxy/resources/java dans le bundle de proxys d'API ou dans la section Scripts du volet de navigation de l'éditeur de proxy d'API), ou aux niveaux de l'organisation ou de l'environnement afin de le réutiliser sur plusieurs proxys d'API, comme décrit dans la section Fichiers de ressources.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Valeur par défaut : Aucun
Présence : Requis
Type : Chaîne

Informations de référence sur les erreurs

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>

Schémas

Compiler et déployer

Pour découvrir comment compiler votre code Java personnalisé et le déployer avec un proxy, consultez la section Créer un appel Java.

Restrictions

Voici les restrictions à prendre en compte lorsque vous écrivez du code d'appel Java :

  • La plupart des appels système ne sont pas autorisés. Par exemple, vous ne pouvez pas effectuer de lectures ou d'écritures du système de fichiers internes.
  • Accès au réseau via des sockets. Apigee restreint l'accès aux adresses sitelocal, anylocal, loopback et linklocal.
  • L'appel ne peut pas obtenir d'informations sur le processus actuel, la liste des processus ou l'utilisation du processeur/de la mémoire sur la machine. Bien que certains de ces appels puissent être fonctionnels, ils ne sont pas acceptés et sont susceptibles d'être désactivés à tout moment. Pour assurer la compatibilité ascendante, vous devez éviter d'effectuer de tels appels dans votre code.
  • La dépendance aux bibliothèques Java incluses dans Apigee n'est pas compatible. Ces bibliothèques sont réservées aux fonctionnalités du produit Apigee, et rien ne garantit qu'elles seront disponibles à partir des versions.
  • N'utilisez pas io.apigee ou com.apigee comme noms de package dans les appels Java. Ceux-ci sont réservés et utilisés par d'autres modules Apigee.

Empaqueter

Placez le fichier JAR dans un proxy d'API sous /resources/java. Si votre code JavaCallout s'appuie sur des bibliothèques tierces supplémentaires empaquetées sous forme de fichiers JAR indépendants, placez également ces fichiers JAR dans le répertoire /resources/java pour vous assurer qu'ils sont chargés correctement lors de l'exécution.

Si vous utilisez l'interface utilisateur de gestion pour créer ou modifier le proxy, ajoutez une ressource et spécifiez un fichier JAR dépendant supplémentaire. S'il existe plusieurs fichiers JAR, ajoutez-les simplement en tant que ressources supplémentaires. Vous n'avez pas besoin de modifier la configuration de la stratégie pour faire référence à des fichiers JAR supplémentaires. Nous vous recommandons de les placer dans /resources/java.

Pour plus d'informations sur l'importation de fichiers JAR Java, consultez la page Fichiers de ressources.

Pour obtenir un exemple détaillé illustrant comment empaqueter et déployer des règles JavaCallout à l'aide de Maven ou de javac, consultez Créer un appel Java.

Javadoc

La documentation Javadoc sur l'écriture du code d'appel Java est disponible sur GitHub. Il vous faudra cloner ou télécharger le code HTML sur votre système, puis ouvrir simplement le fichier index.html dans un navigateur.

Remarques sur l'utilisation et bonnes pratiques

  • Lorsque vous utilisez plusieurs règles JavaCallout, envisagez d'importer des fichiers JAR courants en tant que ressources au niveau de l'environnement. Cette pratique est plus efficace que l'empaquetage des mêmes fichiers JAR avec plusieurs groupes de proxys lors du déploiement dans le même environnement.
  • Évitez d'empaqueter et de déployer plusieurs copies ou versions du même fichier JAR dans un environnement. Par exemple, Apigee recommande d'éviter les actions suivantes :
    • Déployer le même fichier JAR dans le cadre d'un bundle de proxys et en tant que ressource d'environnement.
    • Déployer une version d'un fichier JAR en tant que ressource d'environnement et une autre dans le cadre d'un bundle de proxys.

    Le fait de déployer plusieurs copies d'un même fichier JAR peut entraîner un comportement non déterministe au moment de l'exécution en raison de conflits potentiels de ClassLoader.

  • Une règle JavaCallout ne contient pas de code réel. À la place, la règle référence une "ressource" Java et définit l'étape du flux d'API où le code Java s'exécute. Vous pouvez importer votre JAR Java via l'éditeur de proxy de l'UI de gestion ou l'inclure dans le répertoire /resources/java des proxys d'API que vous développez localement.
  • Pour les opérations légères, telles que les appels d'API aux services distants, nous vous recommandons d'utiliser la règle ServiceCallout. Consultez la Stratégie d'appel de service.
  • Pour les interactions relativement simples avec le contenu des messages, telles que la modification ou l'extraction d'en-têtes HTTP, de paramètres ou du contenu des messages, Apigee recommande d'utiliser une règle JavaScript.