Schnellstart: Erstellen einer Node.js-Anwendung mithilfe eines Gremlin-API-Kontos für Azure Cosmos DB

GILT FÜR: Gremlin-API

In dieser Schnellstartanleitung erstellen und verwalten Sie ein Azure Cosmos DB-Gremlin-API-Konto (Graph) im Azure-Portal und fügen Daten mithilfe einer über GitHub geklonten Node.js-App hinzu. Azure Cosmos DB ist ein Multimodell-Datenbankdienst, mit dem Sie mithilfe der Funktionen für globale Verteilung und horizontale Skalierung schnell Dokument-, Tabellen-, Schlüssel-Wert- und Graph-Datenbanken erstellen und abfragen können.

Voraussetzungen

Erstellen eines Datenbankkontos

  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.

    Erstellen einer Ressource im Azure-Portal

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

    Die Bereich „Datenbanken“ im Azure-Portal

    Tipp

    Wenn Azure Cosmos DB in der Liste nicht angezeigt wird, geben Sie den Namen einfach oben auf der Seite in das Suchfeld ein, und drücken Sie die EINGABETASTE.

  4. 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 Ihr Abonnement Wählen Sie das Azure-Abonnement aus, das Sie für dieses Azure Cosmos DB-Konto verwenden möchten.
    Ressourcengruppe Neu erstellen

    Geben Sie dann den gleichen Namen als Kontonamen ein.
    Wählen Sie Neu erstellen. Geben Sie dann einen neuen Ressourcengruppenname für Ihr Konto ein. Verwenden Sie der Einfachheit halber den gleichen Namen als Azure Cosmos DB-Kontonamen.
    Kontoname Geben Sie einen eindeutigen Namen ein. Geben Sie einen eindeutigen Namen ein, der Ihr Azure Cosmos DB-Konto identifiziert. Der Konto-URI lautet gremlin.azure.com und wird an Ihren eindeutigen Kontonamen angehängt.

    Der Kontoname darf nur Kleinbuchstaben, Ziffern und Bindestriche (-) enthalten und muss zwischen 3 und 31 Zeichen lang sein.
    API Gremlin (Diagramm) Die API bestimmt den Typ des zu erstellenden Kontos. Azure Cosmos DB stellt fünf APIs bereit: Kern-API (SQL) für Dokumentdatenbanken, Gremlin-API für Graphdatenbanken, MongoDB-API für Dokumentdatenbanken, Azure-Tabellen-API und Cassandra-API. Sie müssen ein separates Konto für jede API erstellen.

    Wählen Sie Gremlin (graph) aus, da Sie in dieser Schnellstartanleitung eine Tabelle erstellen, die mit der Gremlin-API verwendet werden kann.

    Weitere Informationen zur Gremlin-API
    Standort Wählen Sie die Region aus, 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 einen Standort, der Ihren Benutzern am nächsten liegt, um ihnen einen schnellen Zugriff auf die Daten zu gewähren.
    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.

    Wählen Sie Bewerten + erstellen aus. Sie können die Abschnitte Netzwerk und Tags überspringen.

    Die Seite „Neues Konto“ für Azure Cosmos DB

  5. Die Kontoerstellung dauert einige Minuten. Warten Sie, bis das Portal die Seite Herzlichen Glückwunsch! Ihr Azure Cosmos DB-Konto wurde erstellt anzeigt.

    Seite mit erstelltem Azure Cosmos DB-Konto

Hinzufügen eines Graphs

Sie können nun mithilfe des Daten-Explorer-Tools im Azure-Portal eine Diagrammdatenbank erstellen.

  1. Wählen Sie Daten-Explorer > New Graph (Neues Diagramm) aus.

    Der Bereich Add Graph (Graph hinzufügen) wird rechts angezeigt. Möglicherweise müssen Sie nach rechts scrollen, damit Sie ihn sehen.

    „Daten-Explorer“ im Azure-Portal, Seite „Graph hinzufügen“

  2. Geben Sie auf der Seite Graph hinzufügen die Einstellungen für den neuen Graphen ein.

    Einstellung Vorgeschlagener Wert BESCHREIBUNG
    Datenbank-ID sample-database Geben Sie sample-database als Namen für die neue Datenbank ein. Datenbanknamen müssen zwischen 1 und 255 Zeichen lang sein und dürfen weder / \ # ? noch nachgestellte Leerzeichen enthalten.
    Throughput 400 RUs Ändern Sie den Durchsatz in 400 Anforderungseinheiten pro Sekunde (RU/s). Sie können den Durchsatz später zentral hochskalieren, wenn Sie Wartezeiten verringern möchten.
    Graph-ID sample-graph Geben Sie sample-graph als Namen für die neue Sammlung ein. Für Diagrammnamen gelten dieselben Zeichenanforderungen wie für Datenbank-IDs.
    Partitionsschlüssel /pk Alle Cosmos DB-Konten benötigen zum horizontalen Skalieren einen Partitionsschlüssel. Informationen zum Auswählen eines geeigneten Partitionsschlüssels finden Sie unter Verwenden eines partitionierten Graphen in Azure Cosmos DB.
  3. Wählen Sie OK aus, nachdem Sie das Formular ausgefüllt haben.

Klonen der Beispielanwendung

Klonen Sie eine Gremlin-API-App aus GitHub, legen Sie die Verbindungszeichenfolge fest, und führen Sie sie aus. Sie werden feststellen, wie einfach Sie programmgesteuert mit Daten arbeiten können.

  1. Öffnen Sie eine Eingabeaufforderung, erstellen Sie einen neuen Ordner namens „git-samples“, und schließen Sie die Eingabeaufforderung.

    md "C:\git-samples"
    
  2. Öffnen Sie ein Git-Terminalfenster (z.B. git bash), und verwenden Sie den Befehl cd, um in den neuen Ordner zu gelangen und dort die Beispiel-App zu installieren.

    cd "C:\git-samples"
    
  3. Führen Sie den folgenden Befehl aus, um das Beispielrepository zu klonen. Dieser Befehl erstellt eine Kopie der Beispiel-App auf Ihrem Computer.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-nodejs-getting-started.git
    
  4. Öffnen Sie die Projektmappendatei in Visual Studio.

Überprüfen des Codes

Dieser Schritt ist optional. Wenn Sie erfahren möchten, wie die Datenbankressourcen im Code erstellt werden, können Sie sich die folgenden Codeausschnitte ansehen. Andernfalls können Sie mit Aktualisieren der Verbindungszeichenfolge fortfahren.

Die folgenden Codeausschnitte stammen alle aus der Datei app.js.

In dieser Konsolen-App wird der Open-Source-Treiber Gremlin Node.js verwendet.

  • Der Gremlin-Client wird erstellt.

    const authenticator = new Gremlin.driver.auth.PlainTextSaslAuthenticator(
        `/dbs/${config.database}/colls/${config.collection}`, 
        config.primaryKey
    )
    
    
    const client = new Gremlin.driver.Client(
        config.endpoint, 
        { 
            authenticator,
            traversalsource : "g",
            rejectUnauthorized : true,
            mimeType : "application/vnd.gremlin-v2.0+json"
        }
    );
    
    

    Die Konfigurationen befinden sich alle in config.js. Diese Datei wird im folgenden Abschnitt bearbeitet.

  • Eine Reihe von Funktionen wird definiert, um verschiedene Gremlin-Vorgänge auszuführen. Hierzu zählt beispielsweise Folgendes:

    function addVertex1()
    {
        console.log('Running Add Vertex1'); 
        return client.submit("g.addV(label).property('id', id).property('firstName', firstName).property('age', age).property('userid', userid).property('pk', 'pk')", {
                label:"person",
                id:"thomas",
                firstName:"Thomas",
                age:44, userid: 1
            }).then(function (result) {
                    console.log("Result: %s\n", JSON.stringify(result));
            });
    }
    
  • Jede Funktion führt eine Methode vom Typ client.execute mit einem Gremlin-Abfragezeichenfolgenparameter aus. Beispiel für die Ausführung von g.V().count():

    function countVertices()
    {
        console.log('Running Count');
        return client.submit("g.V().count()", { }).then(function (result) {
            console.log("Result: %s\n", JSON.stringify(result));
        });
    }
    
  • Am Ende der Datei werden dann alle Methoden aufgerufen. So werden sie nacheinander ausgeführt:

    client.open()
    .then(dropGraph)
    .then(addVertex1)
    .then(addVertex2)
    .then(addEdge)
    .then(countVertices)
    .catch((err) => {
        console.error("Error running query...");
        console.error(err)
    }).then((res) => {
        client.close();
        finish();
    }).catch((err) => 
        console.error("Fatal error:", err)
    );
    

Aktualisieren der Verbindungszeichenfolge

  1. Öffnen Sie die Datei config.js.

  2. Fügen Sie in der Datei config.js den config.endpoint-Schlüssel mit dem Wert für den Gremlin-Endpunkt von der Seite Übersicht Ihres Cosmos DB-Kontos im Azure-Portal ein.

    config.endpoint = "https://<your_Gremlin_account_name>.gremlin.cosmosdb.azure.com:443/";

    Anzeigen und Kopieren eines Zugriffsschlüssels im Azure-Portal auf der Seite „Übersicht“

  3. Fügen Sie in der Datei config.js den config.primaryKey-Wert mit dem Wert für Primärschlüssel von der Seite Schlüssel Ihres Cosmos DB-Kontos im Azure-Portal ein.

    config.primaryKey = "PRIMARYKEY";

    Azure-Portal-Blatt „Schlüssel“

  4. Geben Sie den Datenbanknamen und den Graphnamen (Container) für den Wert von „config.database“ und „config.collection“ ein.

Hier sehen Sie ein Beispiel dafür, wie Ihre fertige Datei config.js aussehen sollte:

var config = {}

// Note that this must include the protocol (HTTPS:// for .NET SDK URI or wss:// for Gremlin Endpoint) and the port number
config.endpoint = "https://testgraphacct.gremlin.cosmosdb.azure.com:443/"; 
config.primaryKey = "Pams6e7LEUS7LJ2Qk0fjZf3eGo65JdMWHmyn65i52w8ozPX2oxY3iP0yu05t9v1WymAHNcMwPIqNAEv3XDFsEg==";
config.database = "graphdb"
config.collection = "Persons"

module.exports = config;

Ausführen der Konsolenanwendung

  1. Öffnen Sie ein Terminalfenster, und wechseln Sie (über den cd-Befehl) zum Installationsverzeichnis der Datei package.json, die im Projekt enthalten ist.

  2. Führen Sie npm install aus, um die erforderlichen npm-Module zu installieren, einschließlich gremlin.

  3. Führen Sie node app.js in einem Terminal aus, um Ihre Node-Anwendung zu starten.

Durchsuchen mit dem Daten-Explorer

Sie können nun zum Daten-Explorer im Azure-Portal zurückkehren, um mit den neuen Graph-Daten zu arbeiten und um diese anzuzeigen, abzufragen und zu ändern.

Im Daten-Explorer wird die neue Datenbank im Diagrammbereich angezeigt. Erweitern Sie die Datenbank und den Container, und wählen Sie anschließend Graph aus.

Die von der Beispiel-App generierten Daten werden im nächsten Bereich auf der Registerkarte Graph angezeigt, wenn Sie Filter anwenden auswählen.

Vervollständigen Sie g.V() mit .has('firstName', 'Thomas'), um den Filter zu testen. Halten Sie sich dabei an die Groß-/Kleinschreibung des Werts.

Überprüfen von SLAs im Azure-Portal

Im Azure-Portal werden Durchsatz, Speicher, Verfügbarkeit, Wartezeit und Konsistenz Ihres Cosmos DB-Kontos überwacht. Diagramme für Metriken einer Azure Cosmos DB-SLA (Service Level Agreement, Vereinbarung zum Servicelevel) zeigen den SLA-Wert im Vergleich zur tatsächlichen Leistung. Diese Sammlung von Metriken macht die Überwachung Ihrer SLAs transparent.

So überprüfen Sie Metriken und SLAs:

  1. Wählen Sie im Navigationsmenü Ihres Cosmos DB-Kontos die Option Metrik aus.

  2. Wählen Sie eine Registerkarte (etwa Wartezeit) und auf der rechten Seite einen Zeitraum aus. Vergleichen Sie Zeilen Tatsächlich und SLA in den Diagrammen.

    Azure Cosmos DB-Metriken

  3. Überprüfen Sie die Metriken auf den anderen Registerkarten.

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

In diesem Artikel haben Sie gelernt, wie Sie ein Azure Cosmos DB-Konto erstellen, einen Graph mit dem Daten-Explorer erstellen und eine Node.js-App ausführen, um dem Graph Daten hinzuzufügen. Nun können Sie komplexere Abfragen erstellen und leistungsfähige Logik zum Durchlaufen von Diagrammen mit Gremlin implementieren.