Schnellstart: Erstellen, Abfragen und Durchlaufen einer Azure Cosmos DB-Graphdatenbank mithilfe der Gremlin-Konsole

GILT FÜR: Gremlin-API

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.

In dieser Schnellstartanleitung erfahren Sie, wie Sie mithilfe des Azure-Portals ein Gremlin-API-Konto, eine Datenbank und einen Graph (Container) in Azure Cosmos DB erstellen und anschließend über die Gremlin-Konsole von Apache TinkerPop mit Daten der Gremlin-API arbeiten. In diesem Tutorial erstellen Sie Scheitelpunkte und Kanten und fragen diese ab. Außerdem führen Sie eine Aktualisierung einer Scheitelpunkteigenschaft durch sowie eine Abfrage von Scheitelpunkten, eine Übertragung eines Graphen und das Löschen eines Scheitelpunkts.

Azure Cosmos DB in der Gremlin-Konsole von Apache

Die Gremlin-Konsole basiert auf Groovy bzw. Java und kann unter Linux, Mac und Windows ausgeführt werden. Sie können die Konsole von der Seite „Apache TinkerPop“ herunterladen.

Voraussetzungen

Zum Erstellen eines Azure Cosmos DB-Kontos für diesen Schnellstart benötigen Sie ein Azure-Abonnement.

Wenn Sie kein Azure-Abonnement besitzen, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.

Außerdem müssen Sie die Gremlin-Konsole installieren. Die empfohlene Version ist v3.4.3 oder früher. (Zur Verwendung der Gremlin-Konsole unter Windows müssen Sie Java Runtime installieren).

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.

Herstellen einer Verbindung mit Ihrem App-Dienst/Graph

  1. Erstellen bzw. ändern Sie die Konfigurationsdatei „remote-secure.yaml“ im Verzeichnis apache-tinkerpop-gremlin-console-3.2.5/conf, bevor Sie die Gremlin-Konsole starten.

  2. Füllen Sie die Konfigurationen Host, Port, Benutzername, Kennwort, connectionPool und Serialisierungsmodul aus, wie in der folgenden Tabelle definiert:

    Einstellung Vorgeschlagener Wert BESCHREIBUNG
    hosts [account-name.gremlin.cosmos.azure.com] Der folgende Screenshot zeigt dies. Dies ist der Wert für den Gremlin-URI auf der Seite „Übersicht“ des Azure-Portals (in eckigen Klammern und ohne den Zusatz „:443/“). Hinweis: Achten Sie darauf, den Gremlin-Wert und nicht den URI zu verwenden, der auf [account-name.documents.azure.com] endet. Andernfalls wird beim späteren Ausführen von Gremlin-Abfragen wahrscheinlich eine Ausnahme „Host did not respond in a timely fashion“ (Host hat nicht rechtszeitig reagiert) ausgelöst.
    port 443 Legen Sie den Wert 443 fest.
    username Ihr Benutzername Die Ressource im Format /dbs/<db>/colls/<coll>, wobei <db> der Datenbankname und <coll> der Sammlungsname ist.
    password Ihr Primärschlüssel Siehe zweiten Screenshot unten. Dies ist Ihr Primärschlüssel, den Sie von der Seite „Schlüssel“ des Azure-Portals im Feld „Primärschlüssel“ abrufen können. Verwenden Sie die Schaltfläche „Kopieren“ links vom Feld, um den Wert zu kopieren.
    connectionPool {enableSsl: true} Ihre Verbindungspooleinstellung für TLS.
    serializer { className: org.apache.tinkerpop.gremlin.
    driver.ser.GraphSONMessageSerializerV2d0,
    config: { serializeResultToString: true }}
    Legen Sie diesen Wert fest, und löschen Sie alle \n-Zeilenumbrüche, wenn Sie den Wert einfügen.

    Kopieren Sie zur Angabe des Werts „Hosts“ den Gremlin-URI auf der Seite Übersicht:

    Anzeigen und Kopieren des den Gremlin-URI-Werts auf der Seite „Übersicht“ im Azure-Portal

    Kopieren Sie für den Kennwortwert den Primärschlüssel aus der Seite Schlüssel:

    Anzeigen und Kopieren Ihres Primärschlüssels im Azure-Portal, Seite „Schlüssel“

    Die Datei „remote-secure.yaml“ sollte wie folgt aussehen:

    hosts: [your_database_server.gremlin.cosmos.azure.com] 
    port: 443
    username: /dbs/your_database_account/colls/your_collection
    password: your_primary_key
    connectionPool: {
      enableSsl: true
    }
    serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV2d0, config: { serializeResultToString: true }}
    

    Setzen Sie den Wert des hosts-Parameters in eckige Klammern: [].

  3. Führen Sie in Ihrem Terminal bin/gremlin.bat oder bin/gremlin.sh aus, um die Gremlin-Konsole zu starten.

  4. Führen Sie in Ihrem Terminal :remote connect tinkerpop.server conf/remote-secure.yaml aus, um eine Verbindung mit Ihrer App Service-Instanz herzustellen.

    Tipp

    Sollte die Fehlermeldung No appenders could be found for logger angezeigt werden, vergewissern Sie sich, dass der Serialisierungsmodulwert in der Datei „remote-secure.yaml“ wie in Schritt 2 beschrieben aktualisiert wurde. Wenn Ihre Konfiguration korrekt ist, kann diese Warnung sicher ignoriert werden, da Sie sich nicht auf die Verwendung der Konsole auswirkt.

  5. Führen Sie als Nächstes :remote console aus, um alle Konsolenbefehle an den Remoteserver umzuleiten.

    Hinweis

    Wenn Sie den :remote console-Befehl nicht ausführen, aber alle Konsolenbefehle an den Remoteserver umleiten möchten, sollten Sie dem Befehl ein :> voranstellen. So sollten Sie den Befehl beispielsweise als :> g.V().count() ausführen. Dieses Präfix ist ein Teil des Befehls und wichtig bei der Verwendung der Gremlin-Konsole mit Azure Cosmos DB. Wenn Sie das Präfix weglassen, wird die Konsole angewiesen, den Befehl lokal auszuführen. Dies wird häufig für einen In-Memory-Graphen durchgeführt. Mit diesem Präfix – :> – weisen Sie die Konsole an, einen Remotebefehl auszuführen – in diesem Fall für Azure Cosmos DB (entweder der localhost-Emulator oder eine Azure-Instanz).

Prima. Damit ist die Einrichtung abgeschlossen. Jetzt können Sie mit dem Ausführen von Konsolenbefehlen beginnen.

Probieren Sie einen einfachen count()-Befehl aus. Geben Sie an der Eingabeaufforderung in der Konsole Folgendes ein:

g.V().count()

Erstellen von Scheitelpunkten und Kanten

Fügen Sie zunächst fünf Scheitelpunkte für Personen hinzu: Thomas, Mary Kay, Robin, Ben und Jack.

Eingabe (Thomas):

g.addV('person').property('firstName', 'Thomas').property('lastName', 'Andersen').property('age', 44).property('userid', 1).property('pk', 'pk')

Ausgabe:

==>[id:796cdccc-2acd-4e58-a324-91d6f6f5ed6d,label:person,type:vertex,properties:[firstName:[[id:f02a749f-b67c-4016-850e-910242d68953,value:Thomas]],lastName:[[id:f5fa3126-8818-4fda-88b0-9bb55145ce5c,value:Andersen]],age:[[id:f6390f9c-e563-433e-acbf-25627628016e,value:44]],userid:[[id:796cdccc-2acd-4e58-a324-91d6f6f5ed6d|userid,value:1]]]]

Eingabe (Mary Kay):

g.addV('person').property('firstName', 'Mary Kay').property('lastName', 'Andersen').property('age', 39).property('userid', 2).property('pk', 'pk')

Ausgabe:

==>[id:0ac9be25-a476-4a30-8da8-e79f0119ea5e,label:person,type:vertex,properties:[firstName:[[id:ea0604f8-14ee-4513-a48a-1734a1f28dc0,value:Mary Kay]],lastName:[[id:86d3bba5-fd60-4856-9396-c195ef7d7f4b,value:Andersen]],age:[[id:bc81b78d-30c4-4e03-8f40-50f72eb5f6da,value:39]],userid:[[id:0ac9be25-a476-4a30-8da8-e79f0119ea5e|userid,value:2]]]]

Eingabe (Robin):

g.addV('person').property('firstName', 'Robin').property('lastName', 'Wakefield').property('userid', 3).property('pk', 'pk')

Ausgabe:

==>[id:8dc14d6a-8683-4a54-8d74-7eef1fb43a3e,label:person,type:vertex,properties:[firstName:[[id:ec65f078-7a43-4cbe-bc06-e50f2640dc4e,value:Robin]],lastName:[[id:a3937d07-0e88-45d3-a442-26fcdfb042ce,value:Wakefield]],userid:[[id:8dc14d6a-8683-4a54-8d74-7eef1fb43a3e|userid,value:3]]]]

Eingabe (Ben):

g.addV('person').property('firstName', 'Ben').property('lastName', 'Miller').property('userid', 4).property('pk', 'pk')

Ausgabe:

==>[id:ee86b670-4d24-4966-9a39-30529284b66f,label:person,type:vertex,properties:[firstName:[[id:a632469b-30fc-4157-840c-b80260871e9a,value:Ben]],lastName:[[id:4a08d307-0719-47c6-84ae-1b0b06630928,value:Miller]],userid:[[id:ee86b670-4d24-4966-9a39-30529284b66f|userid,value:4]]]]

Eingabe (Jack):

g.addV('person').property('firstName', 'Jack').property('lastName', 'Connor').property('userid', 5).property('pk', 'pk')

Ausgabe:

==>[id:4c835f2a-ea5b-43bb-9b6b-215488ad8469,label:person,type:vertex,properties:[firstName:[[id:4250824e-4b72-417f-af98-8034aa15559f,value:Jack]],lastName:[[id:44c1d5e1-a831-480a-bf94-5167d133549e,value:Connor]],userid:[[id:4c835f2a-ea5b-43bb-9b6b-215488ad8469|userid,value:5]]]]

Fügen Sie als Nächstes Kanten für die Personenbeziehungen hinzu.

Eingabe (Thomas -> Mary Kay):

g.V().hasLabel('person').has('firstName', 'Thomas').addE('knows').to(g.V().hasLabel('person').has('firstName', 'Mary Kay'))

Ausgabe:

==>[id:c12bf9fb-96a1-4cb7-a3f8-431e196e702f,label:knows,type:edge,inVLabel:person,outVLabel:person,inV:0d1fa428-780c-49a5-bd3a-a68d96391d5c,outV:1ce821c6-aa3d-4170-a0b7-d14d2a4d18c3]

Eingabe (Thomas -> Robin):

g.V().hasLabel('person').has('firstName', 'Thomas').addE('knows').to(g.V().hasLabel('person').has('firstName', 'Robin'))

Ausgabe:

==>[id:58319bdd-1d3e-4f17-a106-0ddf18719d15,label:knows,type:edge,inVLabel:person,outVLabel:person,inV:3e324073-ccfc-4ae1-8675-d450858ca116,outV:1ce821c6-aa3d-4170-a0b7-d14d2a4d18c3]

Eingabe (Robin -> Ben):

g.V().hasLabel('person').has('firstName', 'Robin').addE('knows').to(g.V().hasLabel('person').has('firstName', 'Ben'))

Ausgabe:

==>[id:889c4d3c-549e-4d35-bc21-a3d1bfa11e00,label:knows,type:edge,inVLabel:person,outVLabel:person,inV:40fd641d-546e-412a-abcc-58fe53891aab,outV:3e324073-ccfc-4ae1-8675-d450858ca116]

Aktualisieren eines Scheitelpunkts

Aktualisieren Sie den Scheitelpunkt Thomas mit dem neuen Alter 45.

Eingabe:

g.V().hasLabel('person').has('firstName', 'Thomas').property('age', 45)

Ausgabe:

==>[id:ae36f938-210e-445a-92df-519f2b64c8ec,label:person,type:vertex,properties:[firstName:[[id:872090b6-6a77-456a-9a55-a59141d4ebc2,value:Thomas]],lastName:[[id:7ee7a39a-a414-4127-89b4-870bc4ef99f3,value:Andersen]],age:[[id:a2a75d5a-ae70-4095-806d-a35abcbfe71d,value:45]]]]

Abfragen des Graphs

Jetzt können Sie einige Abfragen mit dem Graph durchführen.

Führen Sie zunächst eine Abfrage mit einem Filter durch, um nur Personen zurückzugeben, die älter als 40 sind.

Eingabe (Filterabfrage):

g.V().hasLabel('person').has('age', gt(40))

Ausgabe:

==>[id:ae36f938-210e-445a-92df-519f2b64c8ec,label:person,type:vertex,properties:[firstName:[[id:872090b6-6a77-456a-9a55-a59141d4ebc2,value:Thomas]],lastName:[[id:7ee7a39a-a414-4127-89b4-870bc4ef99f3,value:Andersen]],age:[[id:a2a75d5a-ae70-4095-806d-a35abcbfe71d,value:45]]]]

Projizieren Sie als Nächstes die Vornamen aller Personen, die älter als 40 sind.

Eingabe (Filter + Abfrage zur Projektion):

g.V().hasLabel('person').has('age', gt(40)).values('firstName')

Ausgabe:

==>Thomas

Traversieren des Graphs

Traversieren Sie den Graph, um alle Freunde von Thomas zurückzugeben.

Eingabe (Freunde von Thomas):

g.V().hasLabel('person').has('firstName', 'Thomas').outE('knows').inV().hasLabel('person')

Ausgabe:

==>[id:f04bc00b-cb56-46c4-a3bb-a5870c42f7ff,label:person,type:vertex,properties:[firstName:[[id:14feedec-b070-444e-b544-62be15c7167c,value:Mary Kay]],lastName:[[id:107ab421-7208-45d4-b969-bbc54481992a,value:Andersen]],age:[[id:4b08d6e4-58f5-45df-8e69-6b790b692e0a,value:39]]]]
==>[id:91605c63-4988-4b60-9a30-5144719ae326,label:person,type:vertex,properties:[firstName:[[id:f760e0e6-652a-481a-92b0-1767d9bf372e,value:Robin]],lastName:[[id:352a4caa-bad6-47e3-a7dc-90ff342cf870,value:Wakefield]]]]

Gehen Sie dann zur nächsten Scheitelpunktebene über. Traversieren Sie den Graph, um alle Freunde von Freunden von Thomas zurückzugeben.

Eingabe (Freunde von Freunden von Thomas):

g.V().hasLabel('person').has('firstName', 'Thomas').outE('knows').inV().hasLabel('person').outE('knows').inV().hasLabel('person')

Ausgabe:

==>[id:a801a0cb-ee85-44ee-a502-271685ef212e,label:person,type:vertex,properties:[firstName:[[id:b9489902-d29a-4673-8c09-c2b3fe7f8b94,value:Ben]],lastName:[[id:e084f933-9a4b-4dbc-8273-f0171265cf1d,value:Miller]]]]

Löschen eines Scheitelpunkts

Löschen Sie jetzt einen Scheitelpunkt aus der Graphdatenbank.

Eingabe (Löschen des Scheitelpunkts „Jack“):

g.V().hasLabel('person').has('firstName', 'Jack').drop()

Bereinigen des Graphs

Löschen Sie zum Schluss alle Scheitelpunkte und Kanten aus der Datenbank.

Eingabe:

g.E().drop()
g.V().drop()

Glückwunsch! Sie haben das Tutorial zu Azure Cosmos DB: Gremlin-API erfolgreich abgeschlossen.

Ü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 Schnellstart haben Sie erfahren, wie Sie ein Konto für Azure Cosmos DB und einen Graph mit dem Daten-Explorer erstellen können. Außerdem wissen Sie nun, wie Sie Scheitelpunkte und Kanten erstellen können, und wie Sie den Graph mit der Gremlin-Konsole traversieren können. Nun können Sie komplexere Abfragen erstellen und leistungsfähige Logik zum Traversieren von Graphen mit Gremlin implementieren.