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

  • Articolo

SI APPLICA A: MongoDB

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

Nota

I frammenti di codice di esempio sono disponibili in GitHub come progetto JavaScript.

Documentazione di riferimento dell'API per MongoDB | Pacchetto MongoDB (NuGet)

Prerequisiti

Controllo dei prerequisiti

  • In un terminale o in una finestra di comando eseguire node --version per verificare che Node.js sia una delle versioni LTS.
  • Eseguire az --version (interfaccia della riga di comando di Azure) o Get-Module -ListAvailable AzureRM (Azure PowerShell) per verificare che siano installati gli strumenti da riga di comando di Azure appropriati.

Configurazione

Questa sezione illustra come creare un account Azure Cosmos DB e configurare un progetto che usa il pacchetto npm MongoDB.

Creare un account Azure Cosmos DB

Questo argomento di avvio rapido creerà un singolo account Azure Cosmos DB tramite l'API per MongoDB.

  1. Creare variabili della shell per accountName, resourceGroupNamee location.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-quickstart-rg"
location="westus"

# Variable for account name with a randomnly generated suffix
let suffix=$RANDOM*$RANDOM
accountName="msdocs-$suffix"

  2. Se non è già stato fatto, accedere all'interfaccia della riga di comando di Azure usando il comando az login.

  3. Usare il comando az group create per creare un nuovo gruppo di risorse nella sottoscrizione.

    az group create \
    --name $resourceGroupName \
    --location $location

  4. Usare il comando az cosmosdb create per creare un nuovo account Azure Cosmos DB for MongoDB con le impostazioni predefinite.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location
    --kind MongoDB

Ottenere la stringa di connessione di MongoDB

  1. Trovare la stringa di connessione dell'API per MongoDB dall'elenco delle stringhe di connessione per l'account con il comando az cosmosdb keys list.

    az cosmosdb keys list --type connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName

  2. Registrare i valori PRIMARY KEY. Queste credenziali saranno necessarie più avanti.

Creare una nuova app JavaScript

Creare una nuova applicazione JavaScript in una cartella vuota usando il terminale preferito. Usare il comando npm init per avviare i prompt per la creazione del file package.json. Accettare le impostazioni predefinite per i prompt.

npm init

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

Configurare le variabili di ambiente

Per usare i valori della STRINGA DI CONNESSIONE all'interno del codice, impostare questo valore nell'ambiente locale che esegue l'applicazione. Per impostare la variabile di ambiente, usare il terminale preferito per eseguire i comandi seguenti:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

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.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, collections, and docs.

Per interagire con queste risorse, si useranno 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 può esistere o meno nel servizio. Il database viene convalidato sul lato server quando si tenta di accedervi o di eseguire un'operazione su di essa.
  • Collection : questa classe è un riferimento a una raccolta che può non esistere ancora nel servizio. La raccolta viene convalidata sul lato server quando si tenta di usarla.

Esempi di codice

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 userà 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 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 dovrebbe essere 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.

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

az group delete --name $resourceGroupName

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