Guida introduttiva: Usare Azure Cosmos DB per NoSQL con Azure SDK per Java

In questa guida introduttiva si distribuisce un'applicazione Azure Cosmos DB per NoSQL di base usando Azure SDK per Java. Azure Cosmos DB per NoSQL è un archivio dati senza schema che consente alle applicazioni di archiviare dati non strutturati nel cloud. Eseguire query sui dati nei contenitori ed eseguire operazioni comuni su singoli elementi usando Azure SDK per Java.

Documentazione di riferimento delle API | Codice sorgente della libreria | Pacchetto (Maven) | Azure Developer CLI

Prerequisiti

• Azure Developer CLI
• Docker Desktop
• Java 21

Se non si ha un account Azure, creare un account gratuito prima di iniziare.

Inizializzare il progetto

Usare l'interfaccia della riga di comando per sviluppatori di Azure (azd) per creare un account Azure Cosmos DB per NoSQL e distribuire un'applicazione di esempio in contenitori. L'applicazione di esempio usa la libreria client per gestire, creare, leggere ed eseguire query sui dati di esempio.

1. Aprire un terminale in una directory vuota.

2. Se non si è già autenticati, eseguire l'autenticazione all'interfaccia della riga di comando per sviluppatori di Azure usando azd auth login. Seguire i passaggi specificati dallo strumento per eseguire l'autenticazione all'interfaccia della riga di comando usando le credenziali di Azure preferite.

   azd auth login
   

3. Usare azd init per inizializzare il progetto.

   azd init --template cosmos-db-nosql-java-quickstart
   

4. Durante l'inizializzazione, configurare un nome di ambiente univoco.

5. Distribuire l'account Azure Cosmos DB usando azd up. I modelli Bicep distribuiscono anche un'applicazione Web di esempio.

   azd up
   

6. Durante il processo di approvvigionamento, selezionare la sottoscrizione, la località desiderata e il gruppo di risorse di destinazione. Attendere il completamento del processo di provisioning. Per il processo sono necessari circa 5 minuti.

7. Al termine del provisioning delle risorse di Azure, nell'output viene incluso un URL dell'applicazione Web in esecuzione.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Usare l'URL nella console per passare all'applicazione Web nel browser. Osservare l'output dell'app in esecuzione.

Installare la libreria client

La libreria client è disponibile tramite Maven, come pacchetto azure-spring-data-cosmos.

1. Passare alla cartella /src/web e aprire il file pom.xml.

2. Se non esiste già, aggiungere una voce per il pacchetto azure-spring-data-cosmos.

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

3. Aggiungere anche un'altra dipendenza per il pacchetto azure-identity, se non esiste già.

   <dependency>
       <groupId>com.azure</groupId>
       <artifactId>azure-identity</artifactId>
   </dependency>
   

Importare le librerie

Importare tutti i namespace necessari nel codice dell'applicazione.

import com.azure.cosmos.CosmosClientBuilder;
import com.azure.cosmos.models.PartitionKey;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.spring.data.cosmos.config.AbstractCosmosConfiguration;
import com.azure.spring.data.cosmos.config.CosmosConfig;
import com.azure.spring.data.cosmos.core.mapping.Container;
import com.azure.spring.data.cosmos.core.mapping.PartitionKey;
import com.azure.spring.data.cosmos.repository.CosmosRepository;
import com.azure.spring.data.cosmos.repository.Query;
import com.azure.spring.data.cosmos.repository.config.EnableCosmosRepositories;

Modello a oggetti

Esempi di codice

• Autenticare il client
• Ottieni un database
• Prendere un contenitore
• Creare un elemento
• Ricevere un oggetto
• Elementi di query

Il codice di esempio nel modello usa un database denominato cosmicworks e un contenitore denominato products. Il contenitore products contiene dettagli quali nome, categoria, quantità, identificatore univoco e flag di vendita per ogni prodotto. Il contenitore usa la proprietà /category come chiave di partizione logica.

Autenticare il client

Per prima cosa, questo esempio crea una nuova classe che eredita da AbstractCosmosConfiguration per configurare la connessione ad Azure Cosmos DB for NoSQL.

@Configuration
@EnableCosmosRepositories
public class CosmosConfiguration extends AbstractCosmosConfiguration {
}

All'interno della classe di configurazione, questo esempio crea una nuova istanza della classe CosmosClientBuilder e configura l'autenticazione usando un'istanza di DefaultAzureCredential.

@Bean
public CosmosClientBuilder getCosmosClientBuilder() {
    DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
        .build();
        
    return new CosmosClientBuilder()
        .endpoint("<azure-cosmos-db-nosql-account-endpoint>")
        .credential(credential);
}

Ottenere un database

Nella classe di configurazione l'esempio implementa un metodo per restituire il nome del database esistente denominato cosmicworks.

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

Ottenere un contenitore

Usare il decoratore del metodo Container per configurare una classe per rappresentare gli elementi in un contenitore. Creare la classe con tutti i membri da serializzare in JSON. In questo esempio il tipo ha un identificatore univoco e i campi per categoria, nome, quantità, prezzo e liquidazione.

@Container(containerName = "products", autoCreateContainer = false)
public class Item {
    private String id;
    private String name;
    private Integer quantity;
    private Boolean sale;

    @PartitionKey
    private String category;

    // Extra members omitted for brevity
}

Creare un elemento

Creare un elemento nel contenitore usando repository.save.

Item item = new Item(
    "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "gear-surf-surfboards",
    "Yamba Surfboard",
    12,
    false
);
Item created_item = repository.save(item);

Leggere un elemento

Eseguire un'operazione di lettura dei punti usando sia l'identificatore univoco (id) che i campi chiave di partizione. Usare repository.findById per recuperare in modo efficiente l'elemento specifico.

PartitionKey partitionKey = new PartitionKey("gear-surf-surfboards");
Optional<Item> existing_item = repository.findById("aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", partitionKey);
if (existing_item.isPresent()) {
    // Do something
}

Elementi della query

Eseguire una query su più elementi in un contenitore definendo una query nell'interfaccia del repository. Questo esempio utilizza il decoratore del metodo Query per definire un metodo che esegue questa query parametrizzata:

SELECT * FROM products p WHERE p.category = @category

@Repository
public interface ItemRepository extends CosmosRepository<Item, String> {

    @Query("SELECT * FROM products p WHERE p.category = @category")
    List<Item> getItemsByCategory(@Param("category") String category);

}

Recuperare tutti i risultati della query usando repository.getItemsByCategory. Scorrere i risultati della query.

List<Item> items = repository.getItemsByCategory("gear-surf-surfboards");
for (Item item : items) {
    // Do something
}

Esplora i tuoi dati

Usare l'estensione Di Visual Studio Code per Azure Cosmos DB per esplorare i dati NoSQL. È possibile eseguire operazioni di database di base, tra cui:

• Esecuzione di query usando un scrapbook o l'editor di query
• Modifica, aggiornamento, creazione ed eliminazione di elementi
• Importazione di dati in blocco da altre origini
• Gestione di database e contenitori

Per altre informazioni, vedere How-to use Visual Studio Code extension to explore Azure Cosmos DB for NoSQL data (Come usare l'estensione Visual Studio Code per esplorare i dati di Azure Cosmos DB per NoSQL).

Pulire le risorse

Quando l'applicazione o le risorse di esempio non sono più necessarie, rimuovere la distribuzione corrispondente e tutte le risorse.

azd down

Contenuto correlato

• Avvio rapido per .NET
• Guida introduttiva di Node. js
• Avvio rapido per Java
• Avvio rapido per Go
• Guida introduttiva a Rust