Erste Schritte mit Azure Cosmos DB for NoSQL unter Verwendung von JavaScript
GILT FÜR: NoSQL
In diesem Artikel erfahren Sie, wie Sie mithilfe des Python SDK eine Verbindung mit Azure Cosmos DB for NoSQL herstellen. Sobald die Verbindung hergestellt ist, können Sie Vorgänge für Datenbanken, Container und Elemente ausführen.
Paket (npm) | Beispiele | API-Dokumentation | Bibliothekquellcode | Feedback einreichen
Voraussetzungen
- Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
- Azure Cosmos DB for NoSQL-Konto. Erstellen eines „API für NoSQL“-Kontos.
- Node.js LTS
- Azure-Befehlszeilenschnittstelle (CLI) oder Azure PowerShell
Einrichten Ihres lokalen Projekts
Erstellen Sie ein neues Verzeichnis für Ihr JavaScript-Projekt in einer Bash-Shell.
mkdir cosmos-db-nosql-javascript-samples && cd ./cosmos-db-nosql-javascript-samples
Erstellen Sie eine neue .NET-Anwendung mithilfe des Befehls
npm init
mit der Konsole-Vorlage.npm init -y
Installieren Sie die erforderliche Abhängigkeit für das Azure Cosmos DB for NoSQL JavaScript SDK.
npm install @azure/cosmos
Herstellen einer Verbindung mit Azure Cosmos DB for NoSQL
Um eine Verbindung mit der API für NoSQL von Azure Cosmos DB herzustellen, erstellen Sie eine Instanz der CosmosClient
-Klasse. Diese Klasse ist der Ausgangspunkt, um alle Vorgänge für Datenbanken auszuführen. Es gibt drei Hauptmethoden zum Herstellen einer Verbindung mit einem API für NoSQL-Konto mit der CosmosClient-Klasse:
- Verbinden mit einem API für NoSQL-Endpunkt und Lese-/Schreibschlüssel
- Verbinden mit einer API für NoSQL-Verbindungszeichenfolge
- Verbinden mit Microsoft Entra ID
Verbinden Sie sich mit einem Endpunkt und Schlüssel
Der gebräuchlichste Konstruktor für CosmosClient hat zwei Parameter:
Parameter | Beispielwert | BESCHREIBUNG |
---|---|---|
accountEndpoint |
Umgebungsvariable COSMOS_ENDPOINT |
API für NoSQL-Endpunkt, der für alle Anforderungen verwendet werden soll |
authKeyOrResourceToken |
Umgebungsvariable COSMOS_KEY |
Kontoschlüssel oder Ressourcentoken zur Verwendung bei der Authentifizierung |
Rufen Sie Ihren Kontoendpunkt und -schlüssel ab
Erstellen Sie eine Shell-Variable für resourceGroupName.
# Variable for resource group name resourceGroupName="msdocs-cosmos-javascript-howto-rg"
Verwenden Sie den Befehl
az 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 )
Rufen Sie den API für NoSQL-Endpunkt-URI für das Konto mithilfe des
az cosmosdb show
-Befehls ab.az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "documentEndpoint"
Suchen Sie den PRIMÄRSCHLÜSSEL aus der Liste der Schlüssel für das Konto mit dem
az-cosmosdb-keys-list
-Befehl.az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"
Aufzeichnen der Werte von URI und PRIMÄRSCHLÜSSEL. Sie werden diese Anmeldeinformationen zu einem späteren Zeitpunkt verwenden.
Um die Werte von URI und PRIMÄRSCHLÜSSEL in Ihrem Code zu verwenden, speichern Sie sie in neuen Umgebungsvariablen auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird.
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
Erstellen Sie CosmosClient mit Kontoendpunkt und Schlüssel
Erstellen Sie eine neue Instanz der CosmosClient-Klasse mit den Variablen und COSMOS_ENDPOINT
COSMOS_KEY
Umgebungsvariablen als Parameter.
const client = new CosmosClient({ endpoint, key });
Verbinden mit einer Verbindungszeichenfolge
Ein weiterer Konstruktor für CosmosClient enthält nur einen einzelnen Parameter:
Parameter | Beispielwert | BESCHREIBUNG |
---|---|---|
accountEndpoint |
Umgebungsvariable COSMOS_ENDPOINT |
API für NoSQL-Endpunkt, der für alle Anforderungen verwendet werden soll |
connectionString |
Umgebungsvariable COSMOS_CONNECTION_STRING |
Verbindungszeichenfolge für das API für NoSQL-Konto |
Rufen Sie Ihre Kontoverbindungszeichenfolge ab
Verwenden Sie den Befehl
az 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 )
Suchen Sie mit dem Befehl
az-cosmosdb-keys-list
die PRIMÄRE VERBINDUNGSZEICHENFOLGE in der Liste der Verbindungszeichenfolgen für das Konto.az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "connection-strings" \ --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
Um den PRIMÄREN VERBINDUNGSZEICHENFOLGEN-Wert in Ihrem Code zu verwenden, halten Sie auf einer neuen Umgebungsvariable auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird, fort.
$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"
CosmosClient mit Verbindungszeichenfolge erstellen
Erstellen Sie eine neue Instanz der CosmosClient-Klasse mit der COSMOS_CONNECTION_STRING
Umgebungsvariablen als einzigem Parameter.
// New instance of CosmosClient class using a connection string
const cosmosClient = new CosmosClient(process.env.COSMOS_CONNECTION_STRING);
Verbinden mithilfe von Microsoft Identity Platform
Verwenden Sie einen Sicherheitsprinzipal, um mithilfe von Microsoft Identity Platform und Microsoft Entra ID eine Verbindung mit Ihrem API für NoSQL-Konto herzustellen. Der genaue Prinzipaltyp hängt davon ab, wo Sie Ihren Anwendungscode hosten. Die folgende Tabelle dient als Kurzanleitung.
Ausführungsort der Anwendung | Sicherheitsprinzipal |
---|---|
Lokaler Computer (Entwickeln und Testen) | Benutzeridentität oder Dienstprinzipal |
Azure | Verwaltete Identität |
Server oder Clients außerhalb von Azure | Dienstprinzipal |
Importieren Sie @azure/identity
Das azure/identity npm-Paket enthält grundlegende Authentifizierungsfunktionen, die von allen Azure SDK-Bibliotheken gemeinsam genutzt werden.
Importieren Sie das @azure/identity npm-Paket mithilfe des
npm install
-Befehls.npm install @azure/identity
Fügen Sie in Ihrem Code-Editor die Abhängigkeiten hinzu.
const { DefaultAzureCredential } = require("@azure/identity");
Erstellen von CosmosClient mit Standard-Implementierung von Anmeldeinformationen
Wenn Sie auf einem lokalen Computer testen oder Ihre Anwendung auf Azure-Diensten mit direkter Unterstützung für verwaltete Identitäten ausgeführt wird, rufen Sie ein OAuth-Token ab, indem Sie eine DefaultAzureCredential
-Instanz erstellen. Erstellen Sie dann eine neue Instanz der CosmosClient-Klasse mit der COSMOS_ENDPOINT
-Umgebungsvariable und dem TokenCredential-Objekt als Parameter.
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
const credential = new DefaultAzureCredential();
const cosmosClient = new CosmosClient({
endpoint,
aadCredentials: credential
});
Erstellen von CosmosClient mit Standard-Implementierung von Anmeldeinformationen
Wenn Sie die Anwendung außerhalb von Azure bereitstellen möchten, können Sie ein OAuth-Token abrufen, indem Sie andere Klassen in der Azure.Identity-Clientbibliothek für JavaScript verwenden. Auch diese anderen Klassen leiten sich von der TokenCredential
-Klasse ab.
Für dieses Beispiel erstellen wir eine ClientSecretCredential
-Instanz, indem wir Client- und Mandanten-IDs zusammen mit einem geheimen Clientschlüssel verwenden.
Sie können die Client-ID, die Mandanten-ID und den geheimen Clientschlüssel abrufen, wenn Sie eine Anwendung in Microsoft Entra ID registrieren. Weitere Informationen zum Registrieren von Microsoft Entra-Anwendungen finden Sie unter Registrieren einer Anwendung bei Microsoft Identity Platform.
Erstellen Sie eine neue Instanz der CosmosClient-Klasse mit der COSMOS_ENDPOINT
-Umgebungsvariable und dem TokenCredential-Objekt als Parameter.
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
const credential = new ClientSecretCredential(
tenantId: process.env.AAD_TENANT_ID,
clientId: process.env.AAD_CLIENT_ID,
clientSecret: process.env.AAD_CLIENT_SECRET
);
const cosmosClient = new CosmosClient({
endpoint,
aadCredentials: credential
});
Erstellen Ihrer Anwendung
Beim Erstellen Ihrer Anwendung interagiert Ihr Code hauptsächlich mit vier Arten von Ressourcen:
Das API für NoSQL-Konto, das der eindeutige Namespace der obersten Ebene für Ihre Azure Cosmos DB-Daten ist.
Datenbanken, die Container in Ihrem Konto organisieren.
Container, die eine Reihe einzelner Elemente in Ihrer Datenbank enthalten.
Elemente, die ein JSON-Dokument in Ihrem Container darstellen.
Im folgenden Diagramm ist die Beziehung zwischen diesen Ressourcen dargestellt.
Hierarchisches Diagramm mit einem Azure Cosmos DB-Konto oben. Das Konto verfügt über zwei untergeordnete Datenbankknoten. Einer der Datenbankknoten enthält zwei untergeordnete Containerknoten. Der andere Datenbankknoten enthält einen einzelnen untergeordneten Containerknoten. Dieser einzelne Containerknoten hat drei untergeordnete Elementknoten.
Jeder Ressourcentyp wird durch eine oder mehrere zugeordnete Klassen dargestellt. Nachstehend finden Sie eine Liste der gängigsten Klassen:
Klasse | BESCHREIBUNG |
---|---|
CosmosClient |
Diese Klasse bietet eine clientseitige logische Darstellung für den Azure Cosmos DB-Dienst. Das Clientobjekt wird zum Konfigurieren und Ausführen von Anforderungen für den Dienst verwendet. |
Database |
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. |
Container |
Diese Klasse ist ein Verweis auf einen Container, der möglicherweise noch nicht im Dienst vorhanden ist. Der Container wird serverseitig validiert, wenn Sie versuchen, damit zu arbeiten. |
In den folgenden Leitfäden wird gezeigt, wie Sie diese verschiedenen Klassen verwenden, um Ihre Anwendung zu erstellen.
Handbuch | BESCHREIBUNG |
---|---|
Erstellen einer Datenbank | Erstellen von Datenbanken |
Container erstellen | Erstellen von Containern. |
Erstellen und Lesen eines Elements | Punktlesevorgang eines bestimmten Elements |
Abfrageelemente | Mehrere Elemente abfragen |
Weitere Informationen
Nächste Schritte
Nachdem Sie sich mit einem API für NoSQL-Konto verbunden haben, befolgen Sie zum Erstellen und Verwalten von Datenbanken die nächste Anleitung.
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für