Règle JavaCallout

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Quoi

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.

Pour connaître les versions compatibles de Java, consultez la page Logiciels et versions compatibles.

Date

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

About

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 erreurs, d'extraire des données à partir de requêtes ou de réponses, et plus encore. Cette règle vous permet implémenter un comportement personnalisé qui n'est couvert par aucune autre règle Edge 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, implémentez le constructeur suivant sur la classe Execution. comme suit:
    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 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.

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

 faux Facultatif
enabled

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

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

 vrai Facultatif
async

Cet attribut est obsolète.

 faux Obsolète

Élément <DisplayName>

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

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

ND

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 : ND
Présence : Requis
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 : None
Présence : Facultatif
Type : Chaîne

Attributs

Attribut Description Par défaut Présence
nom

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

 ND 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 : None
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 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>

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.
  • Le recours aux bibliothèques Java incluses dans Apigee Edge n'est pas pris en charge. Ces les bibliothèques sont destinées uniquement aux fonctionnalités du produit Edge et il n'y a aucune garantie qu'une bibliothèque d'une version à l'autre.
  • 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

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

Articles associés