Schnellstart: Azure Cosmos DB for MongoDB-Treiber für Node.js

GILT FÜR: MongoDB

Erste Schritte mit dem MongoDB-npm-Paket zum Erstellen von Datenbanken, Sammlungen und Dokumenten in Ihrer Azure Cosmos DB-Ressource. Führen Sie die nachfolgenden Schritte aus, um das Paket zu installieren und den Beispielcode für grundlegende Aufgaben zu testen.

Referenzdokumentation der API für MongoDB | MongoDB-Paket (NuGet) packages/Microsoft.Azure.Cosmos) | Azure Developer CLI

Voraussetzungen

Einrichten

Stellen Sie den Entwicklungscontainer dieses Projekts in Ihrer Umgebung bereit. Verwenden Sie dann das Azure Developer CLI (azd), um ein Azure Cosmos DB for MongoDB-Konto zu erstellen und eine containerisierte Beispielanwendung bereitzustellen. Die Beispielanwendung verwendet die Clientbibliothek zum Verwalten, Erstellen, Lesen und Abfragen von Beispieldaten.

1. Öffnen Sie ein Terminal im Stammverzeichnis des Projekts.

2. Authentifizieren Sie sich mithilfe von azd auth login bei Azure Developer CLI. Führen Sie die vom Tool angegebenen Schritte aus, um sich mit Ihren bevorzugten Azure-Anmeldeinformationen bei der CLI zu authentifizieren.

   azd auth login
   

3. Verwenden Sie azd init, um das Projekt zu initialisieren.

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

   Hinweis

   Diese Schnellstartanleitung verwendet das GitHub-Vorlagenrepository azure-samples/cosmos-db-mongodb-nodejs-quickstart. Die Azure Developer CLI klont dieses Projekt automatisch auf Ihrem Computer, wenn es noch nicht vorhanden ist.

4. Konfigurieren Sie während der Initialisierung einen eindeutigen Umgebungsnamen.

   Tipp

   Der Umgebungsname wird auch als Name der Zielressourcengruppe verwendet. Ziehen Sie für diese Schnellstartanleitung die Verwendung von msdocs-cosmos-db in Betracht.

5. Stellen Sie das Azure Cosmos DB-Konto mit azd up bereit. Die Bicep-Vorlagen stellen auch eine Beispielwebanwendung bereit.

   azd up
   

6. Wählen Sie während des Bereitstellungsprozesses Ihr Abonnement und den gewünschten Standort aus. Warten Sie auf den Abschluss des Bereitstellungsvorgangs. Dieser Prozess kann ca. fünf Minuten dauern.

7. Sobald die Bereitstellung Ihrer Azure-Ressourcen abgeschlossen ist, enthält die Ausgabe eine URL zur ausgeführten Webanwendung.

   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. Verwenden Sie die URL in der Konsole, um im Browser zu Ihrer Webanwendung zu navigieren. Sehen Sie sich die Ausgabe der ausgeführten App an.

   

Installieren des Pakets

Fügen Sie das MongoDB-npm-Paket dem JavaScript-Projekt hinzu. Verwenden Sie den Befehl npm install package, der den Namen des npm-Pakets angibt. Das Paket dotenv wird verwendet, um die Umgebungsvariablen während der lokalen Entwicklung aus einer .env-Datei zu lesen.

npm install mongodb dotenv

Objektmodell

Bevor Sie mit dem Erstellen der Anwendung beginnen, sehen Sie sich die Hierarchie von Ressourcen in Azure Cosmos DB an. Bei Azure Cosmos DB gibt es ein spezifisches Objektmodell, das zum Erstellen von und Zugreifen auf Ressourcen verwendet wird. Azure Cosmos DB erstellt Ressourcen in einer Hierarchie, die aus Konten, Datenbanken, Sammlungen und Dokumenten besteht.

Sie verwenden die folgenden MongoDB-Klassen für die Interaktion mit diesen Ressourcen:

• MongoClient: Diese Klasse bietet eine clientseitige logische Darstellung für die „API für MongoDB“-Ebene in Azure Cosmos DB. Das Clientobjekt wird zum Konfigurieren und Ausführen von Anforderungen für den Dienst verwendet.
• Db: Diese Klasse ist ein Verweis auf eine Datenbank, die möglicherweise noch nicht im Dienst vorhanden ist. Die Datenbank wird vom Server aus überprüft, wenn Sie versuchen, darauf zuzugreifen oder einen Vorgang auszuführen.
• Collection: Diese Klasse ist ein Verweis auf eine Sammlung, die im Dienst ebenfalls möglicherweise noch nicht vorhanden ist. Die Sammlung wird vom Server aus überprüft, wenn Sie versuchen, damit zu arbeiten.

Codebeispiele

• Authentifizieren des Clients
• Abrufen der Datenbankinstanz
• Abrufen der Sammlungsinstanz
• Verwenden von verketteten Methoden
• Erstellen eines Index
• Erstellen eines Dokuments
• Abrufen eines Dokuments
• Ausführen von Abfragen

Der in diesem Artikel beschriebene Beispielcode erstellt die Datenbank adventureworks mit der Sammlung products. Die Sammlung products soll Produktdetails wie Name (name), Kategorie (category), Menge (quantity) und einen Verkaufsindikator (sale) enthalten. Jedes Produkt enthält außerdem einen eindeutigen Bezeichner.

Für diese Prozedur verwendet die Datenbank kein Sharding.

Authentifizieren des Clients

1. Erstellen Sie im Projektverzeichnis eine index.js-Datei. Fügen Sie in Ihrem Editor die erforderlichen Anweisungen hinzu, um auf die MongoDB- und DotEnv-npm-Pakete zu verweisen.

   // 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. Definieren Sie mithilfe des Konstruktors eine neue Instanz der Klasse MongoClient, und von process.env., um die zuvor erstellte Umgebungsvariable zu lesen.

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

Weitere Informationen zu den verschiedenen Möglichkeiten zum Erstellen einer MongoClient-Instanz finden Sie im MongoDB NodeJS Driver Quick Start (Schnellstart zum MongoDB NodeJS-Treiber).

Einrichten von asynchronen Vorgängen

Fügen Sie in der Datei index.js den folgenden Code zur Unterstützung der asynchronen Vorgänge hinzu:

async function main(){

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

}

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

Die folgenden Codeausschnitte sollten in der Funktion main hinzugefügt werden, um die „async/await“-Syntax zu verarbeiten.

Herstellen der Verbindung mit der Datenbank

Verwenden Sie die Methode MongoClient.connect zum Herstellen einer Verbindung mit Ihrer Azure Cosmos DB for MongoDB-Ressource. Diese Methode gibt einen Verweis auf die Datenbank zurück.

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

Abrufen der Datenbankinstanz

Verwenden Sie MongoClient.db, um einen Verweis auf eine Datenbank abzurufen.

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

Abrufen der Sammlungsinstanz

Verwenden Sie MongoClient.Db.collection, um einen Verweis auf eine Sammlung abzurufen.

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

Verkettete Instanzen

Sie können Client, Datenbank und Sammlung miteinander verketten. Dies ist praktischer, wenn Sie auf mehrere Datenbanken oder Sammlungen zugreifen müssen.

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

Erstellen eines Index

Verwenden Sie Collection.createIndex zum Erstellen eines Indexes für die Eigenschaften des Dokuments, die Sie zum Sortieren mit der FindCursor.sort-Methode von MongoDB verwenden möchten.

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

Erstellen eines Dokuments

Erstellen Sie ein Dokument mit den product-Eigenschaften für die adventureworks-Datenbank:

• Eine _id-Eigenschaft als eindeutiger Bezeichner des Produkts.
• Eine category-Eigenschaft. Sie kann als logischer Partitionsschlüssel verwendet werden.
• Eine name-Eigenschaft.
• Eine quantity-Bestandseigenschaft.
• Eine sale-Eigenschaft, die angibt, ob das Produkt verkauft wird.

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

Erstellen Sie ein Dokument in der Sammlung, indem Sie Collection.UpdateOne aufrufen. In diesem Beispiel haben wir uns dafür entschieden, ein Upsert auszuführen statt ein neues Dokument zu erstellen, falls Sie diesen Beispielcode mehrmals ausführen.

Abrufen eines Dokuments

In Azure Cosmos DB können Sie einen kostengünstigeren Punktlesevorgang durchführen, indem Sie sowohl den eindeutigen Bezeichner (_id) als auch den Partitionsschlüssel (category) verwenden.

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

Abfragen von Dokumenten

Nachdem Sie ein Dokument eingefügt haben, können Sie eine Abfrage zum Abrufen aller Dokumente ausführen, die einem bestimmten Filter entsprechen. In diesem Beispiel werden alle Dokumente gesucht, die einer bestimmten Kategorie entsprechen: gear-surf-surfboards. Sobald die Abfrage definiert wurde, rufen Sie Collection.find auf, um ein FindCursor-Ergebnis zu erhalten. Konvertieren Sie den Cursor in ein Array, um JavaScript-Arraymethoden verwenden zu können.

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

Problembehandlung:

• Vergewissern Sie sich bei Anzeige einer Fehlermeldung wie The index path corresponding to the specified order-by item is excluded., dass der Index erstellt wurde.

Ausführen des Codes

Diese App erstellt eine „API für MongoDB“-Datenbank und -Sammlung sowie ein Dokument und zeigt dann das betreffende Dokument an. Schließlich verursacht das Beispiel eine Abfrage, die nur dieses einzelne Dokument zurückgeben soll. In jedem Schritt gibt das Beispiel Informationen über die ausgeführten Schritte an die Konsole aus.

Verwenden Sie zur Ausführung der App ein Terminal, um zum Anwendungsverzeichnis zu navigieren und die Anwendung auszuführen.

node index.js

Die Ausgabe der App sollte ähnlich wie dieses Beispiel aussehen:

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

Bereinigen von Ressourcen

Wenn Sie das Azure Cosmos DB for MongoDB-Konto nicht mehr benötigen, können Sie die entsprechende Ressourcengruppe löschen.

az group delete --name $resourceGroupName

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

Nächste Schritte

In diesem Schnellstart haben Sie gelernt, wie Sie mithilfe des MongoDB-Treibers ein Azure Cosmos DB for MongoDB-Konto, eine Datenbank und eine Sammlung erstellen können. Sie können sich jetzt mit Azure Cosmos DB for MongoDB intensiver beschäftigen, um weitere Daten zu importieren, komplexe Abfragen auszuführen und Ihre Azure Cosmos DB MongoDB-Ressourcen zu verwalten.