Schnellstartanleitung: Azure Cosmos DB for NoSQL-Bibliothek für Node.js

Artikel
01/16/2024

GILT FÜR: NoSQL

Hier erfahren Sie mehr über die ersten Schritte mit der Azure Cosmos DB for NoSQL-Clientbibliothek für Node.js, um Daten in Ihren Containern abzufragen und allgemeine Vorgänge für einzelne Elemente auszuführen. Führen Sie die folgenden Schritte aus, um mithilfe von Azure Developer CLI eine minimale Lösung für Ihre Umgebung bereitzustellen.

API-Referenzdokumentation | Quellcode der Bibliothek | Paket (npm) | 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 Azure Developer CLI (azd), um ein Azure Cosmos DB for NoSQL-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.

Öffnen Sie ein Terminal im Stammverzeichnis des Projekts.
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
```
Verwenden Sie azd init, um das Projekt zu initialisieren.
```
azd init
```
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.
Stellen Sie das Azure Cosmos DB-Konto mit azd up bereit. Die Bicep-Vorlagen stellen auch eine Beispielwebanwendung bereit.
```
azd up
```
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.

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.

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 der Clientbibliothek

Die Clientbibliothek ist über den Node-Paket-Manager als @azure/cosmos-Paket verfügbar.

Öffnen Sie ein Terminal, und navigieren Sie zum /src-Ordner.
```
cd ./src
```
Installieren Sie das @azure/cosmos-Paket mithilfe von npm install, falls es noch nicht installiert ist.
```
npm install --save @azure/cosmos
```
Installieren Sie außerdem das @azure/identity-Paket (sofern noch nicht installiert).
```
npm install --save @azure/identity
```
Öffnen Sie die Datei src/package.json, und überprüfen Sie sie, um zu bestätigen, dass die Einträge azure-cosmos und azure-identity vorhanden sind.

Objektmodell

name	Beschreibung
`CosmosClient`	Diese Klasse ist die primäre Clientklasse und wird verwendet, um kontoweite Metadaten oder Datenbanken zu verwalten.
`Database`	Diese Klasse stellt eine Datenbank innerhalb des Kontos dar.
`Container`	Diese Klasse wird in erster Linie verwendet, um Lese-, Update- und Löschvorgänge für den Container oder die im Container gespeicherten Elemente auszuführen.
`PartitionKey`	Diese Klasse stellt einen logischen Partitionsschlüssel dar. Sie ist für viele allgemeine Vorgänge und Abfragen erforderlich.
`SqlQuerySpec`	Diese Schnittstelle stellt eine SQL-Abfrage und alle Abfrageparameter dar.

Der Beispielcode in der Vorlage verwendet eine Datenbank mit dem Namen cosmicworks und einen Container mit dem Namen products. Der products-Container enthält Details wie Name, Kategorie, Menge, eindeutiger Bezeichner und ein Verkaufsflag für jedes Produkt. Der Container verwendet die /category-Eigenschaft als logischen Partitionsschlüssel.

Authentifizieren des Clients

Anwendungsanforderungen an die meisten Azure-Dienste müssen autorisiert werden. Verwenden Sie den DefaultAzureCredential-Typ als bevorzugte Methode, um eine kennwortlose Verbindung zwischen Ihren Anwendungen und Azure Cosmos DB for NoSQL zu implementieren. DefaultAzureCredential unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche Methode zur Laufzeit verwendet werden soll.

Wichtig

Anforderungen an Azure-Dienste können auch direkt mithilfe von Kennwörtern, Verbindungszeichenfolgen oder anderen Anmeldeinformationen autorisiert werden. Dieser Ansatz sollte jedoch mit Vorsicht verwendet werden. Entwickler müssen darauf achten, dass diese Geheimnisse nicht an einem unsicheren Ort offengelegt werden. Alle Benutzer*innen, die Zugriff auf das Kennwort oder auf den geheimen Schlüssel erhalten, können sich damit beim Datenbankdienst authentifizieren. DefaultAzureCredential bietet im Vergleich zum Kontoschlüssel verbesserte Verwaltungs- und Sicherheitsansätze, um die kennwortlose Authentifizierung zu ermöglichen, ohne dass das Risiko besteht, Schlüssel speichern zu müssen.

In diesem Beispiel wird eine neue Instanz des CosmosClient-Typs erstellt, und die Authentifizierung erfolgt mit einer DefaultAzureCredential-Instanz.

const credential = new DefaultAzureCredential();

const client = new CosmosClient({
    endpoint,
    aadCredentials: credential
});

Datenbank abrufen

Verwenden Sie client.database, um die vorhandene Datenbank mit dem Namen cosmicworks abzurufen.

const database = client.database('cosmicworks');

Container abrufen

Rufen Sie den vorhandenen products-Container mithilfe von database.container ab.

const container = database.container('products');

Erstellen eines Elements

Erstellen Sie ein neues Objekt mit allen Membern, die Sie in JSON serialisieren möchten. In diesem Beispiel weist der Typ einen eindeutigen Bezeichner und Felder für Kategorie, Name, Menge, Preis und den Verkauf auf. Erstellen Sie mithilfe von container.items.upsert ein Element im Container. Mit dieser Methode wird ein Upsertvorgang für das Element ausgeführt, wodurch es effektiv ersetzt wird (sofern schon vorhanden).

var item = {
    'id': '70b63682-b93a-4c77-aad2-65501347265f',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

var response = await container.items.upsert(item);

Lesen eines Elements

Führen Sie einen Punktlesevorgang durch, indem Sie sowohl den eindeutigen Bezeichner (id) als auch die Partitionsschlüsselfelder verwenden. Verwenden Sie container.item zum Abrufen eines Zeigers auf ein Element, und rufen Sie mit item.read effizient das jeweilige Element ab.

var id = '70b63682-b93a-4c77-aad2-65501347265f';
var partitionKey = 'gear-surf-surfboards';

var response = await container.item(id, partitionKey).read();
var read_item = response.resource;

Abfrageelemente

Führen Sie mithilfe von container.items.query eine Abfrage für mehrere Elemente in einem Container durch. Suchen Sie alle Elemente in einer angegebenen Kategorie mithilfe dieser parametrisierten Abfrage:

SELECT * FROM products p WHERE p.category = @category

Fetchen Sie mithilfe von query.fetchAll alle Ergebnisse dieser Abfrage. Durchlaufen Sie die Ergebnisse der Abfrage.

const querySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

var response = await container.items.query(querySpec).fetchAll();
for (var item of response.resources) {

}

Nächster Schritt

Tutorial: Erstellen einer Node.js-Web-App