Schnellstart: Azure Cosmos DB for NoSQL-Clientbibliothek für Node.js

  • Artikel
  • 14 Minuten Lesedauer

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

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

  1. Melden Sie sich beim Azure-Portal an.

  2. Wählen Sie im Menü des Azure-Portals oder auf der Startseite die Option Ressource erstellen aus.

  3. Suchen Sie auf der Seite Neu nach Azure Cosmos DB, und wählen Sie die Option aus.

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

    Screenshot: ausgewählte API-Optionen-Seite für Azure Cosmos DB.

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

    Screenshot: Neue Kontoseite für API für NoSQL

  6. Klicken Sie auf Überprüfen + erstellen.

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

  8. Wählen Sie Zu Ressource wechseln aus, um zur Seite des Azure Cosmos DB-Kontos zu wechseln.

    Screenshot: Bereitstellungsseite für API für NoSQL-Ressource

  9. Wählen Sie auf der API für NoSQL-Kontoseite im Navigationsmenü die Option Schlüssel aus.

    Screenshot: API für NoSQL-Kontoseite mit hervorgehobener Option „Schlüssel“ im Navigationsmenü

  10. Zeichnen Sie die Werte aus den Feldern von URI - und PRIMÄRSCLÜSSEL auf. Diese Werte benötigen Sie in einem späteren Schritt.

    Screenshot: Seite „Schlüssel“ mit diversen Anmeldeinformationen für ein API für NoSQL-Konto

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

  1. Erstellen Sie eine neue Node.js-Anwendung in einem leeren Ordner mit Ihrem bevorzugten Terminal.

    npm init -y

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

  1. Fügen Sie das npm-Paket @azure/cosmos zum Node.js-Projekt hinzu.

    npm install @azure/cosmos

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

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

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

Diagram der Azure Cosmos DB-Hierarchie, einschließlich Konten, Datenbanken, Containern und Elementen.

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

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.

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

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

    Screenshot: Die Option „Ressourcengruppe löschen“ in der Navigationsleiste für eine Ressourcengruppe.

  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.

    Screenshot: Die Bestätigungsseite für das Löschen einer Ressourcengruppe.

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.

Tutorial: Erstellen einer Node.js-Konsolen-App