Schnellstart: Azure Cosmos DB for NoSQL-Clientbibliothek für Node.js
GILT FÜR: NoSQL
Erste Schritte mit der Azure Cosmos DB-Clientbibliothek für JavaScript, um Datenbanken, Container und Elemente in Ihrem Konto zu erstellen. Sie können ein kostenloses Azure Cosmos DB-Testkonto einrichten, ohne eine Kreditkarte oder ein Azure-Abonnement zu benötigen. 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 Node.js-Projekt verfügbar.
Voraussetzungen
- Ein Azure-Konto mit einem aktiven Abonnement.
- Kein Azure-Abonnement? Sie können Azure Cosmos DB kostenlos testen, ohne dass eine Kreditkarte erforderlich ist.
- Node.js 10 oder höher
- Azure-Befehlszeilenschnittstelle (CLI) oder Azure PowerShell
Prüfen der Voraussetzungen
- Führen Sie in einem Terminal- oder Befehlsfenster
node --version
aus, um festzustellen, ob die Node.js-Version eine der aktuellen Versionen mit langfristiger Unterstützung ist. - Führen Sie
az --version
(Azure CLI) oderGet-Module -ListAvailable AzureRM
(Azure PowerShell) aus, um zu überprüfen, ob die geeigneten Azure-Befehlszeilentools installiert wurden.
Einrichten
Dieser Abschnitt führt Sie durch das Erstellen eines Azure Cosmos-Kontos und durch das Einrichten eines Projekts, das die Azure Cosmos DB-SQL-API-Clientbibliothek für JavaScript zum Verwalten von Ressourcen verwendet.
Erstellen eines Azure Cosmos DB-Kontos
Tipp
Kein Azure-Abonnement? Sie können Azure Cosmos DB kostenlos testen, ohne dass eine Kreditkarte erforderlich ist. Wenn Sie mithilfe der kostenlosen Testversion ein Konto erstellen, können Sie mit dem Abschnitt Erstellen eines neuen JavaScript-Projekts fortfahren.
In dieser Schnellstartanleitung wird ein einzelnes Azure Cosmos DB-Konto mithilfe der API für NoSQL erstellt.
Tipp
Für diesen Schnellstart empfehlen wir die Verwendung des Ressourcengruppennamens msdocs-cosmos-quickstart-rg
.
Melden Sie sich beim Azure-Portal an.
Wählen Sie im Menü des Azure-Portals oder auf der Startseite die Option Ressource erstellen aus.
Suchen Sie auf der Seite Neu nach Azure Cosmos DB, und wählen Sie die Option aus.
Wählen Sie auf der Seite API-Option auswählen im Abschnitt NoSQL die Option Erstellen aus. Azure Cosmos DB verfügt über sechs APIs: NoSQL, MongoDB, PostgreSQL, Apache Cassandra, Apache Gremlin und Table. Weitere Informationen zur API für NoSQL.
Geben Sie auf der Seite Azure Cosmos DB-Konto erstellen die folgenden Informationen ein:
Einstellung Wert BESCHREIBUNG Subscription Abonnementname Wählen Sie das Azure-Abonnement aus, das Sie für dieses Azure Cosmos-Konto verwenden möchten. Ressourcengruppe Ressourcengruppenname Wählen Sie eine Ressourcengruppe aus, oder wählen Sie Neu erstellen aus, und geben Sie einen eindeutigen Namen für die Ressourcengruppe ein. Kontoname Ein eindeutiger Name Geben Sie einen Namen ein, der Ihr Azure Cosmos-Konto identifiziert. Weil der Name als Teil eines vollqualifizierten Domänennamens (FQDN) mit dem Suffix documents.azure.com verwendet wird, muss er global eindeutig sein. Der Name darf nur Kleinbuchstaben, Zahlen und den Bindestrich (-) enthalten. Außerdem muss der Name zwischen 3 und 44 Zeichen lang sein. Standort Die Region, die Ihren Benutzern am nächsten liegt Wählen Sie einen geografischen Standort aus, an dem Ihr Azure Cosmos DB-Konto gehostet werden soll. Verwenden Sie den Standort, der Ihren Benutzern am nächsten ist, damit sie möglichst schnell auf die Daten zugreifen können. Kapazitätsmodus Bereitgestellter Durchsatz oder serverlos Wählen Sie Bereitgestellter Durchsatz aus, um ein Konto im Modus Bereitgestellter Durchsatz zu erstellen. Wählen Sie Serverlos aus, um ein Konto im Modus Serverlos zu erstellen. Anwenden des Rabatts für den Free-Tarif von Azure Cosmos DB Anwenden oder Nicht anwenden Aktivieren Sie den Free-Tarif von Azure Cosmos DB. Mit dem Azure Cosmos DB-Tarif „Free“ erhalten Sie die ersten 1000 RUs/Sek. sowie 25 GB Speicher kostenlos in einem Konto. Weitere Informationen zum Tarif „Free“ Hinweis
Sie können pro Azure-Abonnement maximal ein Azure Cosmos DB-Konto im Free-Tarif einrichten und müssen sich beim Erstellen des Kontos anmelden. Wird die Option zum Anwenden des tarifspezifischen Rabatts für den Free-Tarif nicht angezeigt, bedeutet dies, dass bereits ein anderes Konto im Abonnement mit dem Free-Tarif aktiviert wurde.
Klicken Sie auf Überprüfen + erstellen.
Überprüfen Sie die von Ihnen angegebenen Einstellungen, und wählen Sie dann Erstellen aus. Die Erstellung des Kontos dauert einige Minuten. Warten Sie, bis auf der Portalseite Ihre Bereitstellung ist abgeschlossen angezeigt wird, bevor sie den Vorgang fortsetzen.
Wählen Sie Zu Ressource wechseln aus, um zur Seite des Azure Cosmos DB-Kontos zu wechseln.
Wählen Sie auf der API für NoSQL-Kontoseite im Navigationsmenü die Option Schlüssel aus.
Zeichnen Sie die Werte aus den Feldern von URI - und PRIMÄRSCLÜSSEL auf. Diese Werte benötigen Sie in einem späteren Schritt.
Konfigurieren von Umgebungsvariablen
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. Verwenden Sie zum Festlegen der Umgebungsvariablen Ihr bevorzugtes Terminal, um die folgenden Befehle auszuführen:
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
Erstellen eines neuen JavaScript-Projekts
Erstellen Sie eine neue Node.js-Anwendung in einem leeren Ordner mit Ihrem bevorzugten Terminal.
npm init -y
Bearbeiten Sie die Datei
package.json
für die Verwendung von ES6-Modulen, indem Sie den Eintrag"type": "module",
hinzufügen. Diese Einstellung ermöglicht es Ihrem Code, die moderne async/await-Syntax zu verwenden.{ "name": "azure-cosmos-db-sql-api-quickstart", "version": "1.0.0", "description": "Azure Cosmos DB for Core (SQL) quickstart with JavaScript", "main": "index", "type": "module", "scripts": { "start": "node index.js", "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [ "cosmos", "quickstart" ], "author": "diberry", "license": "MIT", "dependencies": { "@azure/cosmos": "^3.17.0", "dotenv": "^16.0.2" } }
Installieren des Pakets
Fügen Sie das npm-Paket @azure/cosmos zum Node.js-Projekt hinzu.
npm install @azure/cosmos
Fügen Sie das npm-Paket dotenv hinzu, um Umgebungsvariablen aus einer
.env
-Datei lesen zu können.npm install dotenv
Erstellen der Dateien für die lokale Entwicklungsumgebung
Erstellen Sie eine
.gitignore
-Datei, und fügen Sie den folgenden Wert hinzu, um die Umgebungsdatei und die node_modules zu ignorieren. Diese Konfigurationsdatei stellt sicher, dass nur sichere und relevante Dateien in den Quellcode eingecheckt werden..env node_modules
Erstellen Sie eine
.env
-Datei mit folgenden Variablen:COSMOS_ENDPOINT= COSMOS_KEY=
Erstellen einer Codedatei
Erstellen Sie eine index.js
-Datei, und fügen Sie den folgenden Textbaustein als Code hinzu, um Umgebungsvariablen zu lesen:
// Get environment variables from .env
import * as dotenv from 'dotenv';
dotenv.config();
Hinzufügen einer Abhängigkeit zur Clientbibliothek
Fügen Sie den folgenden Code am Ende der index.js
-Datei hinzu, um die erforderliche Abhängigkeit für den programmgesteuerten Zugriff auf Cosmos DB einzufügen.
// Get Cosmos Client
import { CosmosClient } from "@azure/cosmos";
Hinzufügen der Umgebungsvariablen zur Codedatei
Fügen Sie am Ende der index.js
-Datei den folgenden Code hinzu, um die erforderlichen Umgebungsvariablen einzufügen. Endpunkt und Schlüssel wurden am Ende der Kontoerstellungsschritte ermittelt.
// Provide required connection from environment variables
const key = process.env.COSMOS_KEY;
// Endpoint format: https://YOUR-RESOURCE-NAME.documents.azure.com:443/
const endpoint = process.env.COSMOS_ENDPOINT;
Hinzufügen von Variablen für Namen
Fügen Sie die folgenden Variablen hinzu, um eindeutige Datenbank- und Containernamen sowie den Partitionsschlüssel (pk
) zu verwalten.
// Uniqueness for database and container
const timeStamp = + new Date();
// Set Database name and container name with unique timestamp
const databaseName = `contoso_${timeStamp}`;
const containerName = `products_${timeStamp}`;
const partitionKeyPath = ["/categoryName"]
In diesem Beispiel wurde für den Fall, dass Sie diesen Beispielcode mehrmals ausführen, ein Zeitstempel zur Datenbank und zum Container hinzugefügt.
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. Die Azure Cosmos DB erstellt Ressourcen in einer Hierarchie, die aus Konten, Datenbanken, Containern und Elementen 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 Containerknoten. Der andere Datenbankknoten enthält einen einzelnen untergeordneten Containerknoten. Dieser einzelne Containerknoten hat drei untergeordnete Elementknoten.
Weitere Informationen zur Hierarchie der verschiedenen Entitäten finden Sie im Artikel Arbeiten mit Datenbanken, Containern und Elementen in Azure Cosmos DB.
Sie verwenden die folgenden JavaScript-Klassen für die Interaktion mit folgenden Ressourcen:
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 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.Container
- Diese Klasse ist ein Verweis auf einen Container, der möglicherweise noch nicht im Dienst vorhanden ist. Der Container wird vom Server aus überprüft, wenn Sie versuchen, damit zu arbeiten.SqlQuerySpec
- Diese Schnittstelle stellt eine SQL-Abfrage und alle Abfrageparameter dar.QueryIterator<>
- Diese Klasse stellt einen Iterator dar, der die aktuelle Seite der Ergebnisse nachverfolgen und eine neue Seite mit Ergebnissen erhalten kann.FeedResponse<>
- Diese Klasse stellt eine einzelne Seite von Antworten aus dem Iterator dar.
Codebeispiele
- Authentifizieren des Clients
- Erstellen einer Datenbank
- Container erstellen
- Erstellen eines Elements
- Abrufen eines Elements
- Abfrageelemente
Der in diesem Artikel beschriebene Beispielcode erstellt eine Datenbank mit dem Namen adventureworks
mit einem Container mit dem Namen products
. Die products
-Tabelle soll Produktdetails wie Name, Kategorie, Menge und Verkaufsindikator enthalten. Jedes Produkt enthält außerdem einen eindeutigen Bezeichner.
Für diesen Beispielcode verwendet der Container die Kategorie als logischer Partitionsschlüssel.
Authentifizieren des Clients
Fügen Sie in index.js
den folgenden Code hinzu, um endpoint und key der Ressource für die Authentifizierung bei Cosmos DB zu verwenden. Definieren Sie eine neue Instanz der CosmosClient
-Klasse.
// Authenticate to Azure Cosmos DB
const cosmosClient = new CosmosClient({ endpoint, key });
Erstellen einer Datenbank
Fügen Sie den folgenden Code hinzu, um die Methode CosmosClient.Databases.createDatabaseIfNotExists
zum Erstellen einer neuen Datenbank verwenden, wenn noch keine vorhanden ist. Diese Methode gibt einen Verweis auf die bereits vorhandene oder neu erstellte Datenbank zurück.
// Create database if it doesn't exist
const { database } = await cosmosClient.databases.createIfNotExists({ id: databaseName });
console.log(`${database.id} database ready`);
Erstellen eines Containers
Fügen Sie den folgenden Code hinzu, um mit der Database.Containers.createContainerIfNotExistsAsync
-Methode einen Container zu erstellen. Diese Methode gibt einen Verweis auf den Container zurück.
// Create container if it doesn't exist
const { container } = await database.containers.createIfNotExists({
id: containerName,
partitionKey: {
paths: partitionKeyPath
}
});
console.log(`${container.id} container ready`);
Erstellen eines Elements
Fügen Sie den folgenden Code hinzu, um das Dataset bereitzustellen. Jedes Produkt verfügt über eine eindeutige ID, einen Namen, einen Kategorienamen (als Partitionsschlüssel verwendet) und andere Felder.
// Data items
const items = [
{
"id": "08225A9E-F2B3-4FA3-AB08-8C70ADD6C3C2",
"categoryId": "75BF1ACB-168D-469C-9AA3-1FD26BB4EA4C",
"categoryName": "Bikes, Touring Bikes",
"sku": "BK-T79U-50",
"name": "Touring-1000 Blue, 50",
"description": "The product called \"Touring-1000 Blue, 50\"",
"price": 2384.0700000000002,
"tags": [
{
"_id": "27B7F8D5-1009-45B8-88F5-41008A0F0393",
"name": "Tag-61"
}
]
},
{
"id": "2C981511-AC73-4A65-9DA3-A0577E386394",
"categoryId": "75BF1ACB-168D-469C-9AA3-1FD26BB4EA4C",
"categoryName": "Bikes, Touring Bikes",
"sku": "BK-T79U-46",
"name": "Touring-1000 Blue, 46",
"description": "The product called \"Touring-1000 Blue, 46\"",
"price": 2384.0700000000002,
"tags": [
{
"_id": "4E102F3F-7D57-4CD7-88F4-AC5076A42C59",
"name": "Tag-91"
}
]
},
{
"id": "0F124781-C991-48A9-ACF2-249771D44029",
"categoryId": "56400CF3-446D-4C3F-B9B2-68286DA3BB99",
"categoryName": "Bikes, Mountain Bikes",
"sku": "BK-M68B-42",
"name": "Mountain-200 Black, 42",
"description": "The product called \"Mountain-200 Black, 42\"",
"price": 2294.9899999999998,
"tags": [
{
"_id": "4F67013C-3B5E-4A3D-B4B0-8C597A491EB6",
"name": "Tag-82"
}
]
}
];
Erstellen Sie einige Elemente im Container, indem Sie Container.Items.create
in einer Schleife aufrufen.
// Create all items
for (const item of items) {
const { resource } = await container.items.create(item);
console.log(`'${resource.name}' inserted`);
}
Abrufen eines Elements
In Azure Cosmos DB können Sie einen Punktlesevorgang ausführen, indem Sie sowohl die eindeutigen Bezeichner (id
) als auch die Partitionsschlüsselfelder verwenden. Rufen Sie im SDK Container.item().read
auf, und übergeben Sie beide Wert, um ein Element zurückzugeben.
Der Partitionsschlüssel ist containerspezifisch. In diesem Contoso Products-Container wird der Kategoriename categoryName
als Partitionsschlüssel verwendet.
// Read item by id and partitionKey - least expensive `find`
const { resource } = await container.item(items[0].id, items[0].categoryName).read();
console.log(`${resource.name} read`);
Abfrageelemente
Fügen Sie den folgenden Code hinzu, um alle Elemente abzufragen, die einem bestimmten Filter entsprechen. Erstellen Sie einen parametrisierten Abfrageausdruck, und rufen Sie dann die Container.Items.query
-Methode auf. Diese Methode gibt einen QueryIterator
für die Verwaltung der Ergebnisseiten zurück. Verwenden Sie dann eine Kombination aus while
- und for
-Schleifen, um fetchNext
für die Ergebnisseiten als FeedResponse
durchzuführen und dann die einzelnen Datenobjekte zu durchlaufen.
Die Abfrage wird programmgesteuert als SELECT * FROM todo t WHERE t.partitionKey = 'Bikes, Touring Bikes'
erstellt.
// Query by SQL - more expensive `find`
// find all items with same categoryName (partitionKey)
const querySpec = {
query: "select * from products p where p.categoryName=@categoryName",
parameters: [
{
name: "@categoryName",
value: items[2].categoryName
}
]
};
// Get items
const { resources } = await container.items.query(querySpec).fetchAll();
for (const item of resources) {
console.log(`${item.id}: ${item.name}, ${item.sku}`);
}
Um die von FeedResponse zurückgegebenen Daten als item verwenden zu können, müssen Sie mit der Container.Items.read
-Methode ein Item
erstellen.
Löschen eines Elements
Fügen Sie den folgenden Code hinzu, um ein Element zu löschen. Sie müssen die ID und den Partitionsschlüssel verwenden, um das Element abzurufen, und es dann löschen. In diesem Beispiel wird die Container.Item.delete
-Methode zum Löschen des Elements verwendet.
// Delete item
const { statusCode } = await container.item(items[2].id, items[2].categoryName).delete();
console.log(`${items[2].id} ${statusCode==204 ? `Item deleted` : `Item not deleted`}`);
Ausführen des Codes
Diese App erstellt eine Azure Cosmos DB SQL API-Datenbank und Container. Das Beispiel erstellt dann Elemente und liest dann ein Element wieder ein. Schließlich erstellt das Beispiel eine Abfrage, die nur Elemente zurückgeben soll, die einer bestimmten Kategorie entsprechen. In jedem Schritt gibt das Beispiel über die ausgeführten Schritte Metadaten in 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:
contoso_1663276732626 database ready
products_1663276732626 container ready
'Touring-1000 Blue, 50' inserted
'Touring-1000 Blue, 46' inserted
'Mountain-200 Black, 42' inserted
Touring-1000 Blue, 50 read
08225A9E-F2B3-4FA3-AB08-8C70ADD6C3C2: Touring-1000 Blue, 50, BK-T79U-50
2C981511-AC73-4A65-9DA3-A0577E386394: Touring-1000 Blue, 46, BK-T79U-46
0F124781-C991-48A9-ACF2-249771D44029 Item deleted
Bereinigen von Ressourcen
Wenn Sie das API für NoSQL-Konto nicht mehr benötigen, können Sie die entsprechende Ressourcengruppe löschen.
Navigieren Sie zu der Ressourcengruppe, die Sie im Azure-Portal zuvor erstellt haben.
Tipp
In diesem Schnellstart haben wir den Namen
msdocs-cosmos-quickstart-rg
empfohlen.Wählen Sie die Option Ressourcengruppe löschen.
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 ein Azure Cosmos DB SQL API-Konto eine Datenbank und einen Container mithilfe von JavaScript SDK erstellen. Sie können nun tiefer in das SDK eintauchen, um weitere Daten zu importieren, komplexe Abfragen auszuführen und Ihre Azure Cosmos DB SQL API-Ressourcen zu verwalten.