Avvio rapido: Driver Azure Cosmos DB for MongoDB per Node.js

SI APPLICA A: MongoDB

• Node.js
• Python
• Java
• .NET
• Golang

È possibile iniziare a usare il pacchetto npm MongoDB per creare database, raccolte e documenti all'interno della propria risorsa di Azure Cosmos DB. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.

Documentazione di riferimento dell’API per MongoDB | Pacchetto MongoDB (NuGet) packages/Microsoft.Azure.Cosmos) | Azure Developer CLI

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 per MongoDB 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 entitlement di archiviazione e ore di core senza costi. Per altre informazioni, vedere l'articolo sullo spazio di archiviazione e le ore di core inclusi per gli account GitHub.

1. Aprire un terminale nella directory radice del progetto.

2. 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
   

3. Usare azd init per inizializzare il progetto.

   azd init --template cosmos-db-mongodb-nodejs-quickstart
   

   Nota

   Questo avvio rapido usa il modello del repository GitHub azure-samples/cosmos-db-mongodb-nodejs-quickstart. Azure Developer CLI clonerà automaticamente questo progetto nel computer, se non è già presente.

4. 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 questo avvio rapido è consigliabile usare msdocs-cosmos-db.

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 e la posizione desiderata. 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 il pacchetto

Aggiungere il pacchetto npm MongoDB al progetto JavaScript. Usare il comando npm install package che specifica il nome del pacchetto npm. Il pacchetto dotenv viene usato per leggere le variabili di ambiente da un file di .env durante lo sviluppo locale.

npm install mongodb dotenv

Modello a oggetti

Prima di iniziare a compilare l'applicazione, verrà esaminata la gerarchia di risorse in Azure Cosmos DB. Azure Cosmos DB ha un modello a oggetti specifico usato per creare e accedere alle risorse. Azure Cosmos DB crea risorse in una gerarchia costituita da account, database, raccolte e documenti.

Diagramma gerarchico che mostra al vertice un account di Azure Cosmos DB. L'account ha due partizioni di database figlio. Una delle partizioni del database include due partizioni di raccolta figlio. L'altra partizione di database include un singolo nodo di raccolta figlio. La singola partizione di raccolta ha tre partizioni di documento figlio.

Per interagire con queste risorse, usare le classi di MongoDB seguenti:

• MongoClient: questa classe fornisce una rappresentazione logica lato client per il livello dell'API per MongoDB in Azure Cosmos DB. L'oggetto client viene usato per configurare ed eseguire richieste nel servizio.
• Db: questa classe è un riferimento a un database che potrebbe o non potrebbe esistere ancora nel servizio. Il database viene convalidato lato server quando si tenta di accedervi o di eseguire un'operazione su di esso.
• Collection: questa classe è un riferimento a una raccolta che potrebbe non esistere ancora nel servizio. La raccolta viene convalidata sul lato server quando si tenta di usarla.

Esempi di codice

• Autenticare il client
• Ottenere un'istanza del database
• Ottenere un'istanza della raccolta
• Usare metodi concatenati
• Creare un indice
• Creare un documento
• Ottenere un documento
• Esegui query

Il codice di esempio descritto in questo articolo crea un database denominato adventureworks con una raccolta denominata products. La raccolta products è progettata per contenere dettagli del prodotto, ad esempio nome, categoria, quantità e indicatore di vendita. Ogni prodotto contiene anche un identificatore univoco.

Per questa procedura, il database non usa il partizionamento orizzontale.

Autenticare il client

1. Dalla directory del progetto creare un file index.js. Nell'editor aggiungere istruzioni requires per fare riferimento ai pacchetti npm MongoDB e DotEnv.

   // Read .env file and set environment variables
   require('dotenv').config();
   const random = Math.floor(Math.random() * 100);
   
   // Use official mongodb driver to connect to the server
   const { MongoClient, ObjectId } = require('mongodb');
   

2. Definire una nuova istanza della classe MongoClient, usando il costruttore e process.env. per leggere la variabile di ambiente creata in precedenza.

   // New instance of MongoClient with connection string
   // for Cosmos DB
   const url = process.env.COSMOS_CONNECTION_STRING;
   const client = new MongoClient(url);
   

Per altre informazioni sui diversi modi per creare un'istanza di MongoClient, vedere l'argomento di avvio rapido sul driver MongoDB per NodeJS.

Configurare le operazioni asincrone

Nel file index.js aggiungere il codice seguente per supportare le operazioni asincrone:

async function main(){

// The remaining operations are added here
// in the main function

}

main()
  .then(console.log)
  .catch(console.error)
  .finally(() => client.close());

I frammenti di codice seguenti devono essere aggiunti alla funzione main per gestire la sintassi async/await.

Stabilire la connessione al database

Usare il metodo MongoClient.connect per connettersi alla risorsa Azure Cosmos DB for MongoDB. Il metodo connect restituisce un riferimento al database.

// Use connect method to connect to the server
await client.connect();

Ottenere un'istanza del database

Usare MongoClient.db per ottenere un riferimento a un database.

// Database reference with creation if it does not already exist
const db = client.db(`adventureworks`);
console.log(`New database:\t${db.databaseName}\n`);

Ottenere un'istanza della raccolta

Usare MongoClient.Db.collection per ottenere un riferimento a una raccolta.

// Collection reference with creation if it does not already exist
const collection = db.collection('products');
console.log(`New collection:\t${collection.collectionName}\n`);

Istanze concatenate

È possibile concatenare insieme il client, il database e la raccolta. Il concatenamento è più pratico se è necessario accedere a più database o raccolte.

const db = await client.db(`adventureworks`).collection('products').updateOne(query, update, options)

Creare un indice

Usare Collection.createIndex per creare un indice nelle proprietà del documento da usare per l'ordinamento con il metodo FindCursor.sort di MongoDB.

// create index to sort by name
const indexResult = await collection.createIndex({ name: 1 });
console.log(`indexResult: ${JSON.stringify(indexResult)}\n`);

Creare un documento

Creare un documento con le proprietà di product per il database adventureworks:

• Una proprietà _id per l'identificatore univoco del prodotto.
• Una proprietà category. Questa proprietà può essere usata come chiave della partizione logica.
• Una proprietà name.
• Una proprietà quantity delle scorte.
• Una proprietà sale che indica se il prodotto è in vendita.

// Create new doc and upsert (create or replace) to collection
const product = {
    category: "gear-surf-surfboards",
    name: `Yamba Surfboard-${random}`,
    quantity: 12,
    sale: false
};
const query = { name: product.name};
const update = { $set: product };
const options = {upsert: true, new: true};

// Insert via upsert (create or replace) doc to collection directly
const upsertResult1 = await collection.updateOne(query, update, options);
console.log(`upsertResult1: ${JSON.stringify(upsertResult1)}\n`);

// Update via upsert on chained instance
const query2 = { _id: ObjectId(upsertResult1.upsertedId) };
const update2 = { $set: { quantity: 20 } };
const upsertResult2 = await client.db(`adventureworks`).collection('products').updateOne(query2, update2, options);
console.log(`upsertResult2: ${JSON.stringify(upsertResult2)}\n`);

Creare un documento nella raccolta chiamando Collection.UpdateOne. In questo esempio si è scelto di eseguire l'upsert anziché creare un nuovo documento nel caso in cui si esegua il codice di esempio più di una volta.

Ottenere un documento

In Azure Cosmos DB è possibile eseguire un'operazione di lettura dei punti meno costosa usando sia l'identificatore univoco (_id) che la chiave di partizione (category).

// Point read doc from collection:
// - without sharding, should use {_id}
// - with sharding,    should use {_id, partitionKey }, ex: {_id, category}
const foundProduct = await collection.findOne({
    _id: ObjectId(upsertResult1.upsertedId), 
    category: "gear-surf-surfboards"
});
console.log(`foundProduct: ${JSON.stringify(foundProduct)}\n`);

Documenti di query

Dopo aver inserito un documento, è possibile eseguire una query per ottenere tutti i documenti che corrispondono a un filtro specifico. Questo esempio trova tutti i documenti corrispondenti a una categoria specifica: gear-surf-surfboards. Dopo aver definito la query, chiamare Collection.find per ottenere un risultato FindCursor. Convertire il cursore in una matrice per usare i metodi della matrice JavaScript.

// select all from product category
const allProductsQuery = { 
    category: "gear-surf-surfboards" 
};

// get all documents, sorted by name, convert cursor into array
const products = await collection.find(allProductsQuery).sort({name:1}).toArray();
products.map((product, i ) => console.log(`${++i} ${JSON.stringify(product)}`));

Risoluzione dei problemi:

• Se viene restituito un errore, ad esempio The index path corresponding to the specified order-by item is excluded., verificare di aver creato l'indice.

Eseguire il codice

Questa app crea un'API per il database e la raccolta MongoDB, crea un documento e quindi legge lo stesso documento. Infine, nell’esempio viene eseguita una query che deve restituire solo tale singolo documento. Con ogni passaggio, l’esempio restituisce informazioni alla console sui passaggi eseguiti.

Per eseguire l'app, usare un terminale per passare alla directory dell'applicazione ed eseguire l'applicazione.

node index.js

L'output dell'app sarà simile a questo esempio:

New database:   adventureworks

New collection: products

upsertResult1: {"acknowledged":true,"modifiedCount":0,"upsertedId":"62b1f492ff69395b30a03169","upsertedCount":1,"matchedCount":0}

upsertResult2: {"acknowledged":true,"modifiedCount":1,"upsertedId":null,"upsertedCount":0,"matchedCount":1}

foundProduct: {"_id":"62b1f492ff69395b30a03169","name":"Yamba Surfboard-93","category":"gear-surf-surfboards","quantity":20,"sale":false}

indexResult: "name_1"

1 {"_id":"62b1f47dacbf04e86c8abf25","name":"Yamba Surfboard-11","category":"gear-surf-surfboards","quantity":20,"sale":false}
done

Pulire le risorse

Quando l'account Azure Cosmos DB for MongoDB non è più necessario, è possibile eliminare il gruppo di risorse corrispondente.

Interfaccia della riga di comando di Azure

Usare il comando az group delete per eliminare il gruppo di risorse.

az group delete --name $resourceGroupName

PowerShell

Usare il cmdlet Remove-AzResourceGroup per eliminare il gruppo di risorse.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Portale

1. Passare al gruppo di risorse precedentemente creato nel portale di Azure.

   Suggerimento

   In questo argomento di avvio rapido è stato consigliato il nome msdocs-cosmos-javascript-quickstart-rg.

2. Selezionare Elimina gruppo di risorse.

   

3. Nella finestra di dialogo Eliminare immettere il nome del gruppo di risorse e quindi selezionare Elimina.

   

Passaggi successivi

In questo argomento di avvio rapido si è appreso come creare un account Azure Cosmos DB for MongoDB, un database e una raccolta usando il driver MongoDB. È ora possibile esplorare più in dettaglio Azure Cosmos DB for MongoDB per importare più dati, eseguire query complesse e gestire le risorse di Azure Cosmos DB for MongoDB.

Eseguire la migrazione offline di MongoDB ad Azure Cosmos DB for MongoDB