Créer un appel Java

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

Consultez la documentation d'Apigee Edge.

Qu'est-ce qu'un appel Java ?

Apigee propose un éventail de règles qui répondent aux exigences courantes en termes 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.

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

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 à Apigee permettant 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 stratégies 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 Apigee. 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édez 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 les bibliothèques Java incluses dans Apigee et ne vous y fiez pas. Ces bibliothèques ne sont utilisées que par les fonctionnalités du produit Apigee ; il n'est pas garanti qu'une bibliothèque soit disponible d'une version à la suivante. Si vous utilisez de telles bibliothèques, ne le faites que lors de démonstrations hors production.

Appel Java "Hello"

Examinons 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. Si api-platform-samples est déjà installé sur votre système, exécutez une commande pull pour vous assurer que vous disposez de la dernière version.
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'appel Apigee 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 : L'objet MessageContext vous permet d'accéder aux entités d'un flux où s'exécute la règle 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 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

Assurez-vous que Maven est installé :
```
mvn -version
```

Installez les dépendances JAR requises dans votre dépôt local Maven à l'aide de l'une des méthodes suivantes :

Ajoutez l'extrait suivant au fichier pom.xml pour télécharger les dépendances JAR requises à partir d'Artifact Registry :

<repositories>
  <repository>
    <id>artifact-registry</id>
    <url>https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.apigee.gateway.libraries</groupId>
    <artifactId>message-flow</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
  <dependency>
    <groupId>com.apigee.infra.libraries</groupId>
    <artifactId>expressions</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
</dependencies>

Utilisez les appels curl suivants pour télécharger les dépendances JAR requises à partir d'Artifact Registry :

curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/gateway/libraries/message-flow/1.0.0/message-flow-1.0.0.jar" -v -L -o message-flow-1.0-0.jar

curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/infra/libraries/expressions/1.0.0/expressions-1.0.0.jar" -v -L -o expressions-1.0.0.jar

Exécutez le script java-hello/buildsetup.sh. Ce script télécharge les dépendances JAR requises à partir du dépôt GitHub d'Apigee.

Accédez au répertoire java-hello/callout à l'aide de la commande cd.
Exécutez Maven :
```
mvn clean package
```
Remarque : Si vous obtenez une erreur Maven, vérifiez que vous êtes bien 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.

Déployer et appeler le proxy

Pour déployer et tester le proxy d'API, procédez comme suit :

Accédez au répertoire java-hello.

Compressez le groupe de proxys d'API :

zip apiproxy-bundle.zip -r apiproxy -x \*.\*~

Le moyen le plus simple de déployer le proxy consiste à le compacter en un fichier zip et à importer celui-ci dans un environnement de votre organisation Apigee. Pour plus d'informations, consultez la page Créer un proxy d'API. Veillez à sélectionner l'option Upload Proxy Bundle (Importer le package de proxy). Pour plus d'informations, consultez également les conseils et astuces pour importer un proxy d'API sous forme de package de la communauté Apigee.
Une fois le proxy déployé, appelez-le à l'aide de la commande suivante :
```
curl  https://$HOSTNAME/java-hello -H "username:Will"
```
Celui-ci renvoie "Hello, Will!".

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