Guida introduttiva: Libreria Azure Cosmos DB per NoSQL per Node.js

Articolo
03/28/2024

SI APPLICA A: NoSQL

Introduzione alla libreria client di Azure Cosmos DB per NoSQL per Node.js per eseguire query sui dati nei contenitori ed eseguire operazioni comuni su singoli elementi. Seguire questa procedura per distribuire una soluzione minima nell'ambiente usando Azure Developer CLI.

Documentazione | di riferimento sulle API Pacchetto del codice | sorgente della libreria (npm) | Interfaccia della riga di comando per sviluppatori di Azure

Prerequisiti

Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
Account GitHub

Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
Azure Developer CLI
Docker Desktop

Configurazione

Distribuire il contenitore di sviluppo di questo progetto nell'ambiente. Usare quindi Azure Developer CLI (azd) per creare un account Azure Cosmos DB for 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.

Importante

Gli account GitHub includono un diritto di archiviazione e ore di core senza costi. Per altre informazioni, vedere le ore di archiviazione e i core inclusi per gli account GitHub.

Aprire un terminale nella directory radice del progetto.
Eseguire l'autenticazione in 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
```
Usare azd init per inizializzare il progetto.
```
azd init
```
Durante l'inizializzazione, configurare un nome di ambiente univoco.

Suggerimento

Il nome dell'ambiente verrà usato anche come nome del gruppo di risorse di destinazione. Per questa guida introduttiva, è consigliabile usare msdocs-cosmos-db-.
Distribuire l'account Azure Cosmos DB usando azd up. I modelli Bicep distribuiscono anche un'applicazione Web di esempio.
```
azd up
```
Durante il processo di provisioning, selezionare la sottoscrizione e il percorso desiderato. Attendere il completamento del processo di provisioning. Per il processo sono necessari circa 5 minuti.

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.

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 il Gestione pacchetti Node, come @azure/cosmos pacchetto.

Aprire un terminale e passare alla cartella /src.
```
cd ./src
```
Se non è già installato, installare il pacchetto @azure/cosmos usando npm install.
```
npm install --save @azure/cosmos
```
Installare anche il pacchetto @azure/identity se non è già stato fatto.
```
npm install --save @azure/identity
```
Aprire ed esaminare il file src/package.json per verificare che le azure-cosmos voci e azure-identity esistano entrambe.

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.

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

Le richieste dell'applicazione per la maggior parte dei servizi di Azure devono essere autorizzate. Usare il tipo DefaultAzureCredential come metodo preferito per implementare una connessione senza password tra le applicazioni e Azure Cosmos DB for NoSQL. DefaultAzureCredential supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione.

Importante

È anche possibile autorizzare le richieste ai servizi di Azure usando direttamente password, stringhe di connessione o altre credenziali. Tuttavia, questo approccio deve essere usato con cautela. Gli sviluppatori devono essere diligenti per non esporre mai questi segreti in una posizione non sicura. Chiunque possa accedere alla password o alla chiave privata è in grado di eseguire l'autenticazione al servizio di database. DefaultAzureCredential offre vantaggi di gestione e sicurezza migliorati rispetto alla chiave dell'account per consentire l'autenticazione senza password senza rischi di archiviazione delle chiavi.

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,
    aadCredentials: credential
});

Ottenere un database

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

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

Ottenere un contenitore

Recuperare il contenitore di products esistente usando database.container.

const 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à.

var item = {
    'id': '70b63682-b93a-4c77-aad2-65501347265f',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

var response = await container.items.upsert(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 recuperare in modo efficiente l'elemento specifico.

var id = '70b63682-b93a-4c77-aad2-65501347265f';
var partitionKey = 'gear-surf-surfboards';

var response = await container.item(id, partitionKey).read();
var read_item = 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'
        }
    ]
};

var response = await container.items.query(querySpec).fetchAll();
for (var item of response.resources) {

}

Passaggio successivo

Esercitazione: Creare un'app Web Node.js