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

Créer un appel Java

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

Qu'est-ce qu'un appel Java ?

Apigee Edge propose une gamme de règles répondant aux exigences courantes de gestion des API, telles que la sécurité, la transformation des données, la 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 page 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 code Java doit mettre en œuvre certaines interfaces Java spécifiques à Edge qui permettent au code d'interagir avec le proxy en cours 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 les 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 et n'utilisez pas les bibliothèques Java incluses dans Apigee Edge. Ces bibliothèques sont destinées aux 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 en-tête "username" avec une valeur "name", 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. Les packages importés sont requis pour le code d'accroche Edge Java. 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:L'objet MessageContext vous permet d'accéder aux entités du flux où s'exécute la stratégie d'appel Java. 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. L'objet Message vous donne à son tour accès aux en-têtes, aux paramètres de requête, au contenu du corps et aux variables de flux.
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, vérifiez que vous vous trouvez 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

Cela 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 en ajoutant les informations de votre compte Apigee: votre nom d'utilisateur (l'adresse e-mail associée à votre compte), le nom de votre organisation et le domaine que vous utilisez pour effectuer des appels de gestion des API. Par exemple, pour le cloud Edge, le domaine est https://api.enterprise.apigee.com. Cependant, votre domaine peut être différent si vous utilisez un cloud privé Edge.
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 script invoke.sh pour changer le nom ou, si vous modifiez l'appel 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.