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

VAN TOEPASSING OP: MongoDB

• .NET
• Python
• Java
• Node.js
• Go

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-pakketpakketten (NuGet) /Microsoft.Azure.Cosmos) | Azure Developer CLI

Vereisten

• Een Azure-account met een actief abonnement. Gratis een account maken
• Een GitHub-account

• Een Azure-account met een actief abonnement. Gratis een account maken
• Azure Developer CLI
• Docker Desktop

Instellen

Implementeer de ontwikkelcontainer van dit project in uw omgeving. Gebruik vervolgens de Azure Developer CLI (azd) om een Azure Cosmos DB voor MongoDB-account te maken en een containervoorbeeldtoepassing te implementeren. De voorbeeldtoepassing maakt gebruik van de clientbibliotheek voor het beheren, maken, lezen en opvragen van voorbeeldgegevens.

Belangrijk

GitHub-accounts bevatten gratis rechten voor opslag en kernuren. Zie inbegrepen opslag- en kernuren voor GitHub-accounts voor meer informatie.

1. Open een terminal in de hoofdmap van het project.

2. Verifiëren bij de Azure Developer CLI met behulp van azd auth login. Volg de stappen die door het hulpprogramma zijn opgegeven om te verifiëren bij de CLI met behulp van uw favoriete Azure-referenties.

   azd auth login
   

3. Gebruik azd init dit om het project te initialiseren.

   azd init
   

4. Configureer tijdens de initialisatie een unieke omgevingsnaam.

   Tip

   De omgevingsnaam wordt ook gebruikt als de naam van de doelresourcegroep. Voor deze quickstart kunt u overwegen .msdocs-cosmos-db

5. Implementeer het Azure Cosmos DB-account met behulp van azd up. De Bicep-sjablonen implementeren ook een voorbeeldwebtoepassing.

   azd up
   

6. Selecteer tijdens het inrichtingsproces uw abonnement en gewenste locatie. Wacht tot het inrichtingsproces is voltooid. Het proces kan ongeveer vijf minuten duren.

7. Zodra het inrichten van uw Azure-resources is voltooid, wordt er een URL naar de actieve webtoepassing opgenomen in de uitvoer.

   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. Gebruik de URL in de console om naar uw webtoepassing in de browser te navigeren. Bekijk de uitvoer van de actieve app.

   

---

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

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.

Hiërarchisch diagram met een Azure Cosmos DB-account bovenaan. Het account heeft twee onderliggende database-shards. Een van de database-shards bevat twee onderliggende verzamelings-shards. De andere database-shard bevat één onderliggend verzamelingsknooppunt. Die enkele verzamelingsshard heeft drie onderliggende doc-shards.

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

• De client verifiëren
• Database-exemplaar ophalen
• Verzamelingsexemplaren ophalen
• Gekoppelde exemplaren
• Een index maken
• Een document maken
• Een document ophalen
• Querydocumenten

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.

Azure-CLI

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

az group delete --name $resourceGroupName

Powershell

Gebruik de Remove-AzResourceGroup cmdlet om de resourcegroep te verwijderen.

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

Portal

1. Navigeer naar de resourcegroep die u eerder hebt gemaakt in Azure Portal.

   Tip

   In deze quickstart raden we de naam msdocs-cosmos-javascript-quickstart-rgaan.

2. Selecteer Resourcegroep verwijderen.

   

3. Voer in het dialoogvenster Weet u zeker dat u wilt verwijderen de naam van de resourcegroep in en selecteer Vervolgens Verwijderen.

   

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