Cette page a été traduite par l'API Cloud Translation.

Créer un appel Java

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

Qu'est-ce qu'un appel Java ?

Apigee Edge fournit une gamme de règles qui répondent aux exigences courantes de gestion des API : (sécurité, transformation des données, gestion du trafic, etc.).

Cependant, dans certains cas, votre API nécessite un comportement personnalisé qui n'est pas mis en œuvre dans une règle standard. Dans ces cas, Apigee propose plusieurs options qui vous permettent de créer un script ou un code pour un comportement d'API personnalisé. Une approche consiste à mettre en œuvre le comportement souhaité dans Java.

Pour connaître les versions compatibles de Java, consultez la section logiciels et versions compatibles.

Comment utiliser le code Java dans un proxy ?

Une règle Java permet d'appeler du code Java à partir d'un flux proxy en cours d'exécution. Votre Java le code doit implémenter certaines interfaces Java spécifiques à Edge qui lui permettent d'interagir avec le proxy d'exécution. Par exemple, des méthodes Java existent pour obtenir et définir des en-têtes, des paramètres de requête, des variables de flux et d'autres entités dans le contexte de flux actuel du proxy.

Quand dois-je utiliser un appel Java ?

Examinons les situations dans lesquelles les appels Java sont utiles et les situations dans lesquelles vous devez envisager d'autres approches.

Commençons par envisager d'autres méthodes

Avant d'utiliser un appel Java, notez que d'autres méthodes peuvent être utilisées à la place. Exemple :

Pour les opérations légères, telles que les appels d'API HTTP à des services distants, vous pouvez 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, vous pouvez utiliser les langages JavaScript ou Python.

Actions possibles dans le code Java

Un appel Java prend en charge les opérations de base suivantes :

Examiner ou manipuler des messages de requête ou de réponse
Obtenir et définir des variables de flux Vous pouvez utiliser des méthodes Java pour accéder aux variables de flux Edge. Si vous souhaitez accéder aux informations d'un mappage de valeurs-clés (KVM), utilisez une stratégie KVM, attribuez des valeurs KVM aux variables de flux. Vous pouvez ensuite accéder aux variables de flux depuis l'appel Java.
Appeler des services externes
Signaler des pannes
Manipuler des messages d'erreur et des codes d'état

Actions impossibles dans le code Java

La plupart des appels système ne sont pas autorisés. En revanche, vous ne pouvez pas :

effectuer des opérations de lecture ou d'écriture dans le système de fichiers interne. Vous ne pouvez donc pas utiliser les packages Java pour lire ou écrire dans des systèmes de fichiers internes. Cependant, vous pouvez effectuer des appels distants externes ;
obtenir des informations sur le processus en cours, la liste des processus ou l'utilisation du processeur/de la mémoire de la machine ;
accéder au code source dans "expressions-1.0.0.jar" et "message-flow-1.0.0.jar".

Bien que certains de ces appels puissent fonctionner, ils ne sont pas pris en charge et sont désactivés à tout moment. Évitez de passer de tels appels dans votre code.

N'utilisez pas ou ne vous appuyez pas sur les bibliothèques Java incluses dans Apigee Edge. Ces bibliothèques sont pour les fonctionnalités du produit Edge uniquement, et rien ne garantit qu'une bibliothèque sera disponible d'une version à l'autre. Si vous utilisez de telles bibliothèques, ne le faites que lors de démonstrations hors production.

Appel Java "Hello"

Étudions un exemple de base d'appel Java "Hello World". Dans cet exemple, nous créons un proxy simple et un appel Java renvoyant une réponse "hello world". Le proxy ne peut renvoyer que l'une de ces deux réponses :

Si vous transmettez un "nom d'utilisateur" en-tête contenant un "nom" , le proxy renvoie:
```
Hello, <name>!
```
Si vous omettez l'en-tête, le proxy renvoie simplement:
```
"Hello, Guest!"
```

Télécharger le projet de démarrage

Pour vous faciliter la tâche, nous avons préparé un projet de base sur GitHub dans le dépôt Apigee api-platform-samples.

Téléchargez ou clonez api-platform-samples sur votre système.
Dans le terminal ou l'éditeur de code de votre choix, accédez au projet api-platform-samples/doc-samples/java-hello.

Écrire le code Java

Ouvrez le fichier source Java : java-hello/callout/src/main/java/HelloJava.java. Ce fichier est une version squelette de la classe Java principale que nous mettrons en œuvre. L'élément importé les packages sont requis pour le code Edge Java Accroche. Ces classes fournissent des méthodes qui vous permettent d'accéder au contexte d'exécution du proxy. Nous vous accompagnerons bientôt dans la compilation et le déploiement de ce code.

package com.apigeesample;

import com.apigee.flow.execution.ExecutionContext;
import com.apigee.flow.execution.ExecutionResult;
import com.apigee.flow.execution.spi.Execution;
import com.apigee.flow.message.MessageContext;


public class HelloJava implements Execution {

        public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
                
                try {

                        // Your code here.
            
            return ExecutionResult.SUCCESS;

                } catch (Exception e) {
                        return ExecutionResult.ABORT;
                }
        }

}

Remplacez la ligne commentée // Your code here par le code suivant:
```
String name = messageContext.getMessage().getHeader("username");

if (name != null && name.length()>0) {
        messageContext.getMessage().setContent("Hello, " + name + "!");
        messageContext.getMessage().removeHeader("username");
} else {
        messageContext.getMessage().setContent("Hello, Guest!");
}
```
Remarque:Remarque:MessageContext vous permet d'accéder aux entités à l'intérieur du flux où s'exécute la règle Java Call. Imaginons que la règle d'appel Java est associée au flux de réponse de point de terminaison du proxy. Le code répertorié ci-dessus récupère l'objet de message HTTP pour ce contexte de flux. Le Message vous donne accès aux en-têtes, aux paramètres de requête, au contenu du corps et au flux variables.
Enregistrez le fichier.

Compiler le code avec Maven

Le projet est configuré pour que vous puissiez le compiler avec Maven. Si vous souhaitez utiliser javac, un exemple suit l'exemple Maven.

Assurez-vous que Maven est installé:
```
mvn -version
```
Exécutez le script java-hello/buildsetup.sh. Ce script installe les dépendances JAR requises dans votre dépôt local Maven.
Accédez au répertoire java-hello/callout à l'aide de la commande cd.
Exécutez Maven:
```
mvn clean package
```
Remarque:Si une erreur Maven s'affiche, assurez-vous d'être dans le Répertoire java-hello/callout.
Si vous le souhaitez, vérifiez que le fichier JAR edge-custom-policy-java-hello.jar a bien été copié dans le répertoire java-hello/apiproxy/resources/java. C'est à cet emplacement que doivent se trouver les fichiers JAR que vous souhaitez déployer avec un proxy.

Compiler avec javac (facultatif)

Dans la section précédente, vous générez automatiquement le fichier Java JAR requis à l'aide d'une commande Maven. Si vous souhaitez utiliser javac pour compiler le code, vous pouvez également effectuer une action semblable à celle-ci (à partir du répertoire java-hello). Les fichiers JAR requis sont fournis dans le répertoire java-hello/lib.

Accédez au répertoire api-platform-samples/doc-samples/java-hello à l'aide de la commande cd.
Assurez-vous que javac se trouve dans la variable PATH.
```
javac -version
```

Exécutez la commande javac suivante:

javac -d . -classpath ./lib/expressions-1.0.0.jar:./lib/message-flow-1.0.0.jar:. callout/src/main/java/HelloJava.java

Cette opération crée com/apigeesample/HelloJava.class.

Créez un fichier JAR contenant la classe compilée dans le répertoire apiproxy/resources/java. C'est à cet emplacement que doivent se trouver les fichiers JAR que vous souhaitez déployer avec un proxy. Pour ce faire, exécutez la commande suivante dans le répertoire java-hello (n'oubliez pas le point à la fin).
```
jar cvf apiproxy/resources/java/edge-custom-policy-java-hello.jar -C com .
```

Déployer et appeler le proxy

Un script de déploiement est fourni dans le répertoire ./java-hello. Mais avant de l'exécuter, vous devez effectuer une configuration rapide.

Accédez au répertoire api-platform-samples/doc-samples/java-hello à l'aide de la commande cd.
Si vous ne l'avez pas déjà fait, ouvrez le fichier ../../setup/setenv.sh et modifiez-le comme indiqué dans vos informations de compte Apigee: votre nom d'utilisateur (l'adresse e-mail associé à votre compte), le nom de votre organisation et le domaine que vous utilisez pour créer l'API de gestion de projet. Par exemple, pour le cloud Edge, le domaine est https://api.enterprise.apigee.com; Cependant, votre domaine peut être différent à l'aide de Edge Private Cloud.
Enregistrez le fichier setenv.sh.
Exécutez le script de déploiement:
```
./deploy.sh
```
Si le déploiement réussit, exécutez le script d'appel:
```
./invoke.sh
```
Le script d'appel appelle une commande cURL qui se présente comme suit:
```
curl  http://$org-$env.$api_domain/java-hello -H "username:Will"
```
Celui-ci renvoie "Hello, Will!".

Vous pouvez modifier le nom du script invoke.sh ou, si vous changez le cURL pour supprimer l'en-tête, la commande renvoie "Hello, Guest!"

À propos du proxy

Examinons rapidement les règles utilisées par ce proxy. Soyez attentif à l'emplacement des règles dans le flux de proxy et aux raisons pour lesquelles elles s'y trouvent.

Règle d'attribution de messages

Une règle d'attribution de messages est associée au flux de requêtes ProxyEndpoint. Elle copie l'en-tête du nom d'utilisateur de la requête et l'attribue à la réponse. Cette opération permet à la règle d'appel Java, qui est associée au flux de réponse, à accéder à l'en-tête du nom d'utilisateur et à créer un corps de réponse personnalisé à l'aide de la valeur de cet en-tête.

<AssignMessage async="false" continueOnError="false" enabled="true" name="CopyHeader">     
    <DisplayName>CopyHeader</DisplayName>     
    <Copy source="request">         
        <Headers>             
          <Header name="username"/>         
        </Headers>     
    </Copy>     
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>     
    <AssignTo createNew="false" transport="http" type="response"/> 
</AssignMessage>

Règle d'appel Java

La règle d'appel Java est associée au flux de réponse. En effet, le code Java personnalisé modifie les en-têtes et le message de la réponse. L'élément ClassName de la règle spécifie la classe principale exécutée par la règle. L'élément ResourceURL est le nom du fichier JAR que vous avez créé et ajouté au répertoire resources/java du proxy.

<JavaCallout name="hello-java">         
    <ClassName>com.apigeesample.HelloJava</ClassName>         
    <ResourceURL>java://edge-custom-policy-java-hello.jar</ResourceURL> 
</JavaCallout>

Ce qu'il faut retenir d'un appel Java

Voici quelques points importants à retenir concernant l'implémentation d'un appel Java :

Importe des classes à partir des packages com.apigee.flow.execution et com.apigee.flow.message. Ces packages doivent être inclus dans le fichier JAR empaqueté et déployé. 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.
Il met en œuvre l'interface "Execution". Tout code Java exécuté dans un proxy d'API doit mettre en œuvre "Execution".
Une règle d'appel Java ne contient pas de code réel. À la place, une règle d'appel Java fait référence à une "ressource" Java, que vous devez empaqueter dans un fichier JAR.
Noms de packages à éviter : 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.
Si votre appel Java repose sur des bibliothèques tierces supplémentaires empaquetées sous forme de fichiers JAR indépendants, placez ces fichiers JAR dans le répertoire /resources/java pour vous assurer qu'ils sont chargés correctement lors de l'exécution.
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.