Exercice : configurer votre application Java à l’aide de Maven

15 minutes

Dans cette unité, vous allez créer une application de console de base à l’aide de l’IDE de votre choix pour modifier le code. Vous pouvez éventuellement utiliser le terminal de votre choix pour exécuter le code.

Créer des ressources Azure Cosmos DB

Pour vous permettre de suivre ce labo, Microsoft Learn fournit un bac à sable (sandbox) Azure gratuit dans lequel vous pouvez créer des comptes et des ressources. Vous allez configurer un compte Azure Cosmos DB dans cet abonnement, puis créer une base de données et un conteneur.

Connectez-vous au portail Azure en utilisant le même compte que celui avec lequel vous avez activé le bac à sable.
Dans le Portail Azure, créez un compte Azure Cosmos DB en lui attribuant le nom de votre choix. Lorsque vient le moment de choisir un groupe de ressources pour votre compte, recherchez le groupe de ressources [groupe de ressources sandbox], puis sélectionnez-le.
Dans votre compte Azure Cosmos DB, créez une base de données nommée Utilisateurs.
Dans la base de données Users, créez un conteneur appelé WebCustomers avec une clé de partition de /userId. Provisionnez 400 RU/s pour WebCustomers.

Créer un répertoire de travail

Nous vous fournissons un modèle pour votre application Java. Clonez le référentiel du modèle sur votre système.
```
git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git
```
Ouvrez l’Explorateur de fichiers Windows et accédez au référentiel cloné. Entrez le sous-répertoire java_lab.

Important

Pour ce module, la totalité de votre travail se trouvera dans le sous-répertoire java_lab.
Le modèle contient un fichier pom.xml Maven qui tire (pull) déjà les dépendances nécessaires à votre projet. Ouvrez ce fichier et examinez-le pour trouver la dépendance ci-dessous :
```
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>LATEST</version>
</dependency>
```
Cette dépendance tire (pull) la version la plus récente du kit de développement logiciel (SDK) Java Azure Cosmos DB. Vous pouvez fermer ce fichier.
Ensuite, vous allez générer et exécuter Hello World. À l’aide de votre IDE ou du terminal, ouvrez ce projet. En fonction de votre IDE, il peut y avoir une option permettant d’ouvrir le fichier pom.xml du sous-répertoire java comme un projet.

Une fois le projet ouvert, accédez à src/main/java/com/azure/cosmos/examples/mslearnbasicapp, puis ouvrez CosmosApp.java, qui est un modèle pour l’application Java que nous allons développer. Il doit se présenter comme suit :
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public final class CosmosApp {

    /** For application to log INFO and ERROR. */
    private static Logger logger = LoggerFactory.getLogger(CosmosApp.class.getSimpleName());

    private CosmosApp() {
        // not called
    }

    /**
    * Main.
    * @param args Command line arguments
    */
    public static void main(final String[] args) {
        logger.info("Hello World.");
    }
}
```
Tel qu’il est actuellement, le code de l’application implémente un simple « Hello World ».
Si votre IDE propose des outils pour générer et exécuter votre application Maven : Générez et exécutez votre application à l’aide de l’IDE, puis vérifiez que l’application enregistre Hello World sur le terminal.
Si vous utilisez le terminal pour générer et exécuter votre application Maven : Utilisez la commande suivante pour générer le projet Maven :
```
mvn clean package
```
Ensuite, exécutez :
```
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"  
```
Vérifiez que l’application enregistre la sortie suivante sur le terminal :
```
INFO: Hello World.
```

Connecter l’application à Azure Cosmos DB

Dans la classe CosmosApp, créez les variables de classe statiques suivantes pour les informations de votre connexion Azure Cosmos DB :

/** Azure Cosmos DB endpoint URI. */
private static String endpointUri = "<your-cosmosdb-hostname>";

/** Azure Cosmos DB primary key. */
private static String primaryKey = "<your-cosmosdb-master-key>";

Revenez au Portail Azure, accédez au volet Clés, puis copiez-collez l’URI du point de terminaison Azure Cosmos DB ainsi que la clé primaire dans les définitions de variables ci-dessus.

Par exemple, si votre URI est https://cosmosacct.documents.azure.com:443/, votre nouvelle attribution de variable se présentera ainsi : private static String endpointUri = "https://cosmosacct.documents.azure.com:443/";. Si votre clé primaire est elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==, votre nouvelle attribution de variable se présentera ainsi : private static String primaryKey = "elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==";.

Créer l’instance CosmosAsyncClient

Il est maintenant temps de créer une instance de CosmosAsyncClient, qui est la représentation côté client du service Azure Cosmos DB. Ce client est utilisé pour configurer et exécuter des requêtes auprès du service.

Dans CosmosApp.java, ajoutez la déclaration de variable statique suivante à la classe CosmosApp :
```
/** Azure Cosmos DB client instance. */
private static CosmosAsyncClient client;

/** Azure Cosmos DB database instance. */
private static CosmosAsyncDatabase database;

/** Azure Cosmos DB container instance. */
private static CosmosAsyncContainer container;
```
Le plus souvent, les classes client, database et container ne sont pas encore importées dans votre fichier java. Il est donc judicieux de s’en occuper à ce stade. Certains IDE peuvent vous permettre d’importer automatiquement des dépendances en fonction du code que vous tapez, ce qui peut être utile ici. En général, si nous vous fournissons un bloc de code à coller, attendez-vous à devoir ajouter des instructions import pour que cela fonctionne.
Créez une méthode private void appelée basicOperations sans arguments dans la classe.

Ajoutez le code suivant pour créer une instanceCosmosAsyncClient dans la méthode basicOperations, puis ajoutez du code pour vérifier que la base de données Utilisateurs existe.

 client = new CosmosClientBuilder()
     .endpoint(endpointUri)
     .key(primaryKey)
     .consistencyLevel(ConsistencyLevel.EVENTUAL)
     .directMode()
     .contentResponseOnWriteEnabled(true)
     .buildAsyncClient();

 database = client.getDatabase("Users");
 container = database.getContainer("WebCustomers");            

 logger.info("Database and container validation complete");

 client.close();

À ce stade, votre méthode basicOperations contient le code permettant d’interagir avec Azure Cosmos DB. Toutefois, cette méthode n’est pas appelée dans main, donc notre application sert toujours à imprimer « Hello World ». Pour vérifier, générez et exécutez CosmosApp.java dans l’IDE, ou exécutez le programme dans le terminal en utilisant :
```
mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"  
```
Vérifiez que l’application enregistre toujours la sortie suivante sur le terminal :
```
INFO: Hello World.
```

Copiez et collez le code suivant dans la méthode main, en remplaçant la ligne logger.info("Hello World."); actuelle.

try {
    CosmosApp p = new CosmosApp();
    p.basicOperations();
} catch (CosmosException e) {
    logger.error("Failed while executing app.", e);
} finally {
    logger.info("End of demo, press any key to exit.");
}

Cette opération déclenche le code Azure Cosmos DB dans notre application.

Générez et exécutez CosmosApp.java dans l’IDE ou exécutez le programme sur le terminal à l’aide de :
```
mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"  
```
Vous pouvez voir un grand nombre de messages du journal dans le terminal, dont certains sont générés par le kit de développement logiciel (SDK) lui-même. Lisez-les pour vérifier que l’application enregistre le résultat suivant sur le terminal :
```
INFO: Database and container validation complete
```

Dans cette unité, vous avez configuré les éléments de base de votre application Java Azure Cosmos DB. Vous avez configuré votre application Maven, vous avez créé un projet « Hello World » de base et vous l’avez étendu pour connecter le projet au point de terminaison Azure Cosmos DB.

Nous vous fournissons un modèle pour votre application Java. Clonez le dépôt du modèle sur votre système.
```
git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git
```
Ouvrez l’Explorateur Windows et accédez au dépôt cloné. Entrez le sous-répertoire spring_lab.

Important

Pour ce module, la totalité de votre travail se trouvera dans le sous-répertoire spring_lab.
Le modèle contient un fichier pom.xml Maven qui tire (pull) déjà les dépendances nécessaires à votre projet. Ouvrez ce fichier et examinez-le pour trouver la dépendance ci-dessous :
```
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-spring-data-cosmos</artifactId>
  <version>LATEST</version>
</dependency>
```
Cette dépendance tire (pull) la version la plus récente du kit de développement logiciel (SDK) Spring Data Azure Cosmos DB. Vous pouvez fermer ce fichier.

Connecter l’application à Azure Cosmos DB

À l’aide de votre IDE ou du terminal, ouvrez ce projet. En fonction de votre IDE, il peut y avoir une option permettant d’ouvrir le fichier pom.xml du sous-répertoire spring comme un projet. Une fois le projet ouvert, accédez à src/main/resources/ à l’aide d’un outil d’explorateur de fichiers. Vous devriez voir un fichier nommé application.properties.rename. Spring Data met en évidence les fichiers de configuration par rapport aux paramètres de configuration codés en dur. Afin de créer le fichier de configuration pour votre projet Spring Data, copiez application.properties.rename dans application.properties, puis ouvrez le nouveau fichier application.properties. Vous devriez voir s’afficher le message suivant :
```
cosmos.uri=${ACCOUNT_HOST}
cosmos.key=${ACCOUNT_KEY}
cosmos.secondaryKey=${SECONDARY_ACCOUNT_KEY}

dynamic.collection.name=spel-property-collection
# Populate query metrics
cosmos.queryMetricsEnabled=true
```
Vous allez remplir ${ACCOUNT_HOST} et ${ACCOUNT_KEY} à l’aide d’une méthode de votre choix : en copiant-collant les valeurs dans application.properties, ou en définissant ces variables d’environnement dans votre environnement IDE. Vous trouverez à l’étape suivante les valeurs que ces variables devraient afficher.
Revenez au portail Azure, accédez au volet Clés, puis copiez l’URI du point de terminaison Azure Cosmos DB ainsi que la clé primaire. Comme indiqué à l’étape précédente, utilisez la méthode de votre choix pour assigner votre URI de point de terminaison Azure Cosmos DB et votre clé primaire aux variables mentionnées ci-dessus.

Par exemple, si votre URI est https://cosmosacct.documents.azure.com:443/, et que vous choisissez de coller le point de terminaison et la clé primaire dans application.properties, la ligne dans application.properties se présentera ainsi : cosmos.uri=https://cosmosacct.documents.azure.com:443/. Si votre clé primaire est elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==, le même processus avec votre nouvelle attribution de variable se présentera ainsi : cosmos.key=elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==.

Configurer le client Azure Cosmos DB

Spring Data Azure Cosmos DB instancie automatiquement le client Azure Cosmos DB au démarrage. Le client Azure Cosmos DB est la représentation côté client du service Azure Cosmos DB, utilisé pour exécuter des requêtes auprès du service. Votre code peut configurer le client Azure Cosmos DB avant qu’il ne soit instancié, à l’aide d’un ensemble de méthodes de générateur de requêtes ainsi que des propriétés extraites de application.properties.

Ouvrez CosmosProperties.java. Nous avons fourni ce fichier dans un formulaire rempli : il vous suffit d’examiner son contenu.
```
@ConfigurationProperties(prefix = "cosmos")
public class CosmosProperties {

    private String uri;

    private String key;

    private String secondaryKey;

    private boolean queryMetricsEnabled;

    public String getUri() {
        return uri;
    }

    public void setUri(String uri) {
        this.uri = uri;
    }

    public String getKey() {
        return key;
    }

    public void setKey(String key) {
        this.key = key;
    }

    public String getSecondaryKey() {
        return secondaryKey;
    }

    public void setSecondaryKey(String secondaryKey) {
        this.secondaryKey = secondaryKey;
    }

    public boolean isQueryMetricsEnabled() {
        return queryMetricsEnabled;
    }

    public void setQueryMetricsEnabled(boolean enableQueryMetrics) {
        this.queryMetricsEnabled = enableQueryMetrics;
    }
}
```
Observez les membres de classe uri, key, secondaryKey et queryMetricsEnabled. En revenant à application.properties, vous constatez que les noms de membres CosmosProperties correspondent étroitement aux noms des propriétés application.properties. La classe CosmosProperties présente les accesseurs Get et Set pour le reste de votre application afin d’accéder aux paramètres de configuration à partir de application.properties. Notez qu’il n’existe aucun code ici pour extraire la configuration de application.properties : Spring Data comprend la structure de ce fichier et définit automatiquement les variables membres après l’analyse du fichier de configuration.

À partir de maintenant, nous allons tirer parti de cette configuration lors de la configuration du client Azure Cosmos DB.
Dans CosmosSampleConfiguration.java, examinez la classe CosmosSampleConfiguration et recherchez la méthode cosmosClientBuilder vide :
```
@Bean
public CosmosClientBuilder cosmosClientBuilder() {
    return null;
}
```
Au démarrage, Spring Data appellera automatiquement cette méthode, obtient la valeur CosmosClientBuilder que cette méthode retourne, puis appelle sa méthode build(). À ce stade, une instance CosmosAsyncClient sera créée (en arrière-plan) en fonction des paramètres de configuration contenus dans CosmosClientBuilder. Vous pouvez utiliser cette méthode pour configurer CosmosClientBuilder à l’aide des méthodes de générateur de requêtes.
Notez que nous utilisons l’injection de constructeur (plutôt que l’injection de champs) à l’aide de @Autowired) pour instancier la variable propertieset remplir ses variables membres avec des valeurs analysées à partir du fichier de configuration. Cela garantit que toutes les dépendances requises sont présentes lorsque l’instance de cette classe est créée et facilite l’écriture du code de test à l’avenir.
```
//use constructor injection for spring dependencies 
public CosmosSampleConfiguration(CosmosProperties properties){
    this.properties = properties;
}
```
Nous pouvons utiliser properties pour obtenir les valeurs uri et key pour notre compte Azure Cosmos DB et implémenter cosmosClientBuilder comme indiqué ci-dessous :
```
@Bean
public CosmosClientBuilder cosmosClientBuilder() {
    DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();
    return new CosmosClientBuilder()
        .endpoint(properties.getUri())
        .key(properties.getKey())
        .directMode(directConnectionConfig);
}
```
Cette implémentation
1. Extrait les valeurs uri et key de properties
2. Connecte ces valeurs aux méthodes de générateur de requêtes endpoint et key
3. Configure en outre la connexion réseau au service Azure Cosmos DB. (En mode direct, votre application cliente communique directement avec les partitions Azure Cosmos DB principales.)
Revenez dans CosmosSampleConfiguration.java et recherchez la méthode getDatabaseName :
```
@Override
protected String getDatabaseName() { return ""; }
```
Remplacez la valeur renvoyée par défaut par "Users", le nom de votre base de données. De cette façon, lorsque Spring Data se connecte automatiquement à Azure Cosmos DB au démarrage, il se connecte à la base de données *Users.
Accédez à WebCustomer.java. Vous remarquerez que la classe WebCustomer est précédée d’une annotation @Container :
```
@Container(containerName = "", ru = "")
```
@Container accepte deux arguments :
- containerName : nom du conteneur Azure Cosmos DB (WebCustomers)
- ru : débit provisionné sur votre conteneur. 400 RU/s est une bonne valeur par défaut pour un exercice Microsoft Learn.
Personnalisez la valeur @Container selon votre cas d’utilisation, comme indiqué ci-dessous :
```
@Data
@NoArgsConstructor
@AllArgsConstructor
@Container(containerName = "WebCustomers", ru = "400")
public class WebCustomer {
```

À ce stade, votre projet Spring Data est configuré pour interagir avec Azure Cosmos DB. Ensuite, vous allez générer et exécuter Hello World. Accédez à src/main/java/com/azure/cosmos/examples/springexamples, puis ouvrez CosmosSample.java, qui est un modèle pour l’application Spring Data que nous allons développer. Il doit se présenter comme suit :

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.cosmos.examples.springexamples;

import com.azure.cosmos.CosmosException;
import com.azure.cosmos.examples.springexamples.common.CouponsUsed;
import com.azure.cosmos.examples.springexamples.common.OrderHistory;
import com.azure.cosmos.examples.springexamples.common.ShippingPreference;
import com.azure.cosmos.models.CosmosItemResponse;
import com.azure.cosmos.models.PartitionKey;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

@SpringBootApplication
public class CosmosSample implements CommandLineRunner {

    private final Logger logger = LoggerFactory.getLogger(CosmosSample.class);

    private ReactiveWebCustomerRepository reactiveWebCustomerRepository;

    //constructor dependency injection
    public CosmosSample(ReactiveWebCustomerRepository reactiveWebCustomerRepository){
        this.reactiveWebCustomerRepository = reactiveWebCustomerRepository;
    }

    public void run(String... var1) {
        logger.info("Hello world.");
    }
}

Tel qu’il est actuellement, le code de l’application implémente un simple « Hello World ».

Si votre IDE propose des outils pour générer et exécuter votre application Maven : Générez et exécutez votre application à l’aide de l’IDE, puis vérifiez que l’application enregistre Hello World sur le terminal.
Si vous utilisez le terminal pour générer et exécuter votre application Maven : Utilisez la commande suivante pour générer le projet Maven :
```
mvn clean package
```
Ensuite, exécutez :
```
mvn spring-boot:run
```
Vérifiez que l’application enregistre la sortie suivante sur le terminal, parmi toutes les autres sorties :
```
INFO: Hello World.
```

Dans cette unité, vous avez configuré les éléments de base de votre application Java Azure Cosmos DB. Vous avez personnalisé l’application Maven et avez étendu un projet « Hello World » basique pour le connecter au point de terminaison Azure Cosmos DB.

Exercice : configurer votre application Java à l’aide de Maven

Créer des ressources Azure Cosmos DB

Créer un répertoire de travail

Connecter l’application à Azure Cosmos DB

Créer l’instance CosmosAsyncClient

Connecter l’application à Azure Cosmos DB

Configurer le client Azure Cosmos DB

Commentaires