Accéder aux données avec l’API NoSQL Azure Cosmos DB

  • Article

Cet article explique comment ajouter Spring Cloud Azure Starter pour Spring Data pour Azure Cosmos DB à une application personnalisée. Ce démarrage vous permet de stocker et de récupérer des données à partir de votre base de données Azure Cosmos DB à l’aide de Spring Data et d’Azure Cosmos DB pour NoSQL. L’article commence par vous montrer comment créer une base de données Azure Cosmos DB via le Portail Azure. Ensuite, l’article vous montre comment utiliser Spring Initializr pour créer une application Spring Boot personnalisée que vous pouvez utiliser avec Spring Boot Starter.

Azure Cosmos DB est un service de base de données distribué à l’échelle globale, qui permet aux développeurs de travailler sur des données à l’aide de différentes API standard, telles que SQL, MongoDB, Graph et Table. Spring Boot Starter de Microsoft permet aux développeurs d’utiliser des applications Spring Boot qui s’intègrent facilement à Azure Cosmos DB pour NoSQL.

Prérequis

Créer une base de données Azure Cosmos DB à l’aide du portail Azure

Pour créer une instance Azure Cosmos DB, procédez comme suit :

  1. Accédez au Portail Azure et sélectionnez Créer une ressource.

  2. Sélectionnez Bases de données, puis Azure Cosmos DB.

  3. Dans l’écran Créer un compte Azure Cosmos DB, sélectionnez Azure Cosmos DB pour NoSQL.

    Capture d’écran du Portail Azure montrant la page Créer un compte Azure Cosmos DB avec l’option Azure Cosmos DB pour NoSQL mise en surbrillance.

  4. Sur le panneau Azure Cosmos DB, saisissez les informations suivantes :

    • Choisissez l’Abonnement vous souhaitez utiliser pour votre base de données.
    • Spécifiez si vous souhaitez utiliser un Groupe de ressources existant ou en créer un.
    • Entrez un nom de compte unique, que vous utilisez comme URI pour votre base de données. Par exemple : contosoaccounttest.
    • Spécifiez l’Emplacement pour votre base de données.
    • Sélectionnez Appliquer une remise de niveau gratuit si vous souhaitez créer un compte à des fins de démonstration uniquement.
    • Conservez le reste des options et des paramètres par défaut, comme c’est le cas.

  5. Sélectionnez Vérifier + créer, passer en revue vos spécifications, puis sélectionner Créer.

    Capture d’écran du Portail Azure montrant la page Créer un compte Azure Cosmos DB avec les paramètres Azure Cosmos DB pour NoSQL.

  6. Une fois votre base de données créée, elle est répertoriée dans votre tableau de bord Azure et sous les pages Toutes les ressources et Azure Cosmos DB. Pour créer une base de données et un conteneur pour une nouvelle base de données Azure Cosmos DB, consultez la section Ajouter une base de données et un conteneur de démarrage rapide : Créer un compte, une base de données, un conteneur et des éléments Azure Cosmos DB à partir du Portail Azure. Vous pouvez sélectionner votre base de données à tous ces emplacements pour ouvrir la page des propriétés de votre cache.

  7. Lorsque la page des propriétés de votre base de données s’affiche, sélectionnez Clés et copiez votre URI et vos clés d’accès pour votre base de données. Vous utilisez ces valeurs dans votre application Spring Boot.

    Capture d’écran du Portail Azure montrant le compte Azure Cosmos DB avec la page Clés montrant.

Important

Dans votre nouvelle base de données Azure Cosmos DB, attribuez le Owner rôle au compte Azure que vous utilisez actuellement. Pour plus d’informations, consultez Attribuer des rôles Azure en utilisant le portail Azure.

Créer une application Spring Boot avec Spring Initializr

Effectuez les étapes suivantes pour créer un projet d’application Spring Boot avec le support Azure. Vous pouvez également utiliser l’exemple spring-cloud-azure-data-cosmos-sample dans le référentiel azure-spring-boot-samples . Vous pouvez alors passer directement à la génération et au test de votre application.

  1. Accédez à https://start.spring.io/.

  2. Spécifiez les options suivantes :

    • Générez un projet Maven avec Java.
    • Spécifiez votre version de Spring Boot sur la version 2.7.11.
    • Indiquez les noms du Groupe et de l’Artefact de votre application.
    • Sélectionnez 17 pour la version Java.
    • Ajoutez Support Azure dans les dépendances.

    Remarque

    Spring Initializr utilise les noms de Groupe et d’Artefact pour créer le nom du package. Par exemple : com.example.wingtiptoysdata.

    La version de Spring Boot peut être ultérieure à celle prise en charge par le Support Azure. Une fois le projet généré automatiquement, vous pouvez modifier manuellement la version spring Boot en version la plus élevée prise en charge par Azure, que vous trouverez dans Spring-Versions-Mapping.

  3. Lorsque vous avez spécifié les options répertoriées précédemment, sélectionnez GENERATE.

  4. Lorsque vous y êtes invité, téléchargez le projet dans un emplacement défini par un chemin d’accès sur votre ordinateur local et décompressez les fichiers.

Votre application Spring Boot simple est maintenant prête pour l’édition.

Configurer votre application Spring Boot pour utiliser Azure Spring Boot Starter

  1. Localisez le fichier pom.xml dans le répertoire de votre application. Par exemple :

    C:\SpringBoot\wingtiptoysdata\pom.xml

    -ou-

    /users/example/home/wingtiptoysdata/pom.xml

  2. Ouvrez le fichier pom.xml dans un éditeur de texte, puis ajoutez ce qui suit à l’élément <dependencies> :

    <dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter-data-cosmos</artifactId>
</dependency>

    Remarque

    Pour plus d’informations sur la gestion des versions de bibliothèque Spring Cloud Azure à l’aide d’une facture de documents (BOM), consultez la section Prise en main du guide du développeur Azure Spring Cloud.

  3. Enregistrez et fermez le fichier pom.xml.

Configurer votre application Spring Boot pour utiliser votre base de données Azure Cosmos DB

  1. Localisez le fichier application.properties dans le répertoire resources de votre application. Par exemple :

    C :\SpringBoot\wingtiptoysdata\src\main\resources\application.properties

    -ou-

    /users/example/home/wingtiptoysdata/src/main/resources/application.properties

  2. Ouvrez le fichier application.properties dans un éditeur de texte, ajoutez-y les lignes suivantes, puis remplacez les exemples de valeurs par les propriétés appropriées pour votre base de données :

    # Specify the DNS URI of your Azure Cosmos DB.
spring.cloud.azure.cosmos.endpoint=https://contosoaccounttest.documents.azure.com:443/
spring.cloud.azure.cosmos.key=your-cosmosdb-account-key

# Specify the name of your database.
spring.cloud.azure.cosmos.database=contosoaccounttest
spring.cloud.azure.cosmos.populate-query-metrics=true

  3. Enregistrez et fermez le fichier application.properties.

Ajouter un exemple de code pour implémenter une fonctionnalité simple de base de données

Dans cette section, vous allez créer deux classes Java pour stocker les données utilisateur. Ensuite, vous modifiez votre classe d’application principale pour créer une instance de la User classe et l’enregistrer dans votre base de données.

Définir une classe de base pour le stockage des données utilisateur

  1. Créez un fichier nommé User.java dans le même répertoire que celui du fichier Java principal de votre application.

  2. Ouvrez le fichier User.java dans un éditeur de texte, puis ajoutez-y les lignes suivantes pour définir une classe d’utilisateur générique qui stocke et récupère des valeurs dans votre base de données :

    package com.example.wingtiptoysdata;

import com.azure.spring.data.cosmos.core.mapping.Container;
import com.azure.spring.data.cosmos.core.mapping.PartitionKey;
import org.springframework.data.annotation.Id;

@Container(containerName = "mycollection")
public class User {
    @Id
    private String id;
    private String firstName;
    @PartitionKey
    private String lastName;
    private String address;

    public User() {

    }

    public User(String id, String firstName, String lastName, String address) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.address = address;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    @Override
    public String toString() {
        return String.format("%s %s, %s", firstName, lastName, address);
    }
}

  3. Enregistrez et fermez le fichier User.java.

Définir une interface de référentiel de données

  1. Créez un fichier nommé UserRepository.java dans le même répertoire que le fichier Java principal de votre application.

  2. Ouvrez le fichier UserRepository.java dans un éditeur de texte, puis ajoutez-y les lignes suivantes pour définir une interface de référentiel utilisateur qui étend l’interface ReactiveCosmosRepository par défaut :

    package com.example.wingtiptoysdata;

import com.azure.spring.data.cosmos.repository.ReactiveCosmosRepository;
import org.springframework.stereotype.Repository;
import reactor.core.publisher.Flux;

@Repository
public interface UserRepository extends ReactiveCosmosRepository<User, String> {
    Flux<User> findByFirstName(String firstName);
}

    L’interface ReactiveCosmosRepository remplace l’interface DocumentDbRepository de la version précédente du starter. La nouvelle interface propose des API synchrones et réactives pour les opérations élémentaires que sont l’enregistrement, la suppression et la recherche.

  3. Enregistrez et fermez le fichier UserRepository.java.

Modifiez la classe d’application principale

  1. Recherchez le fichier Java principal de l’application dans le répertoire de package de votre application, par exemple :

    C:\SpringBoot\wingtiptoysdata\src\main\java\com\example\wingtiptoysdata\WingtiptoysdataApplication.java

    -ou-

    /users/example/home/wingtiptoysdata/src/main/java/com/example/wingtiptoysdata/WingtiptoysdataApplication.java

  2. Ouvrez le fichier Java principal de l’application dans un éditeur de texte, puis ajoutez-y les lignes suivantes :

    package com.example.wingtiptoysdata;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.util.Assert;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.Optional;

@SpringBootApplication
public class WingtiptoysdataApplication implements CommandLineRunner {

    private static final Logger LOGGER = LoggerFactory.getLogger(WingtiptoysdataApplication.class);

    @Autowired
    private UserRepository repository;

    public static void main(String[] args) {
        SpringApplication.run(WingtiptoysdataApplication.class, args);
    }

    public void run(String... var1) {
        this.repository.deleteAll().block();
        LOGGER.info("Deleted all data in container.");

        final User testUser = new User("testId", "testFirstName", "testLastName", "test address line one");

        // Save the User class to Azure Cosmos DB database.
        final Mono<User> saveUserMono = repository.save(testUser);

        final Flux<User> firstNameUserFlux = repository.findByFirstName("testFirstName");

        //  Nothing happens until we subscribe to these Monos.
        //  findById won't return the user as user isn't present.
        final Mono<User> findByIdMono = repository.findById(testUser.getId());
        final User findByIdUser = findByIdMono.block();
        Assert.isNull(findByIdUser, "User must be null");

        final User savedUser = saveUserMono.block();
        Assert.state(savedUser != null, "Saved user must not be null");
        Assert.state(savedUser.getFirstName().equals(testUser.getFirstName()), "Saved user first name doesn't match");

        firstNameUserFlux.collectList().block();

        final Optional<User> optionalUserResult = repository.findById(testUser.getId()).blockOptional();
        Assert.isTrue(optionalUserResult.isPresent(), "Cannot find user.");

        final User result = optionalUserResult.get();
        Assert.state(result.getFirstName().equals(testUser.getFirstName()), "query result firstName doesn't match!");
        Assert.state(result.getLastName().equals(testUser.getLastName()), "query result lastName doesn't match!");

        LOGGER.info("findOne in User collection get result: {}", result.toString());
    }
}

  3. Enregistrez et fermez le fichier Java principal de l’application.

Générer et tester votre application

  1. Ouvrez une invite de commandes, puis accédez au dossier où est situé votre fichier pom.xml, par exemple :

    cd C:\SpringBoot\wingtiptoysdata

    -ou-

    cd /users/example/home/wingtiptoysdata

  2. Utilisez la commande suivante pour générer et exécuter votre application :

    ./mvnw clean

    Cette commande exécute l’application automatiquement pendant la phase de test. Vous pouvez aussi utiliser :

    ./mvnw spring-boot:run

    Après une sortie de build et de test, votre fenêtre de console affiche un message similaire à l’exemple suivant :

    INFO 1365 --- [           main] c.e.w.WingtiptoysdataApplication         : Deleted all data in container.

... (omitting connection and diagnostics output) ...

INFO 1365 --- [           main] c.e.w.WingtiptoysdataApplication         : findOne in User collection get result: testFirstName testLastName, test address line one

    Ces messages de sortie indiquent que les données ont été correctement enregistrées dans Azure Cosmos DB, puis récupérées à nouveau.

Nettoyer les ressources

Si vous ne souhaitez pas continuer à utiliser cette application, veillez à supprimer le groupe de ressources contenant azure Cosmos DB que vous avez créé précédemment. Vous pouvez supprimer le groupe de ressources du Portail Azure.

Étapes suivantes

Pour en savoir plus sur Spring et Azure, poursuivez vers le centre de documentation Spring sur Azure.

Spring sur Azure

Plus de ressources

Pour plus d’informations sur l’utilisation d’Azure Cosmos DB et de Java, voir les ressources suivantes :

Pour plus d’informations sur l’utilisation d’applications Spring Boot sur Azure, consultez les articles suivants :

Pour plus d’informations sur l’utilisation d’Azure avec Java, renseignez-vous sur Azure pour les développeurs Java et l’utilisation d’Azure DevOps et Java.

Spring Framework est une solution open source qui aide les développeurs Java à créer des applications d’entreprise. L’un des projets les plus connus basés sur cette plateforme est Spring Boot, qui fournit une approche simplifiée pour la création d’applications Java autonomes. Pour aider les développeurs à bien démarrer avec Spring Boot, plusieurs exemples de packages Spring Boot sont disponibles à l’adresse https://github.com/spring-guides/. En plus de choisir dans la liste des projets Spring Boot de base, Spring Initializr aide les développeurs à commencer à créer des applications Spring Boot personnalisées.