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

GILT FÜR: MongoDB

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

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.

Hinweis

Die Beispielcodeausschnitte sind auf GitHub als JavaScript-Projekt verfügbar.

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

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
• GitHub-Konto

• Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
• Azure Developer CLI
• Docker Desktop

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.

Wichtig

GitHub-Konten enthalten eine Berechtigung für Speicher und Kernstunden, für die jeweils keine Kosten anfallen. Weitere Informationen finden Sie unter Monatlich enthaltene Speicherkapazität und Kernstunden für GitHub-Konten.

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
   

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.

Hierarchisches Diagramm mit einem Azure Cosmos DB-Konto oben. Das Konto verfügt über zwei untergeordnete Datenbank-Shards. Eine der Datenbank-Shards enthält zwei untergeordnete Sammlungsshards. Der andere Datenbank-Shard enthält eine einzelne untergeordnete Sammlungs-Shard. Diese einzelne Sammlungs-Shard weist drei untergeordnete Dokument-Shards auf.

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

• 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 im Dienst möglicherweise vorhanden oder noch nicht 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
• Verkettete Instanzen
• Erstellen eines Index
• Erstellen eines Dokuments
• Abrufen eines Dokuments
• Abfragen von Dokumenten

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 gibt das Beispiel eine Abfrage aus, die nur dieses einzelne Dokument zurückgeben sollte. Mit 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.

Azure-Befehlszeilenschnittstelle

Verwenden Sie den Befehl az group delete zum Löschen der Ressourcengruppe.

az group delete --name $resourceGroupName

PowerShell

Verwenden Sie das Cmdlet Remove-AzResourceGroup zum Löschen der Ressourcengruppe.

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

Portal

1. Navigieren Sie zu der Ressourcengruppe, die Sie im Azure-Portal zuvor erstellt haben.

   Tipp

   In diesem Schnellstart haben wir den Namen msdocs-cosmos-javascript-quickstart-rg empfohlen.

2. Wählen Sie die Option Ressourcengruppe löschen.

   

3. Geben Sie im Dialogfeld Möchten Sie den Löschvorgang durchführen? den Namen der Ressourcengruppe ein, und wählen Sie Löschen aus.

   

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.

Offlinemigration von MongoDB zu Azure Cosmos DB for MongoDB