Schnellstart: Erstellen einer Graphdatenbank in Azure Cosmos DB mit Python und dem Azure-Portal

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 Python-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

Hinweis

Für die in dieser Schnellstartanleitung beschriebenen Schritte benötigen Sie ein Graphdatenbankkonto, das nach dem 20. Dezember 2017 erstellt wurde. Bestehende Konten unterstützen Python, nachdem diese zur Version für die allgemeine Verfügbarkeit migriert wurden.

Erstellen eines Datenbankkontos

Vor dem Erstellen einer Graphdatenbank müssen Sie ein Gremlin (Graph)-Datenbankkonto mit Azure Cosmos DB erstellen.

  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

Beginnen wir nun mit der Verwendung von Code. 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.

    mkdir "./git-samples"
    
  2. Öffnen Sie ein Terminalfenster von Git (z. B. Git Bash), und verwenden Sie den Befehl cd, um den Ordner zu ändern, in den die Beispiel-App gespeichert wird.

    cd "./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-python-getting-started.git
    

Ü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. Die Codeausschnitte stammen alle aus der Datei connect.py im Ordner C:\git-samples\azure-cosmos-db-graph-python-getting-started\ . Andernfalls können Sie mit Aktualisieren der Verbindungszeichenfolge fortfahren.

  • Der Gremlin-Client (client) wird in connect.py in Zeile 155 initialisiert. Ersetzen Sie <YOUR_DATABASE> und <YOUR_CONTAINER_OR_GRAPH> unbedingt durch die Werte für den Datenbanknamen und den Diagrammnamen Ihres Kontos:

    ...
    client = client.Client('wss://<YOUR_ENDPOINT>.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/<YOUR_DATABASE>/colls/<YOUR_CONTAINER_OR_GRAPH>", 
        password="<YOUR_PASSWORD>")
    ...
    
  • Am Anfang der Datei connect.py wird eine Reihe von Schritten für Gremlin deklariert. Diese werden dann mit der Methode client.submitAsync() ausgeführt:

    client.submitAsync(_gremlin_cleanup_graph)
    

Aktualisieren der Verbindungsinformationen

Wechseln Sie nun zurück zum Azure-Portal, um die Verbindungsinformationen abzurufen und in die App zu kopieren. Durch diese Einstellungen kann Ihre App mit Ihrer gehosteten Datenbank kommunizieren.

  1. Wählen Sie im Azure-Portal in Ihrem Azure Cosmos DB-Konto die Option Schlüssel aus.

    Kopieren Sie den ersten Teil des URI-Werts.

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

  2. Öffnen Sie die Datei connect.py, und ersetzen Sie <YOUR_ENDPOINT> in Zeile 155 durch den URI-Wert:

    client = client.Client('wss://<YOUR_ENDPOINT>.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/<YOUR_DATABASE>/colls/<YOUR_COLLECTION_OR_GRAPH>", 
        password="<YOUR_PASSWORD>")
    

    Der URI-Teil des Clientobjekts sollte nun ungefähr wie im folgenden Code aussehen:

    client = client.Client('wss://test.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/<YOUR_DATABASE>/colls/<YOUR_COLLECTION_OR_GRAPH>", 
        password="<YOUR_PASSWORD>")
    
  3. Ändern Sie den zweiten Parameter des client-Objekts, um die Zeichenfolgen <YOUR_DATABASE> und <YOUR_COLLECTION_OR_GRAPH> zu ersetzen. Wenn Sie die vorgeschlagenen Werte verwendet haben, sollte der Parameter wie im folgenden Code aussehen:

    username="/dbs/sample-database/colls/sample-graph"

    Das gesamte client-Objekt sollte nun wie im folgenden Code aussehen:

    client = client.Client('wss://test.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/sample-database/colls/sample-graph", 
        password="<YOUR_PASSWORD>")
    
  4. Kopieren Sie auf der Seite Schlüssel den PRIMÄRSCHLÜSSEL mithilfe der Kopierschaltfläche, und fügen Sie ihn im Parameter password=<YOUR_PASSWORD> für <YOUR_PASSWORD> ein.

    Das gesamte client-Objektdefinition sollte nun wie im folgenden Code aussehen:

    client = client.Client('wss://test.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/sample-database/colls/sample-graph", 
        password="asdb13Fadsf14FASc22Ggkr662ifxz2Mg==")
    
  5. Speichern Sie die Datei connect.py.

Ausführen der Konsolenanwendung

  1. Wechseln Sie im Terminalfenster von Git mithilfe von cd zum Ordner „azure-cosmos-db-graph-python-getting-started“.

    cd "./git-samples\azure-cosmos-db-graph-python-getting-started"
    
  2. Verwenden Sie im Git-Terminalfenster den folgenden Befehl, um die erforderlichen Python-Pakete zu installieren.

    pip install -r requirements.txt
    
  3. Verwenden Sie im Git-Terminalfenster den folgenden Befehl, um die Python-Anwendung zu starten.

    python connect.py
    

    Im Terminalfenster werden die Scheitelpunkte und Kanten angezeigt, die dem Graph hinzugefügt werden.

    Wenn Timeoutfehler auftreten, überprüfen Sie, ob Sie die Verbindungsinformationen unter Aktualisieren der Verbindungsinformationen richtig aktualisiert haben, und versuchen Sie auch, den letzten Befehl erneut auszuführen.

    Drücken Sie nach Abschluss des Programms die EINGABETASTE, und wechseln Sie dann in Ihrem Internetbrowser wieder zum Azure-Portal.

Überprüfen und Hinzufügen von Beispieldaten

Nach dem Einfügen der Scheitelpunkte und Kanten können Sie wieder zum Daten-Explorer zurückkehren, um sich die dem Graph hinzugefügten Scheitelpunkte anzusehen und weitere Datenpunkte hinzuzufügen.

  1. Wählen Sie im Azure-Portal in Ihrem Azure Cosmos DB-Konto Daten-Explorer aus, erweitern Sie den Eintrag sample-graph, und wählen Sie Graph und anschließend Filter anwenden aus.

    Screenshot: In der API ausgewählter Graph mit der Option „Filter anwenden“

  2. Beachten Sie in der Liste Ergebnisse drei neue Benutzer, die dem Graph hinzugefügt wurden. Sie können die Scheitelpunkte bewegen, indem Sie sie ziehen und loslassen, zoomen, indem Sie das Mausrad verwenden, und die Größe des Graphen verändern, indem Sie auf den Doppelpfeil klicken.

    Neue Scheitelpunkte im Graph im Daten-Explorer im Azure-Portal

  3. Fügen Sie nun einige neue Benutzer hinzu. Wählen Sie die Schaltfläche Neuer Vertex aus, um dem Graph Daten hinzuzufügen.

    Screenshot: Bereich „New Vertex“ (Neuer Scheitelpunkt), in dem Sie Werte eingeben können

  4. Geben Sie als Bezeichnung Person ein.

  5. Wählen Sie Eigenschaft hinzufügen aus, um die folgenden Eigenschaften hinzuzufügen. Beachten Sie, dass Sie für jede Person in Ihrem Graph eindeutige Eigenschaften erstellen können. Nur der id-Schlüssel ist erforderlich.

    Schlüssel value Notizen
    pk /pk
    id ashley Der eindeutige Bezeichner für den Scheitelpunkt. Wenn Sie keine ID angeben, wird automatisch eine ID generiert.
    gender female
    tech java

    Hinweis

    In dieser Schnellstartanleitung wird eine nicht partitionierte Sammlung erstellt. Wenn Sie hingegen eine partitionierte Sammlung erstellen, indem Sie bei der Sammlungserstellung einen Partitionsschlüssel angeben, muss der Partitionsschlüssel jedem neuen Scheitelpunkt als Schlüssel hinzugefügt werden.

  6. Klicken Sie auf OK. Der Bildschirm muss möglicherweise erweitert werden, damit OK am unteren Bildschirmrand zu sehen ist.

  7. Wählen Sie erneut New Vertex (Neuer Scheitelpunkt) aus, und fügen Sie einen weiteren neuen Benutzer hinzu.

  8. Geben Sie als Bezeichnung Person ein.

  9. Wählen Sie Eigenschaft hinzufügen aus, um die folgenden Eigenschaften hinzuzufügen:

    Schlüssel value Notizen
    pk /pk
    id rakesh Der eindeutige Bezeichner für den Scheitelpunkt. Wenn Sie keine ID angeben, wird automatisch eine ID generiert.
    gender male
    school MIT
  10. Klicken Sie auf OK.

  11. Wählen Sie die Schaltfläche Filter anwenden mit dem Standardfilter g.V() aus, um alle Werte des Graphen anzuzeigen. Daraufhin werden alle Benutzer in der Liste Ergebnisse angezeigt.

    Wenn Sie weitere Daten hinzufügen, können Sie Ihre Ergebnisse mithilfe von Filtern eingrenzen. Daten-Explorer verwendet standardmäßig g.V(), um alle Scheitelpunkte eines Graphen abzurufen. Sie können ihn in eine andere Graphabfrage wie z.B. g.V().count() ändern, um die Anzahl aller Scheitelpunkte eines Graphen im JSON-Format zurückzugeben. Wenn Sie den Filter geändert haben, ändern Sie den Filter zurück in g.V(), und wählen Sie Filter anwenden aus, um wieder alle Ergebnisse anzuzeigen.

  12. Als Nächstes verbinden wir „rakesh“ und „ashley“. Vergewissern Sie sich, dass ashley in der Liste Ergebnisse ausgewählt ist, und wählen Sie anschließend rechts unten neben Ziele die Bearbeitungsschaltfläche aus. Möglicherweise müssen Sie Ihr Fenster verbreitern, damit der Bereich Eigenschaften zu sehen ist.

    Ändern des Ziels eines Scheitelpunkts in einem Graph

  13. Geben Sie im Feld Ziel die Zeichenfolge rakesh und im Feld Kantenbezeichnung die Zeichenfolge knows ein, und wählen Sie anschließend das Häkchen aus.

    Hinzufügen einer Verbindung zwischen „ashley“ und „rakesh“ im Daten-Explorer

  14. Wählen Sie nun in der Ergebnisliste den Eintrag rakesh aus. Wie Sie sehen, sind „ashley“ und „rakesh“ miteinander verbunden.

    Zwei verbundene Scheitelpunkte im Daten-Explorer

Damit haben Sie den Teil des Tutorials, in dem die Ressourcen erstellt werden, abgeschlossen. Sie können weiter Scheitelpunkte zu Ihrem Graphen hinzufügen, die vorhandenen Scheitelpunkte anpassen oder die Abfragen ändern. Sehen Sie sich nun die von Azure Cosmos DB bereitgestellten Metriken an, und bereinigen Sie anschließend die Ressourcen.

Ü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 dieser Schnellstartanleitung haben Sie gelernt, wie Sie ein Azure Cosmos DB-Konto erstellen, einen Graph mit dem Daten-Explorer erstellen und eine Python-App ausführen, um dem Graph Daten hinzuzufügen. Nun können Sie komplexere Abfragen erstellen und leistungsfähige Logik zum Traversieren von Graphen mit Gremlin implementieren.