Quickstart: Azure Cosmos DB voor MongoDB-stuurprogramma voor Node.js

  • Artikel

VAN TOEPASSING OP: MongoDB

Ga aan de slag met het MongoDB NPM-pakket om databases, verzamelingen en documenten te maken in uw Azure Cosmos DB-resource. Volg deze stappen om het pakket te installeren en voorbeeldcode voor basistaken uit te proberen.

Notitie

De voorbeeldcodefragmenten zijn beschikbaar op GitHub als een JavaScript-project.

Api voor MongoDB-referentiedocumentatie | MongoDB-pakket (NuGet)

Vereisten

Controle van vereisten

  • Voer in een terminal- of opdrachtvenster uit node --version om te controleren of Node.js een van de LTS-versies is.
  • Voer az --version (Azure CLI) of Get-Module -ListAvailable AzureRM (Azure PowerShell) uit om te controleren of de juiste Azure-opdrachtregelprogramma's zijn geïnstalleerd.

Instellen

In deze sectie wordt uitgelegd hoe u een Azure Cosmos DB-account maakt en een project instelt dat gebruikmaakt van het MongoDB NPM-pakket.

Een Azure Cosmos DB-account maken

In deze quickstart maakt u één Azure Cosmos DB-account met behulp van de API voor MongoDB.

  1. Maak shell-variabelen voor accountName, resourceGroupName en locatie.

    # 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. Als u dat nog niet hebt gedaan, meldt u zich aan bij de Azure CLI met behulp van de az login opdracht.

  3. Gebruik de az group create opdracht om een nieuwe resourcegroep in uw abonnement te maken.

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

  4. Gebruik de az cosmosdb create opdracht om een nieuw Azure Cosmos DB voor MongoDB-account te maken met standaardinstellingen.

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

MongoDB-verbindingsreeks ophalen

  1. Zoek de API voor MongoDB-verbindingsreeks in de lijst met verbindingsreeks s voor het account met de az cosmosdb keys list opdracht.

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

  2. Noteer de WAARDEN VAN DE PRIMAIRE SLEUTEL . U gebruikt deze referenties later.

Een nieuwe JavaScript-app maken

Maak een nieuwe JavaScript-toepassing in een lege map met behulp van uw favoriete terminal. Gebruik de npm init opdracht om de prompts te starten om het package.json bestand te maken. Accepteer de standaardwaarden voor de prompts.

npm init

Het pakket installeren

Voeg het MongoDB NPM-pakket toe aan het JavaScript-project. Gebruik de npm install package opdracht die de naam van het npm-pakket opgeeft. Het dotenv pakket wordt gebruikt om de omgevingsvariabelen uit een .env bestand te lezen tijdens lokale ontwikkeling.

npm install mongodb dotenv

Omgevingsvariabelen configureren

Als u de WAARDEN VOOR VERBINDINGSREEKS in uw code wilt gebruiken, stelt u deze waarde in in de lokale omgeving waarop de toepassing wordt uitgevoerd. Als u de omgevingsvariabele wilt instellen, gebruikt u de terminal van uw voorkeur om de volgende opdrachten uit te voeren:

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

Objectmodel

Voordat u begint met het bouwen van de toepassing, gaan we kijken naar de hiërarchie van resources in Azure Cosmos DB. Azure Cosmos DB heeft een specifiek objectmodel dat wordt gebruikt voor het maken en openen van resources. Azure Cosmos DB maakt resources in een hiërarchie die bestaat uit accounts, databases, verzamelingen en documenten.

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

U gebruikt de volgende MongoDB-klassen om te communiceren met deze resources:

  • MongoClient - Deze klasse biedt een logische weergave aan de clientzijde voor de API voor MongoDB-laag in Azure Cosmos DB. Het clientobject wordt gebruikt om aanvragen aan de service te configureren en uitvoeren.
  • Db - Deze klasse is een verwijzing naar een database die al dan niet bestaat in de service. De database wordt gevalideerd aan de serverzijde wanneer u deze probeert te openen of een bewerking uitvoert.
  • Collection - Deze klasse is een verwijzing naar een verzameling die mogelijk nog niet bestaat in de service. De verzameling wordt gevalideerd aan de serverzijde wanneer u ermee probeert te werken.

Codevoorbeelden

Met de voorbeeldcode die in dit artikel wordt beschreven, wordt een database gemaakt met de naam adventureworksproductseen verzameling. De products verzameling is ontworpen om productdetails te bevatten, zoals naam, categorie, hoeveelheid en een verkoopindicator. Elk product bevat ook een unieke id.

Voor deze procedure gebruikt de database geen sharding.

De client verifiëren

  1. Maak vanuit de projectmap een index.js-bestand . Voeg in uw editor instructies toe om te verwijzen naar de MongoDB- en DotEnv npm-pakketten.

    // 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. Definieer een nieuw exemplaar van de MongoClient, klasse met behulp van de constructor en process.env. lees de omgevingsvariabele die u eerder hebt gemaakt.

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

Zie Snel aan de slag met MongoDB NodeJS Driver voor meer informatie over verschillende manieren om een MongoClient exemplaar te maken.

asynchrone bewerkingen instellen

Voeg in het index.js bestand de volgende code toe ter ondersteuning van de asynchrone bewerkingen:

async function main(){

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

}

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

De volgende codefragmenten moeten worden toegevoegd aan de hoofdfunctie om de syntaxis async/await af te handelen.

Verbinding maken met de database

Gebruik de MongoClient.connect methode om verbinding te maken met uw Azure Cosmos DB voor MongoDB-resource. De verbindingsmethode retourneert een verwijzing naar de database.

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

Database-exemplaar ophalen

Gebruik de MongoClient.db opdracht haalt een verwijzing naar een database op.

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

Verzamelingsexemplaren ophalen

De MongoClient.Db.collection krijgt een verwijzing naar een verzameling.

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

Gekoppelde exemplaren

U kunt de client, database en verzameling aan elkaar koppelen. Koppelen is handiger als u toegang nodig hebt tot meerdere databases of verzamelingen.

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

Een index maken

Gebruik de Collection.createIndex opdracht om een index te maken voor de eigenschappen van het document die u wilt gebruiken voor sorteren met de methode van FindCursor.sort MongoDB.

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

Een document maken

Maak een document met de producteigenschappen voor de adventureworks database:

  • Een _id eigenschap voor de unieke id van het product.
  • Een categorie-eigenschap . Deze eigenschap kan worden gebruikt als de logische partitiesleutel.
  • Een naameigenschap .
  • Een voorraadhoeveelheideigenschap.
  • Een verkoopeigenschap , waarmee wordt aangegeven of het product te koop is.
// 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`);

Maak een document in de verzameling door aan te roepen Collection.UpdateOne. In dit voorbeeld hebben we ervoor gekozen om upsert te maken in plaats van een nieuw document te maken voor het geval u deze voorbeeldcode meer dan één keer uitvoert.

Een document ophalen

In Azure Cosmos DB kunt u een goedkopere leesbewerking voor punten uitvoeren met behulp van zowel de unieke id (_id) als de partitiesleutel (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`);

Querydocumenten

Nadat u een document hebt ingevoegd, kunt u een query uitvoeren om alle documenten op te halen die overeenkomen met een specifiek filter. In dit voorbeeld vindt u alle documenten die overeenkomen met een specifieke categorie: gear-surf-surfboards. Zodra de query is gedefinieerd, roept Collection.find u aan om een FindCursor resultaat op te halen. Converteer de cursor naar een matrix om JavaScript-matrixmethoden te gebruiken.

// 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)}`));

Problemen oplossen:

  • Als er een fout optreedt, bijvoorbeeld The index path corresponding to the specified order-by item is excluded., controleert u of u de index hebt gemaakt.

De code uitvoeren

Met deze app maakt u een API voor mongoDB-database en -verzameling en maakt u een document en leest u vervolgens exact hetzelfde document terug. Ten slotte geeft het voorbeeld een query uit die alleen dat ene document moet retourneren. Bij elke stap voert het voorbeeld informatie uit naar de console over de stappen die deze heeft uitgevoerd.

Als u de app wilt uitvoeren, gebruikt u een terminal om naar de toepassingsmap te navigeren en de toepassing uit te voeren.

node index.js

De uitvoer van de app moet er ongeveer uitzien als in dit voorbeeld:

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

Resources opschonen

Wanneer u het Azure Cosmos DB for MongoDB-account niet meer nodig hebt, kunt u de bijbehorende resourcegroep verwijderen.

Gebruik de az group delete opdracht om de resourcegroep te verwijderen.

az group delete --name $resourceGroupName

Volgende stappen

In deze quickstart hebt u geleerd hoe u een Azure Cosmos DB voor MongoDB-account maakt, een database maakt en een verzameling maakt met behulp van het MongoDB-stuurprogramma. U kunt nu dieper ingaan op Azure Cosmos DB voor MongoDB om meer gegevens te importeren, complexe query's uit te voeren en uw Azure Cosmos DB MongoDB-resources te beheren.

MongoDB offline migreren naar Azure Cosmos DB voor MongoDB