Condividi tramite

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

  • Articolo

Questo articolo illustra come aggiungere Spring Cloud Azure Starter for Spring Data per l'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 utilizzando il portale di Azure

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

  1. Passare alla del portale di Azure e selezionare Crea una risorsa.

  2. Selezionare Databasee quindi selezionare Azure Cosmos DB.

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

    Screenshot del 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 di Azure Cosmos DB immettere le informazioni seguenti:

    • Scegli la sottoscrizione che desideri usare per il tuo database.
    • Specificare se creare un nuovo gruppo di risorse per il database o scegliere un gruppo di risorse esistente.
    • Immettere un nome account univoco , che viene usato come URI per il database. Ad esempio: contosoaccounttest.
    • Specifica la posizione per il tuo database.
    • Selezionare Applica sconto del livello gratuito se si vuole creare un account per scopi dimostrativi.
    • Lasciare invariate le altre opzioni e le impostazioni predefinite.

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

    screenshot del 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 nelladashboard di Azure e nelle pagine Tutte le risorse e azure Cosmos DB. Per creare un database e un contenitore per un Azure Cosmos DB appena creato, vedere la sezione Aggiungere un database e un contenitore di Avvio rapido: Creare un account, un database, un contenitore ed elementi di Azure Cosmos DB dal portale di Azure. È possibile selezionare il tuo database per una qualsiasi di queste posizioni per aprire la pagina delle proprietà per la tua cache.

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

    Screenshot del 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 ruolo di Owner all'account Azure attualmente in uso. Vedere Assegnare ruoli di Azure usando il portale di Azureper altre informazioni.

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 nell'azure-spring-boot-samples repository. È quindi possibile passare direttamente a Compilare e testare l'app.

  1. Sfoglia fino a https://start.spring.io/.

  2. Specificare le opzioni seguenti:

    • Generare un progetto Maven Java.
    • Specificare la versione Spring Boot per 2.7.11.
    • Specificare i nomi group e Artifact per l'applicazione.
    • Selezionare 17 per la versione Java.
    • Aggiungere Supporto Azure nelle dipendenze.

    Nota

    Spring Initializr usa i nomi del gruppo e dell'artifact per generare 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 alla versione più recente supportata da Azure, disponibile in Spring-Versions-Mapping.

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

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

L'applicazione Spring Boot semplice è 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; Per esempio:

    C:\SpringBoot\wingtiptoysdata\pom.xml

    -o-

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

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

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

    Nota

    Per ulteriori informazioni su come gestire le versioni delle librerie di Azure Spring Cloud usando una BOM (bill of materials), vedere la sezione Introduzione della guida per sviluppatori di Azure Spring Cloud .

  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; Per esempio:

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

    -o-

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

  2. Aprire il file application.properties in un editor di testo e 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/
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. Salvare e chiudere il file application.properties.

Aggiungere codice di esempio per implementare la 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 classe User e salvarla nel database.

Definire una classe base per l'archiviazione dei dati utente

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

  2. Aprire il file User.java in un editor di testo e aggiungere le righe seguenti al file per definire una classe utente generica che archivia e recupera 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 Java dell'applicazione principale.

  2. Aprire il file UserRepository.java in un editor di testo e aggiungere le righe seguenti al file per definire un'interfaccia del repository utente che estende l'interfaccia di 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 dalla versione precedente dello starter. La nuova interfaccia fornisce API sincrone e reattive per operazioni di salvataggio, eliminazione e ricerca di base.

  3. Salvare e chiudere il file di UserRepository.java.

Modificare la classe principale dell'applicazione

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

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

    -o-

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

  2. Aprire il file Java dell'applicazione principale 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 principale.

Compilare e testare l'app

  1. Apri un prompt dei comandi e naviga alla cartella in cui si trova il file pom.xml: per esempio:

    cd C:\SpringBoot\wingtiptoysdata

    -o-

    cd /users/example/home/wingtiptoysdata

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

    ./mvnw clean

    Questo comando esegue automaticamente l'applicazione 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 documentazione di Spring in Azure.

Spring su Azure

Altre risorse

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

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

Per ulteriori informazioni sull'uso di Azure con Java, vedere i seguenti documenti: Azure for Java Developers e Lavorare con Azure DevOps e Java.

Il Spring Framework è una soluzione open source che consente agli sviluppatori Java di creare applicazioni a livello aziendale. Uno dei progetti più diffusi basati su tale piattaforma è Spring Boot, che offre un approccio semplificato per la creazione di applicazioni Java autonome. Per aiutare gli sviluppatori a iniziare a usare Spring Boot, sono disponibili diversi pacchetti Spring Boot di esempio in https://github.com/spring-guides/. Oltre a scegliere dall'elenco dei progetti Spring Boot di base, il Spring Initializr consente agli sviluppatori di iniziare a creare applicazioni Spring Boot personalizzate.