Guida introduttiva: Usare Azure DocumentDB con il driver MongoDB per Node.js

In questa guida introduttiva si crea un'applicazione Azure DocumentDB di base usando Node.js. Azure DocumentDB è un archivio dati NoSQL che consente alle applicazioni di archiviare documenti nel cloud e accedervi usando driver MongoDB ufficiali. Questa guida illustra come creare documenti ed eseguire attività di base nel cluster di Azure DocumentDB usando Node.js.

Informazioni di riferimento | sulle APICodice sorgente | Pacchetto (npm)

Prerequisiti

Una sottoscrizione di Azure
- Se non hai un abbonamento Azure, crea un account gratuito

Node.js 22 o versione successiva

Creare un cluster di Azure DocumentDB

Per iniziare, è prima necessario creare un cluster Di Azure DocumentDB, che funge da base per l'archiviazione e la gestione dei dati NoSQL.

Accedere al portale di Azure (https://portal.azure.com).
Nel menu del portale di Azure o dalla pagina Home selezionare Crea una risorsa.
Nella pagina Nuovo cercare e selezionare Azure DocumentDB.
Nella pagina Crea cluster Azure DocumentDB e nella sezione Informazioni di base, nella sezione selezionare l'opzione Configura nella sezione Livello cluster.
Nella pagina Scalabilità configurare queste opzioni e quindi selezionare Salva per rendere persistenti le modifiche apportate al livello cluster.

Value

Livello cluster M30 tier, 2 vCore, 8-GiB RAM

Spazio di archiviazione per partizione 128 GiB

	Value
Livello cluster	`M30 tier, 2 vCore, 8-GiB RAM`
Spazio di archiviazione per partizione	`128 GiB`

Nella sezione Informazioni di base configurare le opzioni seguenti:

	Value
Subscription	Selezionare la sottoscrizione di Azure
Gruppo di risorse	Creare un nuovo gruppo di risorse o selezionare un gruppo di risorse esistente
Nome del cluster	Specificare un nome univoco globale
Ubicazione	Selezionare un'area di Azure supportata per la sottoscrizione
Versione di MongoDB	Selezionare `8.0`
Nome utente amministratore	Creare un nome utente per accedere al cluster come amministratore utente
Parola d’ordine	Usare una password univoca associata al nome utente

Screenshot che mostra i parametri del cluster.

Suggerimento

Registrare i valori usati per nome utente e password. Questi valori vengono usati più avanti in questa guida. Per altre informazioni sui valori validi, vedere Limitazioni del cluster.

Selezionare Avanti: Rete.
Nella sezione Regole del firewall della scheda Rete configurare queste opzioni:

Value

Metodo di connettività Public access

Consentire l'accesso pubblico da servizi e risorse di Azure in Azure a questo cluster abilitato
Aggiungere una regola del firewall per il dispositivo client corrente per concedere l'accesso al cluster selezionando + Aggiungi indirizzo IP client corrente.

Suggerimento

In molti ambienti aziendali, gli indirizzi IP del computer per sviluppatori sono nascosti a causa di una VPN o di altre impostazioni di rete aziendale. In questi casi, è possibile consentire temporaneamente l'accesso a tutti gli indirizzi IP aggiungendo l'intervallo 0.0.0.0 - 255.255.255.255 di indirizzi IP come regola del firewall. Usare questa regola del firewall solo temporaneamente come parte del test e dello sviluppo delle connessioni.
Selezionare Rivedi e crea.
Rivedere le impostazioni specificate e quindi selezionare Crea. La creazione del cluster richiede alcuni minuti. Attendere il completamento della distribuzione delle risorse.
Infine, selezionare Vai alla risorsa per passare al cluster Azure DocumentDB nel portale.

	Value
Metodo di connettività	`Public access`
Consentire l'accesso pubblico da servizi e risorse di Azure in Azure a questo cluster	abilitato

Screenshot che mostra le opzioni delle risorse goto.

Ottenere le credenziali del cluster

Ottenere le credenziali usate per connettersi al cluster.

Nella pagina del cluster selezionare l'opzione Stringhe di connessione nel menu della risorsa.
Nella sezione Stringhe di connessione copiare o registrare il valore dal campo Stringa di connessione .

Screenshot che mostra l'opzione delle stringhe di connessione.

Importante

La stringa di connessione nel portale non include il valore della password. È necessario sostituire il <password> segnaposto con le credenziali immesse al momento della creazione del cluster o immettere la password in modo interattivo.

Inizializzare il progetto

Creare un nuovo progetto Node.js nella directory corrente.

Iniziare in una directory vuota.
Apri un terminale nella directory corrente.
Inizializzare un progetto Node.js.
```
npm init -y
```
Installare TypeScript e inizializzare la configurazione typeScript (facoltativa per il supporto di TypeScript).
```
npm install -D typescript @types/node
npx tsc --init
```

Installare la libreria client

La libreria client è disponibile tramite npm, come mongodb pacchetto.

Installare il driver Node.js MongoDB usando npm.
```
npm install mongodb
```
Aprire ed esaminare il file dipackage.json per verificare che la voce del pacchetto esista.

Importare i moduli necessari nel codice dell'applicazione:

import { MongoClient, Db, Collection, Document } from 'mongodb';

const { MongoClient } = require('mongodb');

Modello a oggetti

Nome	Description
`MongoClient`	Tipo usato per connettersi a MongoDB.
`Db`	Rappresenta un database nel cluster.
`Collection<Document>`	Rappresenta una raccolta all'interno di un database nel cluster.

Il codice in questa applicazione si connette a un database denominato adventureworks e a una raccolta denominata products. La products raccolta contiene dettagli come nome, categoria, quantità, un identificatore unico e un indicatore di vendita per ogni prodotto. Gli esempi di codice qui eseguono le operazioni più comuni quando si lavora con una raccolta.

Autenticare il client

Prima di tutto, connettersi al client usando una stringa di connessione di base.

Creare la funzione main e configurare la stringa di connessione. Sostituire <your-cluster-name>, <your-username>e <your-password> con le informazioni effettive del cluster.

async function main(): Promise<void> {
    // Connection string for Azure DocumentDB cluster
    const connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";

    // Create a new client and connect to the server
    const client = new MongoClient(connectionString);

async function main() {
    // Connection string for Azure DocumentDB cluster
    const connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";

    // Create a new client and connect to the server
    const client = new MongoClient(connectionString);

Connettersi al client MongoDB e verificare la connessione.

    try {
        // Connect to the MongoDB cluster
        await client.connect();

        // Ping the server to verify connection
        await client.db("admin").command({ ping: 1 });
        console.log("Successfully connected and pinged Azure DocumentDB");

    try {
        // Connect to the MongoDB cluster
        await client.connect();

        // Ping the server to verify connection
        await client.db("admin").command({ ping: 1 });
        console.log("Successfully connected and pinged Azure DocumentDB");

Ottieni una raccolta

Ora, ottieni il database e la collezione. Se il database e la raccolta non esistono già, usare il driver per crearlo automaticamente.

Ottenere un riferimento al database.

        // Get database reference
        const database: Db = client.db("adventureworks");
        console.log(`Connected to database: ${database.databaseName}`);

        // Get database reference
        const database = client.db("adventureworks");
        console.log(`Connected to database: ${database.databaseName}`);

Ottenere un riferimento alla raccolta all'interno del database.

        // Get collection reference
        const collection: Collection<Document> = database.collection("products");
        console.log("Connected to collection: products");

        // Get collection reference
        const collection = database.collection("products");
        console.log("Connected to collection: products");

Creare un documento

Creare quindi un paio di nuovi documenti all'interno della raccolta. Eseguire l'upsert dei documenti per assicurarsi che sostituisca eventuali documenti esistenti, se già esistenti con lo stesso identificatore univoco.

Creare documenti di prodotto di esempio.

        // Create sample products
        interface Product {
            _id: string;
            name: string;
            category: string;
            quantity: number;
            price: number;
            sale: boolean;
        }

        const products: Product[] = [
            {
                _id: "00000000-0000-0000-0000-000000004018",
                name: "Windry Mittens",
                category: "apparel-accessories-gloves-and-mittens",
                quantity: 121,
                price: 35.00,
                sale: false,
            },
            {
                _id: "00000000-0000-0000-0000-000000004318",
                name: "Niborio Tent",
                category: "gear-camp-tents",
                quantity: 140,
                price: 420.00,
                sale: true,
            }
        ];

        // Create sample products
        const products = [
            {
                _id: "00000000-0000-0000-0000-000000004018",
                name: "Windry Mittens",
                category: "apparel-accessories-gloves-and-mittens",
                quantity: 121,
                price: 35.00,
                sale: false,
            },
            {
                _id: "00000000-0000-0000-0000-000000004318",
                name: "Niborio Tent",
                category: "gear-camp-tents",
                quantity: 140,
                price: 420.00,
                sale: true,
            }
        ];

Inserire i documenti usando operazioni upsert.

        // Insert documents with upsert
        for (const product of products) {
            const filter = { _id: product._id };
            const options = { upsert: true };

            await collection.replaceOne(filter, product, options);
            console.log(`Upserted product: ${product.name}`);
        }

        // Insert documents with upsert
        for (const product of products) {
            const filter = { _id: product._id };
            const options = { upsert: true };

            await collection.replaceOne(filter, product, options);
            console.log(`Upserted product: ${product.name}`);
        }

Recuperare un documento

Successivamente, eseguire un'operazione di lettura puntuale per recuperare un documento specifico dalla raccolta.

Definire il filtro per trovare un documento specifico in base all'ID.

        // Retrieve a specific document by ID
        const filter = { _id: "00000000-0000-0000-0000-000000004018" };

        // Retrieve a specific document by ID
        const filter = { _id: "00000000-0000-0000-0000-000000004018" };

Eseguire la query e recuperare il risultato.

        const retrievedProduct = await collection.findOne(filter);

        if (retrievedProduct) {
            console.log(`Retrieved product: ${retrievedProduct.name} - $${retrievedProduct.price}`);
        } else {
            console.log("Product not found");
        }

        const retrievedProduct = await collection.findOne(filter);

        if (retrievedProduct) {
            console.log(`Retrieved product: ${retrievedProduct.name} - $${retrievedProduct.price}`);
        } else {
            console.log("Product not found");
        }

Eseguire query su documenti

Infine, eseguire query su più documenti usando il linguaggio mqL (MongoDB Query Language).

Definire una query per trovare documenti corrispondenti a criteri specifici.

        // Query for products on sale
        const saleFilter = { sale: true };
        const saleProducts = await collection.find(saleFilter).toArray();

        // Query for products on sale
        const saleFilter = { sale: true };
        const saleProducts = await collection.find(saleFilter).toArray();

Scorrere i risultati per visualizzare i documenti corrispondenti.

        console.log("Products on sale:");
        for (const product of saleProducts) {
            console.log(`- ${product.name}: $${product.price.toFixed(2)} (Category: ${product.category})`);
        }

    } catch (error) {
        console.error("An error occurred:", error);
    } finally {
        await client.close();
    }
}

main().catch(console.error);

        console.log("Products on sale:");
        for (const product of saleProducts) {
            console.log(`- ${product.name}: $${product.price.toFixed(2)} (Category: ${product.category})`);
        }

    } catch (error) {
        console.error("An error occurred:", error);
    } finally {
        await client.close();
    }
}

main().catch(console.error);

Esplora i tuoi dati con Visual Studio Code

Usare l'estensione DocumentDB in Visual Studio Code per eseguire operazioni di database di base, tra cui l'esecuzione di query, l'inserimento, l'aggiornamento e l'eliminazione di dati.

Aprire Visual Studio Code.
Passare alla visualizzazione Estensioni e cercare il termine DocumentDB. Individuare l'estensione DocumentDB per VS Code .
Selezionare il pulsante Installa per l'estensione. Attendere il completamento dell'installazione. Se richiesto, ricaricare Visual Studio Code.
Passare all'estensione DocumentDB selezionando l'icona corrispondente nella barra delle attività.
Nel riquadro Connessioni documentDB selezionare + Nuova connessione....
Nella finestra di dialogo selezionare Individuazione servizi e quindi Azure DocumentDB - Individuazione dei servizi di Azure.
Selezionare la sottoscrizione di Azure e il cluster Azure DocumentDB appena creato.

Suggerimento

In molti ambienti aziendali, gli indirizzi IP del computer per sviluppatori sono nascosti a causa di una VPN o di altre impostazioni di rete aziendale. In questi casi, è possibile consentire temporaneamente l'accesso a tutti gli indirizzi IP aggiungendo l'intervallo 0.0.0.0 - 255.255.255.255 di indirizzi IP come regola del firewall. Usare questa regola del firewall solo temporaneamente come parte del test e dello sviluppo delle connessioni. Per altre informazioni, vedere Configurare il firewall.
Tornare al riquadro DocumentDB Connections, espandere il nodo per il cluster e navigare verso i nodi di documenti e raccolte esistenti.
Aprire il menu di scelta rapida per la raccolta e quindi selezionare Nuovo DocumentDB Scrapbook>.
Immettere i comandi MQL (MongoDB Query Language) seguenti e quindi selezionare Esegui tutto. Osserva l'output generato dai comandi.
```
db.products.find({
  price: { $gt: 200 },
  sale: true
})
.sort({ price: -1 })
.limit(3)
```

Pulire le risorse

Al termine dell'operazione con il cluster Azure DocumentDB, è possibile eliminare le risorse di Azure create in modo da non comportare costi aggiuntivi.

Nella barra di ricerca del portale di Azure cercare e selezionare Gruppi di risorse.
Nell'elenco, selezionare il gruppo di risorse utilizzato in questa guida introduttiva.
Nella pagina del gruppo di risorse selezionare Elimina gruppo di risorse.
Nella finestra di dialogo di conferma dell'eliminazione, immettere il nome del gruppo di risorse per confermarne l'eliminazione. Infine, selezionare Elimina per eliminare definitivamente il gruppo di risorse.

Che cos'è Azure DocumentDB?

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-11-19