Accedere ai dati con l'API NoSQL di Azure Cosmos DB

  • Articolo

Questo articolo illustra come aggiungere Spring Cloud Azure Starter per Spring Data per Azure Cosmos DB a un'applicazione personalizzata. Questo strumento di avvio consente di archiviare e recuperare dati dal database di Azure Cosmos DB usando Spring Data e Azure Cosmos DB per NoSQL. L'articolo inizia illustrando come creare un'istanza di Azure Cosmos DB tramite il portale di Azure. L'articolo illustra quindi come usare Spring Initializr per creare un'applicazione Spring Boot personalizzata che è possibile usare con Spring Boot Starter.

Azure Cosmos DB è un servizio di database distribuito a livello globale che consente agli sviluppatori di lavorare con i dati usando varie API standard, ad esempio SQL, MongoDB, Graph e TABELLE. Spring Boot Starter di Microsoft consente agli sviluppatori di usare applicazioni Spring Boot che si integrano facilmente con Azure Cosmos DB per NoSQL.

Prerequisiti

Creare un Azure Cosmos DB usando il portale di Azure

Usare la procedura seguente per creare un'istanza di Azure Cosmos DB:

  1. Passare al portale di Azure e selezionare Crea una risorsa.

  2. Selezionare Database e quindi selezionare Azure Cosmos DB.

  3. Nella schermata Crea un account Azure Cosmos DB selezionare Azure Cosmos DB per NoSQL.

    Screenshot della portale di Azure che mostra la pagina Creare un account Azure Cosmos DB con l'opzione Azure Cosmos DB per NoSQL evidenziata.

  4. Nella pagina Azure Cosmos DB immettere le informazioni seguenti:

    • Selezionare la sottoscrizione da usare per il database.
    • Specificare se creare un nuovo gruppo di risorse per il database o sceglierne uno esistente.
    • Immettere un nome account univoco, che viene usato come URI per il database. Ad esempio: contosoaccounttest.
    • Specificare il percorso per il database.
    • Selezionare Applica sconto livello gratuito se si vuole creare un account solo a scopo dimostrativo.
    • Lasciare invariate le altre opzioni e le impostazioni predefinite.

  5. Selezionare Rivedi e crea, esaminare le specifiche e selezionare Crea.

    Screenshot della portale di Azure che mostra la pagina Crea account Azure Cosmos DB con le impostazioni di Azure Cosmos DB per NoSQL.

  6. Dopo aver creato il database, è elencato nel dashboard di Azure e nelle pagine Tutte le risorse e Azure Cosmos DB. Per creare un database e un contenitore per azure Cosmos DB appena creato, vedere la sezione Aggiungere un database e un contenitore di Avvio rapido: Creare un account, un database, un contenitore e un account Azure Cosmos DB dall'portale di Azure. È possibile selezionare il database per uno qualsiasi di questi percorsi per aprire la pagina delle proprietà per la cache.

  7. Quando viene visualizzata la pagina delle proprietà per il database, selezionare Chiavi e copiare l'URI e le chiavi di accesso per il database. Questi valori vengono usati nell'applicazione Spring Boot.

    Screenshot della portale di Azure che mostra l'account Azure Cosmos DB con la pagina Chiavi visualizzata.

Importante

Nel database Azure Cosmos DB appena creato assegnare il Owner ruolo all'account Azure attualmente in uso. Per ulteriori informazioni, vedi Assegnare ruoli di Azure usando il portale di Azure.

Creare un'applicazione Spring Boot con Spring Initializr

Usare la procedura seguente per creare un nuovo progetto di applicazione Spring Boot con il supporto di Azure. In alternativa, è possibile usare l'esempio spring-cloud-azure-data-cosmos-sample nel repository azure-spring-boot-samples . Quindi, è possibile passare direttamente alla sezione Compilare e testare l'app.

  1. Passa a https://start.spring.io/.

  2. Specificare le opzioni seguenti:

    • Generare un progetto Maven con Java.
    • Specificare la versione di Spring Boot alla versione 2.7.11.
    • Specificare i nomi di Group (Gruppo) e Artifact (Artefatto) per l'applicazione.
    • Selezionare 17 per la versione Java.
    • Aggiungere Supporto di Azure nelle dipendenze.

    Nota

    Spring Initializr usa i nomi in Group (Gruppo) e Artifact (Artefatto) per creare il nome del pacchetto, ad esempio com.example.wingtiptoysdata.

    La versione di Spring Boot può essere superiore alla versione supportata dal supporto tecnico di Azure. Dopo aver generato automaticamente il progetto, è possibile modificare manualmente la versione di Spring Boot con la versione più recente supportata da Azure, disponibile in Spring-Versions-Mapping.

  3. Dopo aver specificato le opzioni elencate in precedenza, selezionare GENERA.

  4. Quando richiesto, scaricare il progetto in un percorso nel computer locale ed estrarre i file.

La semplice applicazione Spring Boot è ora pronta per la modifica.

Configurare l'applicazione Spring Boot per l'uso di Azure Spring Boot Starter

  1. Individuare il file pom.xml nella directory dell'app, ad esempio:

    C:\SpringBoot\wingtiptoysdata\pom.xml

    oppure

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

  2. Aprire il file pom.xml in un editor di testo e aggiungere quanto esegue all'elemento <dependencies>:

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

    Nota

    Per altre informazioni su come gestire le versioni delle librerie di Azure Spring Cloud usando una distinta base, vedere la sezione Introduzione alla guida per sviluppatori di Spring Cloud Azure.

  3. Salvare e chiudere il file pom.xml.

Configurare l'applicazione Spring Boot per l'uso di Azure Cosmos DB

  1. Individuare il file application.properties nella directory resources dell'app, ad esempio:

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

    oppure

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

  2. Aprire il file application.properties in un editor di testo, quindi aggiungere le righe seguenti al file e sostituire i valori di esempio con le proprietà appropriate per il database:

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

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

  3. Salvare e chiudere il file application.properties.

Aggiungere il codice di esempio per implementare le funzionalità di base del database

In questa sezione vengono create due classi Java per l'archiviazione dei dati utente. Modificare quindi la classe dell'applicazione principale per creare un'istanza della User classe e salvarla nel database.

Definire una classe di base per l'archiviazione dei dati utente

  1. Creare un nuovo file denominato User.java nella stessa directory del file dell'applicazione Java main.

  2. Aprire il file User.java in un editor di testo e aggiungere le righe seguenti al file per definire una classe User generica che consenta di archiviare e recuperare i valori nel database:

    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. Salvare e chiudere il file User.java.

Definire un'interfaccia del repository di dati

  1. Creare un nuovo file denominato UserRepository.java nella stessa directory del file dell'applicazione Java main.

  2. Aprire il file UserRepository.java in un editor di testo e aggiungere le righe seguenti al file per definire l'interfaccia utente del repository che estende l'interfaccia ReactiveCosmosRepository predefinita:

    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'interfaccia ReactiveCosmosRepository sostituisce l'interfaccia DocumentDbRepository della versione precedente di Starter. La nuova interfaccia include API sincrone e reattive per operazioni di base di salvataggio, eliminazione e ricerca.

  3. Salvare e chiudere il file UserRepository.java.

Modificare la classe dell'applicazione main

  1. Individuare il file Java dell'applicazione main nella directory del pacchetto dell'app, ad esempio:

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

    oppure

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

  2. Aprire il file Java dell'applicazione main in un editor di testo e aggiungere le righe seguenti al file:

    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. Salvare e chiudere il file Java dell'applicazione main.

Compilare e testare l'app

  1. Aprire un prompt dei comandi e passare alla cartella in cui si trova il file pom.xml, ad esempio:

    cd C:\SpringBoot\wingtiptoysdata

    oppure

    cd /users/example/home/wingtiptoysdata

  2. Usare il comando seguente per compilare ed eseguire l'applicazione:

    ./mvnw clean

    Questo comando esegue l'applicazione automaticamente come parte della fase di test. È anche possibile usare:

    ./mvnw spring-boot:run

    Dopo alcuni output di compilazione e test, nella finestra della console viene visualizzato un messaggio simile all'esempio seguente:

    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

    Questi messaggi di output indicano che i dati sono stati salvati correttamente in Azure Cosmos DB e quindi recuperati di nuovo.

Pulire le risorse

Se non si intende continuare a usare questa applicazione, assicurarsi di eliminare il gruppo di risorse contenente Azure Cosmos DB creato in precedenza. È possibile eliminare il gruppo di risorse dal portale di Azure.

Passaggi successivi

Per altre informazioni su Spring e Azure, passare al centro di documentazione di Spring in Azure.

Spring in Azure

Altre risorse

Per altre informazioni sull'utilizzo di Azure Cosmos DB e Java, vedere gli articoli seguenti:

Per altre informazioni sull'uso delle applicazioni Spring Boot in Azure, vedere gli articoli seguenti:

Per altre informazioni sull'uso di Azure con Java, vedere Azure per sviluppatori Java e la documentazione relativa all'uso di Azure DevOps e Java.

Spring Framework è una soluzione open source che consente agli sviluppatori Java di creare applicazioni di livello enterprise. Uno dei progetti più comuni che si basa su questa piattaforma è Spring Boot, che fornisce un approccio semplificato per la creazione di applicazioni Java autonome. Per semplificare le operazioni iniziali con Spring Boot per gli sviluppatori, diversi pacchetti Spring Boot di esempio sono disponibili all'indirizzo https://github.com/spring-guides/. Oltre a consentire di scegliere dall'elenco di progetti Spring Boot di base, Spring Initializr semplifica le operazioni iniziali degli sviluppatori per la creazione di applicazioni Spring Boot personalizzate.