Freigeben über

Verbinden einer Node.js Mongoose-Anwendung mit Azure Cosmos DB

GILT FÜR: MongoDB

In diesem Tutorial wird veranschaulicht, wie das Mongoose-Framework verwendet werden kann, wenn Daten in Azure Cosmos DB gespeichert werden. Für diese exemplarische Vorgehensweise wird die API für MongoDB von Azure Cosmos DB verwendet. Für diejenigen, die Mongoose noch nicht kennen: Mongoose ist ein Objektmodellierungsframework für MongoDB in Node.js und stellt eine schnörkellose schemabasierte Lösung bereit, mit der Sie Ihre Anwendungsdaten modellieren können.

Azure Cosmos DB ist ein global verteilter Datenbankdienst von Microsoft mit mehreren Modellen. Sie können schnell Dokument-, Schlüssel/Wert- und Graph-Datenbanken erstellen und abfragen und dabei stets die Vorteile der globalen Verteilung und der horizontalen Skalierung nutzen, die Azure Cosmos DB zugrunde liegen.

Voraussetzungen

Sollten Sie über kein Azure-Abonnement verfügen, können Sie zunächst ein kostenloses Azure-Konto erstellen.

Sie können Azure Cosmos DB kostenlos testen – ohne Azure-Abonnement und unverbindlich. Alternativ können Sie ein Azure Cosmos DB-Konto im Free-Tarif erstellen, bei dem die ersten 1000 RUs/Sek. sowie 25 GB Speicher kostenlos sind. Sie können auch den Azure Cosmos DB-Emulator mit dem URI https://localhost:8081 verwenden. Informationen zur Verwendung des Schlüssels mit dem Emulator finden Sie unter Verwenden des Azure Cosmos-Emulators für lokale Entwicklungs- und Testvorgänge.

Node.js Version v0.10.29 oder höher.

Erstellen eines Azure Cosmos DB-Kontos

Wir erstellen nun ein Azure Cosmos DB-Konto. Wenn Sie bereits über ein Konto verfügen, das Sie verwenden möchten, können Sie diesen Schritt überspringen und mit dem Einrichten Ihrer Node.js-Anwendung fortfahren. Wenn Sie den Azure Cosmos DB-Emulator verwenden, führen Sie die unter Azure Cosmos DB-Emulator aufgeführten Schritte zum Einrichten des Emulators aus, und fahren Sie dann mit dem Einrichten Ihrer Node.js-Anwendung fort.

  1. Melden Sie sich in einem neuen Browserfenster beim Azure-Portal an.

  2. Wählen Sie im Menü auf der linken Seite Ressource erstellen aus.

    Screenshot: Erstellen einer Ressource im Azure-Portal

  3. Wählen Sie auf der Seite Neu die Optionen Datenbanken>Azure Cosmos DB aus.

    Screenshot: Bereich „Datenbanken“ im Azure-Portal

  4. Wählen Sie auf der Seite API-Option auswählenAzure Cosmos DB for MongoDB>Erstellen aus.

    Die API bestimmt den Typ des zu erstellenden Kontos. Wählen Sie Azure Cosmos DB for MongoDB aus, denn in diesem Schnellstart erstellen Sie eine Sammlung, für die MongoDB verwendet wird. Weitere Informationen finden Sie unter Übersicht über Azure Cosmos DB for MongoDB.

    Screenshot: Bereich „API-Option auswählen“

  5. Geben Sie auf der Seite Azure Cosmos DB-Konto erstellen die Einstellungen für das neue Azure Cosmos DB-Konto ein:

    Einstellung Wert BESCHREIBUNG
    Subscription Abonnementname Wählen Sie das Azure-Abonnement aus, das Sie für dieses Azure Cosmos DB-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 Geben Sie einen eindeutigen Namen ein. Geben Sie einen eindeutigen Namen ein, der Ihr Azure Cosmos DB-Konto identifiziert. Der Konto-URI lautet mongo.cosmos.azure.com und wird an Ihren eindeutigen Kontonamen angehängt.

    Der Kontoname darf nur Kleinbuchstaben, Ziffern und Bindestriche (-) enthalten und muss 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.

    Hinweis: Von serverlosen Konten werden nur die Versionen 4.2, 4.0 und 3.6 der API für MongoDB unterstützt. Wenn Sie 3.2 als Version auswählen, wird das Konto im Modus für bereitgestellten Durchsatz erzwungen.
    Anwenden des Rabatts für den Free-Tarif von Azure Cosmos DB Anwenden oder Nicht anwenden 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“
    Version Auswählen der erforderlichen Serverversion Azure Cosmos DB for MongoDB ist mit den Serverversionen 4.2, 4.0, 3.6 und 3.2 kompatibel. Sie können ein Konto upgraden oder herabstufen, nachdem es erstellt wurde.

    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: Seite „Neues Konto“ für Azure Cosmos DB

  6. Konfigurieren Sie auf der Registerkarte Globale Verteilung die folgenden Details. Für diese Schnellstartanleitung können Sie die Standardwerte übernehmen:

    Einstellung Wert Beschreibung
    Georedundanz Deaktivieren Aktivieren oder deaktivieren Sie die globale Verteilung für Ihr Konto, indem Sie Ihre Region mit einer Region koppeln. Sie können später weitere Regionen zu Ihrem Konto hinzufügen.
    Schreibvorgänge in mehreren Regionen Deaktivieren Mit der Funktion zum Schreiben in mehreren Regionen können Sie den bereitgestellten Durchsatz für Ihre Datenbanken und Container in der ganzen Welt nutzen.

    Hinweis

    Die folgenden Optionen sind nicht verfügbar, wenn Sie als Kapazitätsmodus die Option Serverlos auswählen:

    • Tarifspezifischen Rabatt für den Free-Tarif anwenden
    • Georedundanz
    • Schreibvorgänge in mehreren Regionen

  7. Optional können Sie auf den folgenden Registerkarten zusätzliche Details konfigurieren:

    • Netzwerk: Konfigurieren Sie den Zugriff über ein virtuelles Netzwerk.
    • Sicherungsrichtlinie: Konfigurieren Sie eine Richtlinie für regelmäßige oder fortlaufende Sicherungen.
    • Verschlüsselung: Verwenden Sie entweder einen vom Dienst verwalteten Schlüssel oder einen kundenseitig verwalteten Schlüssel.
    • Tags: Tags sind Name-Wert-Paare, mit denen Sie Ressourcen kategorisieren und eine konsolidierte Abrechnung anzeigen können, indem Sie dasselbe Tag auf mehrere Ressourcen und Ressourcengruppen anwenden.

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

  9. Die Kontoerstellung dauert einige Minuten. Warten Sie, bis im Portal die Seite Herzlichen Glückwunsch! Ihr Azure Cosmos DB for MongoDB-Konto ist bereit angezeigt wird.

    Screenshot: Bereich „Benachrichtigungen“ im Azure-Portal

Erstellen einer Datenbank

In dieser Anwendung werden zwei Möglichkeiten zum Erstellen von Sammlungen in Azure Cosmos DB behandelt:

  • Speichern jedes Objektmodells in einer separaten Sammlung: Es wird empfohlen, eine Datenbank mit dediziertem Durchsatz zu erstellen. Mit diesem Kapazitätsmodell erhalten Sie bessere Kosteneffizienz.

    Node.js-Tutorial: Screenshot des Azure-Portals, der zeigt, wie eine Datenbank in Data Explorer für ein Azure Cosmos DB-Konto für die Verwendung mit dem Mongoose-Knotenmodul erstellt wird

  • Speichern aller Objektmodelle in einer einzigen Azure Cosmos DB-Sammlung: Wenn Sie lieber alle Modelle in einer Sammlung speichern möchten, können Sie einfach eine neue Datenbank erstellen, ohne die Option für Durchsatzbereitstellung auszuwählen. Durch die Verwendung dieses Kapazitätsmodells wird jede Sammlung mit eigener Durchsatzkapazität für jedes Objektmodell erstellt.

Nachdem Sie die Datenbank erstellt haben, verwenden Sie den Namen in der unten gezeigten Umgebungsvariablen COSMOSDB_DBNAME.

Einrichten der Node.js-Anwendung

Hinweis

Wenn Sie sich nur den Beispielcode ansehen möchten, statt die Anwendung einzurichten, klonen Sie das Beispiel, das für dieses Tutorial verwendet wird, und erstellen Sie die Node.js Mongoose-Anwendung in Azure Cosmos DB.

  1. Um eine Node.js-Anwendung in dem von Ihnen gewünschten Ordner zu erstellen, führen Sie den folgenden Befehl an einer Eingabeaufforderung für den Knoten aus.

    npm init

    Beantworten Sie die Fragen. Danach ist das Projekt einsatzbereit.

  2. Fügen Sie im Ordner eine neue Datei hinzu, und nennen Sie diese index.js.

  3. Installieren Sie die erforderlichen Pakete, indem Sie eine der npm install-Optionen verwenden:

    • Mongoose:npm install mongoose --save

    Hinweis

    Weitere Informationen dazu, welche Version von Mongoose mit Ihrer API-Version für MongoDB-Server kompatibel ist, finden Sie unter Kompatibilität mit Mongoose.

    • Dotenv (wenn Sie Ihre Geheimnisse aus einer ENV-Datei laden möchten): npm install dotenv --save

      Hinweis

      Das --save-Flag bewirkt, dass die Abhängigkeit zur Datei „package.json“ hinzugefügt wird.

  4. Importieren Sie die Abhängigkeiten in Ihre index.js-Datei.

    var mongoose = require('mongoose');
var env = require('dotenv').config();   //Use the .env file to load the variables

  5. Fügen Sie Ihre Azure Cosmos DB-Verbindungszeichenfolge und Ihren Azure Cosmos DB-Namen in der .env-Datei hinzu. Ersetzen Sie die Platzhalter „{cosmos-account-name}“ und „{dbname}“ durch Ihren eigenen Azure Cosmos DB-Kontonamen bzw. Datenbanknamen ohne die geschweiften Klammern.

    // You can get the following connection details from the Azure portal. You can find the details on the Connection string pane of your Azure Cosmos DB account.

COSMOSDB_USER = "<Azure Cosmos DB account's user name, usually the database account name>"
COSMOSDB_PASSWORD = "<Azure Cosmos DB account password, this is one of the keys specified in your account>"
COSMOSDB_DBNAME = "<Azure Cosmos DB database name>"
COSMOSDB_HOST= "<Azure Cosmos DB Host name>"
COSMOSDB_PORT=10255

  6. Stellen Sie über das Mongoose-Framework eine Verbindung mit Azure Cosmos DB her, indem Sie den folgenden Code am Ende von „index.js“ hinzufügen.

    mongoose.connect("mongodb://"+process.env.COSMOSDB_HOST+":"+process.env.COSMOSDB_PORT+"/"+process.env.COSMOSDB_DBNAME+"?ssl=true& replicaSet=globaldb", {
   auth: {
     username: process.env.COSMOSDB_USER,
     password: process.env.COSMOSDB_PASSWORD
   },
   useNewUrlParser: true,
   useUnifiedTopology: true,
   retryWrites: false
})
.then(() => console.log('Connection to CosmosDB successful'))
.catch((err) => console.error(err));

    Hinweis

    Hier werden die Umgebungsvariablen mithilfe des npm-Pakets dotenv über „process.env.{Variablenname}“ geladen.

    Sobald Sie eine Verbindung mit Azure Cosmos DB hergestellt haben, können Sie damit beginnen, Objektmodelle in Mongoose einzurichten.

Bewährte Methoden für die Verwendung von Mongoose mit Azure Cosmos DB

Für jedes Modell, das Sie erstellen, erstellt Mongoose eine neue Sammlung. Dies geschieht am besten mithilfe der Option für Durchsatz auf Datenbankebene, die weiter oben erläutert wurde. Wenn Sie eine einzelne Sammlung verwenden möchten, müssen Sie Diskriminatoren von Mongoose verwenden. Diskriminatoren sind ein Mechanismus zu Schemavererbung. Sie ermöglichen Ihnen, mehrere Modelle mit sich überschneidenden Schemas aufgesetzt auf derselben zugrunde liegenden MongoDB-Sammlung zu haben.

Sie können die verschiedenen Datenmodelle in derselben Sammlung speichern und dann zur Abfragezeit eine Filterklausel verwenden, um nur die benötigten Daten zu abzurufen. Sehen wir uns die einzelnen Modelle an.

Eine Sammlung pro Objektmodell

In diesem Abschnitt wird erläutert, wie sich dies mit der API für MongoDB von Azure Cosmos DB erreichen lässt. Diese Methode ist die empfohlene Vorgehensweise, da Sie Ihnen ermöglicht, Kosten und Kapazität zu steuern. Folglich hängt die Anzahl der Anforderungseinheiten für die Datenbank nicht von der Anzahl der Objektmodelle ab. Dies ist das Standardausführungsmodell für Mongoose, daher sind Sie möglicherweise bereits damit vertraut.

  1. Öffnen Sie erneut Ihre index.js-Datei.

  2. Erstellen Sie die Schemadefinition für „Family“.

    const Family = mongoose.model('Family', new mongoose.Schema({
    lastName: String,
    parents: [{
        familyName: String,
        firstName: String,
        gender: String
    }],
    children: [{
        familyName: String,
        firstName: String,
        gender: String,
        grade: Number
    }],
    pets:[{
        givenName: String
    }],
    address: {
        country: String,
        state: String,
        city: String
    }
}));

  3. Erstellen Sie ein Objekt für „Family“.

    const family = new Family({
    lastName: "Volum",
    parents: [
        { firstName: "Thomas" },
        { firstName: "Mary Kay" }
    ],
    children: [
        { firstName: "Ryan", gender: "male", grade: 8 },
        { firstName: "Patrick", gender: "male", grade: 7 }
    ],
    pets: [
        { givenName: "Buddy" }
    ],
    address: { country: "USA", state: "WA", city: "Seattle" }
});

  4. Speichern Sie das Objekt schließlich in Azure Cosmos DB. Dadurch wird eine Sammlung unter der Hauptebene erstellt.

    family.save((err, saveFamily) => {
    console.log(JSON.stringify(saveFamily));
});

  5. Erstellen Sie nun ein weiteres Schema und Objekt. Erstellen Sie dieses Mal ein Schema für Urlaubsziele (VacationDestinations), an denen die Familien interessiert sein könnten.

    1. Erstellen Sie das Schema so wie beim letzten Mal.

      const VacationDestinations = mongoose.model('VacationDestinations', new mongoose.Schema({
 name: String,
 country: String
}));

    2. Erstellen Sie ein Beispielobjekt (Sie können mehrere Objekte zu diesem Schema hinzufügen), und speichern Sie es.

      const vacaySpot = new VacationDestinations({
 name: "Honolulu",
 country: "USA"
});

vacaySpot.save((err, saveVacay) => {
 console.log(JSON.stringify(saveVacay));
});

  6. Nachdem Sie zum Azure-Portal gewechselt haben, sehen Sie nun zwei Sammlungen, die in Azure Cosmos DB erstellt wurden.

    Node.js-Tutorial – Screenshot des Azure-Portals, in dem ein Azure Cosmos DB-Konto angezeigt wird, wobei mehrere Sammlungsnamen hervorgehoben sind – Node-Datenbank

  7. Lesen Sie schließlich die Daten aus Azure Cosmos DB. Da das Mongoose-Standardausführungsmodell verwendet wird, sind die Lesevorgänge mit beliebigen anderen Lesevorgängen mit Mongoose identisch.

    Family.find({ 'children.gender' : "male"}, function(err, foundFamily){
    foundFamily.forEach(fam => console.log("Found Family: " + JSON.stringify(fam)));
});

Verwenden von Mongoose-Diskriminatoren, um Daten in einer einzigen Sammlung zu speichern

In dieser Methode werden Mongoose-Diskriminatoren verwendet, um möglichst geringe Kosten für jede Sammlung zu erreichen. Diskriminatoren ermöglichen es Ihnen, einen unterscheidenden Schlüssel (discriminatorKey) zu definieren, wodurch Sie die Möglichkeit erhalten, unterschiedliche Objektmodelle zu speichern und nach diesen zu unterscheiden und zu filtern.

Sie erstellen ein Basisobjektmodell, definieren einen Differenzierungsschlüssel und fügen „Family“ und „VacationDestinations“ dem Basismodell als Erweiterung hinzu.

  1. Richten Sie die Basiskonfiguration ein, und definieren Sie den Diskriminatorschlüssel.

    const baseConfig = {
    discriminatorKey: "_type", //If you've got a lot of different data types, you could also consider setting up a secondary index here.
    collection: "alldata"   //Name of the Common Collection
};

  2. Definieren Sie als Nächstes das allgemeine Objektmodell.

    const commonModel = mongoose.model('Common', new mongoose.Schema({}, baseConfig));

  3. Definieren Sie nun das „Family“-Modell. Beachten Sie hier, dass commonModel.discriminator anstelle von mongoose.model verwendet wird. Außerdem wird die Basiskonfiguration zum Mongoose-Schema hinzugefügt. Somit ist der Diskriminatorschlüssel (discriminatorKey) hier gleich FamilyType.

    const Family_common = commonModel.discriminator('FamilyType', new     mongoose.Schema({
    lastName: String,
    parents: [{
        familyName: String,
        firstName: String,
        gender: String
    }],
    children: [{
        familyName: String,
        firstName: String,
       gender: String,
        grade: Number
    }],
    pets:[{
        givenName: String
    }],
    address: {
        country: String,
        state: String,
        city: String
    }
}, baseConfig));

  4. Fügen Sie auf gleiche Weise ein weiteres Schema hinzu, und zwar diesmal für die Urlaubsziele (VacationDestinations). Hierfür ist der Diskriminatorschlüssel (discriminatorKey) gleich VacationDestinationsType.

    const Vacation_common = commonModel.discriminator('VacationDestinationsType', new mongoose.Schema({
    name: String,
    country: String
}, baseConfig));

  5. Erstellen Sie schließlich Objekte für das Modell, und speichern Sie das Modell.

    1. Fügen Sie Objekte zum „Family“-Modell hinzu.

      const family_common = new Family_common({
 lastName: "Volum",
 parents: [
     { firstName: "Thomas" },
     { firstName: "Mary Kay" }
 ],
 children: [
     { firstName: "Ryan", gender: "male", grade: 8 },
     { firstName: "Patrick", gender: "male", grade: 7 }
 ],
 pets: [
     { givenName: "Buddy" }
 ],
 address: { country: "USA", state: "WA", city: "Seattle" }
});

family_common.save((err, saveFamily) => {
 console.log("Saved: " + JSON.stringify(saveFamily));
});

    2. Fügen Sie als Nächstes Objekte zum „VacationDestinations“-Modell hinzu, und speichern Sie es.

      const vacay_common = new Vacation_common({
 name: "Honolulu",
 country: "USA"
});

vacay_common.save((err, saveVacay) => {
 console.log("Saved: " + JSON.stringify(saveVacay));
});

  6. Wenn Sie nun zum Azure-Portal zurückkehren, sehen Sie, dass es nur eine Sammlung namens alldata gibt, die sowohl die „Family“- als auch die „VacationDestinations“-Daten enthält.

    Node.js-Tutorial – Screenshot des Azure-Portals, in dem ein Azure Cosmos DB-Konto angezeigt wird, wobei der Sammlungsname hervorgehoben ist – Node-Datenbank

  7. Beachten Sie auch, dass jedes Objekt ein weiteres Attribut namens __type hat, das es Ihnen erleichtert, zwischen den beiden Objektmodellen zu unterscheiden.

  8. Lesen Sie schließlich die Daten, die in Azure Cosmos DB gespeichert sind. Mongoose übernimmt das Filtern von Daten anhand des Modells. Daher müssen Sie nicht anders vorgehen, wenn Sie Daten lesen. Geben Sie einfach Ihr Modell an (in diesem Fall Family_common), und Mongoose verwaltet das Filtern über „DiscriminatorKey“.

    Family_common.find({ 'children.gender' : "male"}, function(err, foundFamily){
    foundFamily.forEach(fam => console.log("Found Family (using discriminator): " + JSON.stringify(fam)));
});

Wie Sie sehen, ist ein Arbeiten mit Mongoose-Diskriminatoren einfach. Wenn Sie über eine App verfügen, die das Mongoose-Framework verwendet, bietet Ihnen dieses Tutorial somit eine Möglichkeit, Ihre Anwendung über die Azure Cosmos DB-API für MongoDB einzurichten und auszuführen, ohne dass zu viele Änderungen erforderlich sind.

Bereinigen von Ressourcen

Wenn Sie Ihre App und das Azure Cosmos DB-Konto fertiggestellt haben, können Sie die erstellten Azure-Ressourcen löschen, damit keine weiteren Gebühren anfallen. So löschen Sie die Ressourcen:

  1. Suchen Sie über die Suchleiste des Azure-Portals nach Ressourcengruppen, und wählen Sie die entsprechende Option aus.

  2. Wählen Sie in der Liste die Ressourcengruppe aus, die Sie für diesen Schnellstart erstellt haben.

    Auswählen der zu löschenden Ressourcengruppe

  3. Wählen Sie auf der Seite Übersicht der Ressourcengruppe die Option Ressourcengruppe löschen aus.

    Löschen der Ressourcengruppe

  4. Geben Sie in dem nächsten Fenster den Namen der zu löschenden Ressourcengruppe ein, und wählen Sie dann Löschen aus.

Nächste Schritte