Guida introduttiva: Usare Azure Cosmos DB for NoSQL con Azure SDK per Node.js

• .NET
• Node.js
• Java
• Python
• Go
• Rust

In questa guida introduttiva si distribuisce un'applicazione Azure Cosmos DB per NoSQL di base usando Azure SDK per Node.js. 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 Node.js.

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

Prerequisiti

• Azure Developer CLI
• Docker Desktop
• Node.js 22 o versione successiva

Se non si ha un account Azure, crearne uno 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 a Azure Developer CLI 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-nodejs-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 provisioning, selezionare la sottoscrizione, la posizione 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 Node Package Manager, come pacchetto @azure/cosmos.

1. Aprire un terminale e passare alla cartella /src.

   cd ./src
   

2. Se non è già installato, installare il pacchetto @azure/cosmos usando npm install.

   npm install --save @azure/cosmos
   

3. Installare anche il pacchetto @azure/identity se non è già stato fatto.

   npm install --save @azure/identity
   

4. Aprire ed esaminare il file src/package.json per verificare che esistano entrambe le voci azure-cosmos e azure-identity.

Importare le librerie

Importa i tipi DefaultAzureCredential e CosmosClient nel codice dell'applicazione.

import { DefaultAzureCredential } from '@azure/identity';
import { CosmosClient } from '@azure/cosmos';

Importare tutti i tipi necessari nel codice dell'applicazione.

import { PagedAsyncIterableIterator } from '@azure/core-paging';
import { DefaultAzureCredential, TokenCredential } from '@azure/identity';
import { Container, CosmosClient, Database, FeedResponse, ItemResponse, SqlQuerySpec } from '@azure/cosmos';

Modello a oggetti

Nome	Descrizione
CosmosClient	Questa classe è la classe client primaria e viene usata per gestire i metadati o i database a livello di account.
Database	Questa classe rappresenta un database all'interno dell'account.
Container	Questa classe viene usata principalmente per eseguire operazioni di lettura, aggiornamento ed eliminazione sul contenitore o sugli elementi archiviati all'interno del contenitore.
PartitionKey	Questa classe rappresenta una chiave di partizione logica. Questa classe è necessaria per molte operazioni e query comuni.
SqlQuerySpec	Questa interfaccia rappresenta una query SQL e tutti i parametri di query.

Esempi di codice

• Autenticare il client
• Ottenere un database
• Ottenere un contenitore
• Creare un elemento
• Ottenere un elemento
• Eseguire query sugli elementi

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

Questo esempio crea una nuova istanza del tipo CosmosClient ed esegue l'autenticazione usando un'istanza di DefaultAzureCredential.

const credential = new DefaultAzureCredential();

const client = new CosmosClient({
    endpoint: '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

const credential: TokenCredential = new DefaultAzureCredential();

const client = new CosmosClient({
    endpoint: '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

Recuperare un database

Usare client.database per recuperare il database esistente denominato cosmicworks.

const database = client.database('cosmicworks');

const database: Database = client.database('cosmicworks');

Recuperare un contenitore

Recuperare il contenitore products esistente usando database.container.

const container = database.container('products');

const container: Container = database.container('products');

Creare un elemento

Creare un nuovo oggetto 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 vendita. Creare un elemento nel contenitore usando container.items.upsert. Questo metodo esegue l'upsert dell'elemento, in pratica sostituendolo, se esiste già.

const item = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response = await container.items.upsert(item);

const item: Product = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response: ItemResponse<Product> = await container.items.upsert<Product>(item);

Leggere un elemento

Eseguire un'operazione di lettura dei punti usando sia l'identificatore univoco (id) che i campi chiave di partizione. Usare container.item per ottenere un puntatore a un elemento e item.read per recuperare in modo efficiente l'elemento specifico.

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response = await container.item(id, partitionKey).read();
let read_item = response.resource;

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response: ItemResponse<Product> = await container.item(id, partitionKey).read<Product>();
let read_item: Product = response.resource!;

Eseguire query sugli elementi

Eseguire una query su più elementi in un contenitore usando container.items.query. Trovare tutti gli elementi all'interno di una categoria specificata usando questa query con parametri:

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

Recuperare tutti i risultati della query usando query.fetchAll. Scorrere i risultati della query.

const querySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response = await container.items.query(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

const querySpec: SqlQuerySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response: FeedResponse<Product> = await container.items.query<Product>(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

Esplorare i 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, senza limitazione alcuna:

• 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
• Gestire database e contenitori

Per altre informazioni, vedere Come usare l'estensione di Visual Studio Code per esplorare i dati di Azure Cosmos DB for 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

Contenuti correlati

• Avvio rapido per .NET
• Guida di avvio rapido per Java
• Avvio rapido per Python
• Avvio rapido per Go
• Guida introduttiva a Rust