Règle JavaCallout

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

Consultez la documentation d'Apigee Edge.

icône de la règle

Événement

Cette règle 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) et aux variables de flux du flux du proxy. Si vous débutez avec cette règle, consultez la section Créer un appel Java.

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.

Date

Pour obtenir des consignes, consultez la section "Dans quels cas utiliser un appel Java ?" de la page Créer un appel Java.

À propos

La règle d'appel Java vous permet d'obtenir et de définir des variables de flux, d'exécuter une logique personnalisée et de gérer les exceptions, d'extraire des données à partir de requêtes ou de réponses, et plus encore. Cette règle vous permet de mettre en œuvre un comportement personnalisé qui n'est couvert par aucune autre règle Apigee standard.

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 un appel Java. Elles sont répertoriées ci-dessous dans la section Restrictions.

Exemples

Exemple simple

Créer un appel Java

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

L'élément <Property> de la règle vous permet de spécifier une paire nom/valeur que vous pouvez récupérer au moment de l'exécution dans votre code Java. Pour obtenir un exemple fonctionnel utilisant des propriétés, consultez la section Utiliser des propriétés dans un appel Java.

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

  • 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>
</Javascript>
  • Dans votre code Java, mettez en œuvre le constructeur suivant classe d'exécution :
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

Définir des variables de flux dans le code Java

Pour obtenir une description claire de la définition de variables dans le contexte de messages (variables de flux) dans votre code Java, consultez cet post destiné à la communauté Apigee.

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

 false 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.
Presence 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 : Non disponible
Présence : Obligatoire
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 un appel Java.

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

Attributs

Attribut Description Par défaut Presence
nom

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

 Non disponible 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 d'appel Java.

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 : Obligatoire
Type : Chaîne

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Code d'erreur État HTTP Cause Corriger
steps.javacallout.ExecutionError 500 Se produit lorsque le code Java génère une exception ou renvoie une valeur nulle lors de l'exécution d'une règle JavaCallout policy.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque le proxy contenant la règle est déployé.

Nom de l'erreur Chaîne d'erreur État HTTP Se produit quand
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A Le fichier spécifié dans l'élément <ResourceURL> n'existe pas.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A Le fichier de classe spécifié dans l'élément <ClassName> n'est pas dans le fichier JAR.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A Voir la chaîne d'erreur. Les versions de Java prises en charge incluent : Oracle JDK 7/8 et OpenJDK 7/8
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A Voir la chaîne d'erreur.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A Voir la chaîne d'erreur.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A Voir la chaîne d'erreur.
NoResourceForURL Could not locate a resource with URL [string] N/A Voir la chaîne d'erreur.

Variables de panne

Ces variables sont définies lorsque cette règle déclenche une erreur. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variables Lieu Exemple
fault.name="fault_name" fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. javacallout.JC-GetUserData.failed = true

Exemple de réponse d'erreur

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

Exemple de règle de défaillance

<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 lors de l'écriture d'appels 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 règle 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 un appel Java à l'aide de Maven ou de javac, consultez la page 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 appels Java, 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 d'appel Java ne contient pas de code réel. À la place, une règle d'appel Java 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.