Erste Schritte mit Azure Cosmos DB for MongoDB unter Verwendung von JavaScript

GILT FÜR: MongoDB

In diesem Artikel wird gezeigt, wie Sie mit dem nativen npm-Paket von MongoDB eine Verbindung mit Azure Cosmos DB for MongoDB herstellen. Sobald die Verbindung hergestellt ist, können Sie Vorgänge für Datenbanken, Sammlungen und Dokumente ausführen.

Hinweis

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

„API für MongoDB“-Referenzdokumentation | MongoDB-Paket (npm)

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
• Node.js LTS
• Azure-Befehlszeilenschnittstelle (CLI) oder Azure PowerShell
• Azure Cosmos DB for MongoDB-Ressource

Erstellen einer neuen JavaScript-App

1. Erstellen Sie mithilfe Ihres bevorzugten Terminals eine neue JavaScript-Anwendung in einem leeren Ordner. Verwenden Sie den npm init-Befehl, um die Eingabeaufforderungen zum Erstellen der package.json-Datei anzuzeigen. Übernehmen Sie die Standardwerte für die Eingabeaufforderungen.

   npm init
   

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

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

   node index.js
   

Herstellen einer Verbindung mit Azure Cosmos DB for MongoDB mithilfe des nativen MongoDB-Treibers

Um eine Verbindung mit dem nativen MongoDB-Treiber mit Azure Cosmos DB herzustellen, erstellen Sie eine Instanz der MongoClient-Klasse. Diese Klasse ist der Ausgangspunkt, um alle Vorgänge für Datenbanken auszuführen.

Der gebräuchlichste Konstruktor für MongoClient hat zwei Parameter:

Parameter	Beispielwert	BESCHREIBUNG
url	Umgebungsvariable COSMOS_CONNECTION_STRING	Für alle Anforderungen zu verwendende „API für MongoDB“-Verbindungszeichenfolge
options	{ssl: true, tls: true, }	MongoDB-Optionen für die Verbindung.

Weitere Informationen zu Verbindungsproblemen finden Sie im Handbuch zur Problembehandlung.

Ressourcennamen abrufen

Azure-Befehlszeilenschnittstelle

1. Erstellen Sie eine Shell-Variable für resourceGroupName.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos"
   

2. Verwenden Sie den Befehlaz cosmosdb list, um den Namen des ersten Azure Cosmos DB-Kontos in Ihrer Ressourcengruppe abzurufen und in der Shell-Variable accountName zu speichern.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

PowerShell

1. Erstellen Sie eine Shell-Variable für RESOURCE_GROUP_NAME.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos"
   

2. Verwenden Sie das Cmdlet Get-AzCosmosDBAccountKey, um den Namen des ersten Azure Cosmos DB-Kontos in Ihrer Ressourcengruppe abzurufen und in der Shellvariable accountName zu speichern.

   # Get the name of the first Azure Cosmos DB account in your resource group
   $ACCOUNT_NAME = (Get-AzCosmosDBAccount -ResourceGroupName $RESOURCE_GROUP_NAME)[0].Name
   

Portal

Überspringen Sie diesen Schritt, und verwenden Sie die Informationen für das Portal im nächsten Schritt.

Abrufen der Verbindungszeichenfolge

Azure-Befehlszeilenschnittstelle

1. Suchen Sie mit dem Befehl az cosmosdb keys list die Verbindungszeichenfolge der API für MongoDB in der Liste der Verbindungszeichenfolgen für das Konto.

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

2. Zeichnen Sie die PRIMARY KEY-Werte (Primärschlüsselwerte) auf. Sie werden diese Anmeldeinformationen zu einem späteren Zeitpunkt verwenden.

PowerShell

1. Suchen Sie mit dem Cmdlet Get-AzCosmosDBAccountKey die CONNECTION STRING (Verbindungszeichenfolge) in der Liste der Schlüssel und Verbindungszeichenfolgen für das Konto.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary MongoDB Connection String"    
   

2. Zeichnen Sie den Wert für CONNECTION STRING auf. Sie werden diese Anmeldeinformationen zu einem späteren Zeitpunkt verwenden.

Portal

Tipp

Für diese Anleitung empfehlen wir die Verwendung des Ressourcengruppennamens msdocs-cosmos.

1. Melden Sie sich beim Azure-Portal an.

2. Navigieren Sie zur Seite des vorhandenen Azure Cosmos DB for MongoDB-Kontos.

3. Wählen Sie auf der Seite für das Azure Cosmos DB for MongoDB-Konto im Navigationsmenü die Option Verbindungszeichenfolge aus.

4. Zeichnen Sie den Wert für das Feld PRIMARY CONNECTION STRING (Primäre Verbindungszeichenfolge) auf. Sie verwenden diesen Wert in einem späteren Schritt.

   

Konfigurieren von Umgebungsvariablen

Wenn Sie die Werte von CONNECTION STRING (Verbindungszeichenfolge) in Ihrem Code verwenden möchten, legen Sie diesen Wert in der lokalen Umgebung fest, in der die Anwendung ausgeführt wird. Verwenden Sie zum Festlegen der Umgebungsvariablen Ihr bevorzugtes Terminal, um die folgenden Befehle auszuführen:

Windows

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

Linux/macOS

export COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

.env

Eine .env-Datei ist eine Standardmöglichkeit zum Speichern von Umgebungsvariablen in einem Projekt. Erstellen Sie eine .env-Datei im Stammverzeichnis Ihres Projekts. Fügen Sie der Datei .env die folgenden Zeilen hinzu:

COSMOS_CONNECTION_STRING="<cosmos-connection-string>"

MongoClient mit Verbindungszeichenfolge erstellen

1. Fügen Sie Abhängigkeiten hinzu, um auf die npm-Pakete für MongoDB und DotEnv zu verweisen.

   // Read .env file and set environment variables
   require('dotenv').config();
   
   // Use official mongodb driver to connect to the server
   const { MongoClient } = require('mongodb');
   

2. Definieren Sie eine neue Instanz der MongoClient-Klasse mit dem Konstruktor und process.env. für die Verwendung der Verbindungszeichenfolge.

   // New instance of MongoClient with connection string
   // for Cosmos DB
   const url = process.env.COSMOS_CONNECTION_STRING;
   const client = new MongoClient(url);
   
   // connect to the server
   await client.connect();
   
   // client options
   const options = client.options
   console.log(`Options:\n${Object.keys(options).map(key => `\t${key}: ${options[key]}\n`)}`);
   

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

MongoClient-Verbindung schließen

Denken Sie daran, die Verbindung zu schließen, wenn die Anwendung die Verbindung nicht mehr benötigt. Der Aufruf von .close() sollte erfolgen, nachdem alle Datenbankaufrufe ausgeführt wurden.

client.close()

Verwenden von MongoDB-Clientklassen mit Azure Cosmos DB für die API für MongoDB

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 Datenbankknoten. Einer der Datenbankknoten enthält zwei untergeordnete Sammlungsknoten. Der andere Datenbankknoten enthält einen einzelnen untergeordneten Sammlungsknoten. Dieser einzelne Sammlungsknoten verfügt über drei untergeordnete Dokumentknoten.

Jeder Ressourcentyp wird durch eine oder mehrere zugeordnete JavaScript-Klassen dargestellt. Nachstehend finden Sie eine Liste der gängigsten Klassen:

Klasse	BESCHREIBUNG
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.

In den folgenden Leitfäden wird gezeigt, wie Sie diese verschiedenen Klassen verwenden, um Ihre Anwendung zu erstellen.

Anleitung:

• Verwalten von Datenbanken
• Verwalten von Sammlungen
• Verwalten von Dokumenten
• Verwenden von Abfragen zum Suchen von Dokumenten

Weitere Informationen

• Paket (NuGet)
• API-Referenz

Nächste Schritte

Nachdem Sie nun eine Verbindung mit einem API für MongoDB-Konto hergestellt haben, befolgen Sie die nächste Anleitung zum Erstellen und Verwalten von Datenbanken.

Erstellen einer Datenbank in Azure Cosmos DB for MongoDB mithilfe von JavaScript