Partager via

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

  • Article

Cet article montre comment ajouter le Spring Cloud Azure Starter pour Spring Data à 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é globalement qui permet aux développeurs d’utiliser des données à l’aide de diverses API standard, telles que SQL, MongoDB, Graph et Les API 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.

Conditions préalables

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 sélectionnez 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. Dans la page Azure Cosmos DB, entrez les informations suivantes :

    • Choisissez l’abonnement que vous souhaitez utiliser pour votre base de données.
    • Spécifiez s’il faut créer un groupe de ressources pour votre base de données ou choisir un groupe de ressources existant.
    • 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 Appliquez la remise Free Tier si vous souhaitez créer un compte uniquement à des fins de démonstration.
    • Conservez le reste des options et des paramètres par défaut, comme c’est le cas.

  5. Sélectionnez Vérifier + créer, passez en revue vos spécifications, puis sélectionnez 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 sur votretableau de bord Azure , puis, sous les pages Toutes les ressources et Azure Cosmos DB. Pour créer une base de données et un conteneur pour un compte Azure Cosmos DB nouvellement créé, consultez la section Ajouter une base de données et un conteneur de Démarrage rapide : Créer un compte Azure Cosmos DB, une base de données, un conteneur et des éléments à partir du portail Azure. Vous pouvez sélectionner votre base de données pour l’un de 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 vos URI et 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 affichée.

Important

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

Créer une application Spring Boot avec Spring Initializr

Procédez comme suit pour créer un projet d’application Spring Boot avec prise en charge d’Azure. Vous avez aussi la possibilité d’utiliser l’exemple spring-cloud-azure-data-cosmos-sample contenu dans le référentiel azure-spring-boot-samples. Ensuite, vous pouvez passer directement à Build et tester 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 et sélectionnez 2.7.11.
    • Spécifiez les noms de groupe et d'artefact pour 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'artifact pour créer le nom de package ; par exemple : com.example.wingtiptoysdata.

    La version de Spring Boot peut être supérieure à la version 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 sur un chemin d’accès sur votre ordinateur local et extrayez les fichiers.

Votre application Spring Boot simple est maintenant prête à être modifiée.

Configurer votre application Spring Boot pour utiliser Azure Spring Boot Starter

  1. Recherchez 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 des bibliothèques Azure Spring Cloud à l’aide d’une liste de matériaux (BOM), consultez la section Commencer du guide du développeur Spring Cloud Azure.

  3. Enregistrez et fermez le fichier pom.xml.

Configurer votre application Spring Boot pour utiliser votre azure Cosmos DB

  1. Recherchez le fichier application.properties dans le répertoire des ressources 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, puis ajoutez les lignes suivantes au fichier, 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 des fonctionnalités 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 classe User 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 le fichier Java de votre application principale.

  2. Ouvrez le fichier User.java dans un éditeur de texte et ajoutez les lignes suivantes au fichier pour définir une classe 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 de votre application principale.

  2. Ouvrez le fichier UserRepository.java dans un éditeur de texte et ajoutez les lignes suivantes au fichier pour définir une interface de référentiel utilisateur qui étend l’interface de 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 démarrage. La nouvelle interface fournit des API synchrones et réactives pour les opérations d’enregistrement, de suppression et de recherche de base.

  3. Enregistrez et fermez le fichier UserRepository.java.

Modifier la classe d’application principale

  1. Recherchez le fichier Java de l’application principale 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 de l’application principale dans un éditeur de texte et ajoutez les lignes suivantes au fichier :

    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 de l’application principale.

Générer et tester votre application

  1. Ouvrez une invite de commandes et accédez au dossier où se trouve 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 automatiquement l’application dans le cadre de la phase de test. Vous pouvez également 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, passez au centre de documentation Spring sur Azure.

Spring sur Azure

Autres ressources

Pour plus d’informations sur l’utilisation d’Azure Cosmos DB et de Java, consultez les articles suivants :

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, consultez les Azure pour les développeurs Java et les Utilisation d’Azure DevOps et Java.

Le Spring Framework est une solution open source qui aide les développeurs Java à créer des applications au niveau de l’entreprise. L’un des projets les plus populaires basés sur cette plateforme est Spring Boot, qui offre une approche simplifiée pour la création d’applications Java autonomes. Pour aider les développeurs à commencer à utiliser Spring Boot, plusieurs exemples de packages Spring Boot sont disponibles à https://github.com/spring-guides/. Outre le choix dans la liste des projets Spring Boot de base, le Spring Initializr permet aux développeurs de commencer à créer des applications Spring Boot personnalisées.