Esercizio - Configurare l'app Java con Maven

  • 15 minuti

In questa unità verrà creata un'app console di base mediante un IDE di propria scelta per modificare il codice. Facoltativamente, è possibile usare il terminale di propria scelta per eseguire il codice.

Creare risorse di Azure Cosmos DB

Per completare questo lab, Microsoft Learn fornisce una sandbox di Azure gratuita in cui è possibile creare account e risorse. Verrà configurato un account Azure Cosmos DB in questa sottoscrizione e quindi verranno creati un database e un contenitore.

  1. Accedere al portale di Azure usando lo stesso account con cui è stata attivata la sandbox.
  2. Usando il portale di Azure, creare un account Azure Cosmos DB con il nome desiderato. Quando viene chiesto di scegliere un gruppo di risorse per l'account, trovare il gruppo di risorse [Gruppo di risorse sandbox] e selezionarlo.
  3. Nell'account Azure Cosmos DB creare un database denominato Utenti.
  4. Nel database Users creare un contenitore denominato WebCustomers con una chiave di partizione /userId. Effettuare il provisioning di 400 UR/sec per WebCustomers.

Creare la directory di lavoro

  1. Viene fornito un modello per l'applicazione Java. Clonare il repository del modello nel sistema.

    git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git

  2. Aprire Esplora file di Windows e passare al repository clonato. Aprire la sottodirectory java_lab.

    Importante

    Tutto il lavoro per questo modulo sarà incluso nella sottodirectory java_lab.

  3. Il modello contiene un file pom.xml Maven che esegue già il pull delle dipendenze necessarie per il progetto. Aprire questo file ed esaminarlo per trovare la dipendenza seguente:

    <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>LATEST</version>
</dependency>

    Questa dipendenza esegue il pull della versione più recente di Java SDK per Azure Cosmos DB. È possibile chiudere questo file.

  4. Successivamente, verrà compilato ed eseguito il programma Hello World. Usando l'IDE o il terminale aprire il progetto. A seconda dell'IDE, potrebbe essere disponibile un'opzione per aprire il file pom.xml nella sottodirectory java come progetto.

    Una volta aperto il progetto, passare a src/main/java/com/azure/cosmos/examples/mslearnbasicapp e aprire CosmosApp.java, ovvero un modello per l'applicazione Java che verrà sviluppata. L'output dovrebbe essere simile al seguente:

    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.");
    }
}

    Così com'è, il codice dell'applicazione implementa un semplice progetto "Hello World".

  5. Se l'IDE offre strumenti per compilare ed eseguire l'applicazione Maven: compilare ed eseguire l'applicazione usando l'IDE e verificare che l'applicazione registri Hello World nel terminale.

  6. Se si userà il terminale per compilare ed eseguire l'applicazione Maven: usare il comando seguente per compilare il progetto Maven:

    mvn clean package

    Eseguire quindi:

    mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    Verificare che l'applicazione registri il seguente output nel terminale:

    INFO: Hello World.

Connettere l'app ad Azure Cosmos DB

  1. Nella classe CosmosApp creare le variabili di classe statiche seguenti per i dati della connessione di 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>";

  2. Tornare al portale di Azure, passare al riquadro Chiavi e copiare/incollare l'URI dell'endpoint di Azure Cosmos DB e la chiave primaria nelle definizioni di variabili precedenti.

    Se, ad esempio, l'URI è https://cosmosacct.documents.azure.com:443/, la nuova assegnazione di variabile sarà simile alla seguente: private static String endpointUri = "https://cosmosacct.documents.azure.com:443/";. Se la chiave primaria è elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==, la nuova assegnazione di variabile sarà simile alla seguente: private static String primaryKey = "elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==";.

Creare l'istanza CosmosAsyncClient

A questo punto è possibile creare un'istanza di CosmosAsyncClient, ovvero la rappresentazione lato client del servizio Azure Cosmos DB. Questo client viene usato per configurare ed eseguire richieste per il servizio.

  1. In CosmosApp.java aggiungere la dichiarazione di variabile statica seguente alla 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;

    Probabilmente, le classi client, databasee container non sono ancora state importate nel file Java, pertanto è opportuno farlo ora. Alcuni IDE potrebbero consentire l'importazione automatica delle dipendenze in base al codice digitato e ciò può essere utile in questo caso. In generale, tenere presente che quando viene fornito un blocco di codice da incollare può essere necessario aggiungere alcune istruzioni import per il corretto funzionamento.

  2. Creare un metodo private void denominato basicOperations senza argomenti nella classe.

  3. Aggiungere il codice seguente per creare un'istanza CosmosAsyncClient nel metodo basicOperations e includere il codice per controllare se il database Utenti esiste.

     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();

  4. A questo punto, il metodo basicOperations contiene il codice per interagire con Azure Cosmos DB. Tuttavia, questo metodo non viene chiamato in main, quindi l'applicazione serve comunque per stampare "Hello World". Come controllo, compilare ed eseguire CosmosApp.java nell'IDE o eseguire il programma nel terminale usando:

    mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    Verificare che l'app registri ancora il seguente output nel terminale:

    INFO: Hello World.

  5. Copiare e incollare il codice seguente nel main metodo sovrascrivendo la riga corrente logger.info("Hello World."); .

    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.");
}

    Questa operazione attiverà il codice di Azure Cosmos DB nell'applicazione.

  6. Compilare ed eseguire CosmosApp.java nell'IDE oppure eseguire il programma nel terminale usando:

    mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    È possibile che nel terminale venga visualizzato un numero elevato di messaggi di log, alcuni dei quali generati dall'SDK stesso. Leggere e verificare che l'app registri l'output seguente nel terminale:

    INFO: Database and container validation complete

In questa unità sono state poste le basi per l'applicazione Java di Azure Cosmos DB. È stata configurata l'applicazione Maven, è stato creato un progetto "Hello World" di base e il progetto è stato esteso per connetterlo all'endpoint di Azure Cosmos DB.

  1. Viene fornito un modello per l'applicazione Java. Clonare il repository del modello nel sistema

    git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git

  2. Aprire Esplora risorse e passare al repository clonato. Aprire la sottodirectory spring_lab.

    Importante

    Tutto il lavoro per questo modulo sarà incluso nella sottodirectory spring_lab.

  3. Il modello contiene un file pom.xml Maven che esegue già il pull delle dipendenze necessarie per il progetto. Aprire questo file ed esaminarlo per trovare la dipendenza seguente:

    <dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-spring-data-cosmos</artifactId>
  <version>LATEST</version>
</dependency>

    Questa dipendenza esegue il pull della versione più recente di Spring Data per Azure Cosmos DB. È possibile chiudere questo file.

Connettere l'app ad Azure Cosmos DB

  1. Usando l'IDE o il terminale aprire il progetto. A seconda dell'IDE, potrebbe essere disponibile un'opzione per aprire il file pom.xml nella sottodirectory spring come progetto. Dopo aver aperto il progetto, passare a src/main/resources/ usando uno strumento per l'esplorazione dei file. Verrà visualizzato un file denominato application.properties.rename. Spring Data evidenzia i file di configurazione basati sui parametri di configurazione hardcoded; per creare il file di configurazione per il progetto Spring Data, copiare application.properties.rename in application.properties e aprire il nuovo file application.properties. Dovrebbe essere visualizzato quanto segue:

    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

    Si popolerà ${ACCOUNT_HOST} e ${ACCOUNT_KEY}, usando un metodo di propria scelta: copiare e incollare i valori in application.properties oppure definire queste variabili di ambiente nell'IDE. Nel passaggio successivo si troveranno i valori di queste variabili.

  2. Tornare al portale di Azure, passare al riquadro Chiavi e copiare l'URI dell'endpoint di Azure Cosmos DB e la chiave primaria. Come illustrato nel passaggio precedente, usare il metodo preferito per assegnare l'URI dell'endpoint di Azure Cosmos DB e la chiave primaria alle variabili indicate sopra.

    Ad esempio, se l'URI è https://cosmosacct.documents.azure.com:443/ e si sceglie di incollare l'endpoint e la chiave primaria in application.properties, la riga in application.properties sarà simile alla seguente: cosmos.uri=https://cosmosacct.documents.azure.com:443/. Se la chiave primaria è elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==, seguendo lo stesso processo la nuova assegnazione di variabile sarà simile alla seguente: cosmos.key=elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==.

Configurare il client di Azure Cosmos DB

Spring Data per Azure Cosmos DB crea automaticamente un'istanza del client di Azure Cosmos DB all'avvio. Il client di Azure Cosmos DB è la rappresentazione lato client del servizio Azure Cosmos DB, usato per eseguire le richieste nel servizio. Il codice può configurare il client di Azure Cosmos DB prima di crearne un'istanza, usando un set di metodi del generatore insieme a proprietà di cui è stato eseguito il pull da application.properties.

  1. Aprire CosmosProperties.java. Poiché questo file è stato fornito in un modulo completato, è sufficiente esaminarne il contenuto.

    @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;
    }
}

    Osservare i membri della classe uri, key, secondaryKey, queryMetricsEnabled. Tornando ad application.properties, osservare che i nomi dei membri di CosmosProperties corrispondono esattamente ai nomi delle proprietà di application.properties. La classe CosmosProperties presenta getter e setter per il resto dell'applicazione per accedere alle impostazioni di configurazione da application.properties. Si noti che non è presente alcun codice per eseguire il pull della configurazione da application.properties: Spring Data individua la struttura del file e imposta automaticamente le variabili membro dopo aver analizzato il file di configurazione.

    Questa configurazione verrà usata in futuro quando verrà configurato il client di Azure Cosmos DB.

  2. In CosmosSampleConfiguration.java esaminare la classe CosmosSampleConfiguration e trovare il metodo cosmosClientBuilder vuoto:

    @Bean
public CosmosClientBuilder cosmosClientBuilder() {
    return null;
}

    All'avvio Spring Data chiama automaticamente questo metodo, ottiene CosmosClientBuilder restituito dal metodo e chiama il relativo metodo build(). In questo momento viene creata un'istanza di CosmosAsyncClient in base alle impostazioni di configurazione contenute in CosmosClientBuilder. È possibile usare questo metodo per configurare CosmosClientBuilder usando i metodi del generatore.

  3. Si noti che viene usato l'inserimento del costruttore (anziché l'inserimento di campi usando @Autowired)) per creare un'istanza della properties variabile e popolare le variabili membro con valori analizzati dal file di configurazione. Ciò garantisce che tutte le dipendenze necessarie siano presenti quando viene creata l'istanza di questa classe e facilita la scrittura del codice di test in futuro.

    //use constructor injection for spring dependencies 
public CosmosSampleConfiguration(CosmosProperties properties){
    this.properties = properties;
}

    È possibile usare properties per ottenere l'URI e la chiave per l'account di Azure Cosmos DB e implementare cosmosClientBuilder come illustrato di seguito:

    @Bean
public CosmosClientBuilder cosmosClientBuilder() {
    DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();
    return new CosmosClientBuilder()
        .endpoint(properties.getUri())
        .key(properties.getKey())
        .directMode(directConnectionConfig);
}

    Questa implementazione

    1. Esegue il pull dell'URI e della chiave da properties
    2. Li inserisce nei metodi del generatore endpoint e key
    3. Configura anche la connessione di rete al servizio Azure Cosmos DB. In modalità diretta l'applicazione client comunica direttamente con le partizioni di Azure Cosmos DB back-end.

  4. Tornare a CosmosSampleConfiguration.java e trovare il metodo getDatabaseName:

    @Override
protected String getDatabaseName() { return ""; }

    Modificare il valore restituito predefinito in "Users", il nome del database. In questo modo, quando Spring Data si connette automaticamente ad Azure Cosmos DB all'avvio, si connetterà al database *Users.

  5. Passare a WebCustomer.java. Si noterà che la classe WebCustomer è preceduta da un'annotazione @Container:

    @Container(containerName = "", ru = "")

    @Container accetta due argomenti:

    • containerName: nome del contenitore di Azure Cosmos DB (WebCustomers)
    • ru: velocità effettiva con provisioning nel contenitore. 400 UR/sec è un valore predefinito adatto a un esercizio di Microsoft Learn.

    Personalizzare @Container per il caso d'uso, come illustrato di seguito:

    @Data
@NoArgsConstructor
@AllArgsConstructor
@Container(containerName = "WebCustomers", ru = "400")
public class WebCustomer {

  6. A questo punto, il progetto Spring Data è configurato per interagire con Azure Cosmos DB. Successivamente, verrà compilato ed eseguito il programma Hello World. Passare a src/main/java/com/azure/cosmos/examples/springexamples e aprire CosmosSample.java, che è un modello per l'applicazione Spring Data che verrà sviluppata. L'output dovrebbe essere simile al seguente:

    // 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.");
    }
}

    Così com'è, il codice dell'applicazione implementa un semplice progetto "Hello World".

  7. Se l'IDE offre strumenti per compilare ed eseguire l'applicazione Maven: compilare ed eseguire l'applicazione usando l'IDE e verificare che l'applicazione registri Hello World nel terminale.

  8. Se si userà il terminale per compilare ed eseguire l'applicazione Maven: usare il comando seguente per compilare il progetto Maven:

    mvn clean package

    Eseguire quindi:

    mvn spring-boot:run

    Verificare che l'applicazione registri l'output seguente nel terminale, tra tutti gli altri output:

    INFO: Hello World.

In questa unità sono state poste le basi per l'applicazione Java di Azure Cosmos DB. È stata personalizzata l'applicazione Maven ed è stato esteso un progetto "Hello World" di base per la connessione all'endpoint di Azure Cosmos DB.