Schnellstart: Azure Cosmos DB for Apache Gremlin-Bibliothek für Python

Artikel
10/09/2023

GILT FÜR: Gremlin

Azure Cosmos DB for Apache Gremlin ist ein vollständig verwalteter Graphdatenbankdienst, der das beliebte Graphcomputingframework Apache Tinkerpop mit der Abfragesprache Gremlin implementiert. Die API für Gremlin ermöglicht mit einem Dienst, der mit minimalem Verwaltungsaufwand beliebig wachsen und skaliert werden kann, einen reibungslosen Einstieg in die Verwendung von Gremlin.

In dieser Schnellstartanleitung verwenden Sie die gremlinpython-Bibliothek, um eine Verbindung mit einem neu erstellten Azure Cosmos DB for Gremlin-Konto herzustellen.

Quellcode der Bibliothek | Paket (PyPi)

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement.
- Kein Azure-Abonnement? Registrieren Sie sich für ein kostenloses Azure-Konto.
- Sie möchten kein Azure-Abonnement? Sie können Azure Cosmos DB kostenlos testen, ohne dass ein Abonnement erforderlich ist.
Python (neueste Version)
- Haben Sie Python nicht installiert? Probieren Sie diese Schnellstartanleitung in GitHub Codespaces aus.
Azure-Befehlszeilenschnittstelle (CLI)

Azure Cloud Shell

Azure hostet Azure Cloud Shell, eine interaktive Shell-Umgebung, die Sie über Ihren Browser nutzen können. Sie können entweder Bash oder PowerShell mit Cloud Shell verwenden, um mit Azure-Diensten zu arbeiten. Sie können die vorinstallierten Befehle von Cloud Shell verwenden, um den Code in diesem Artikel auszuführen, ohne etwas in Ihrer lokalen Umgebung installieren zu müssen.

Starten von Azure Cloud Shell:

Option	Beispiel/Link
Wählen Sie rechts oben in einem Code- oder Befehlsblock die Option Ausprobieren aus. Durch die Auswahl von Ausprobieren wird der Code oder Befehl nicht automatisch in Cloud Shell kopiert.
Rufen Sie https://shell.azure.com auf, oder klicken Sie auf die Schaltfläche Cloud Shell starten, um Cloud Shell im Browser zu öffnen.
Wählen Sie im Azure-Portal rechts oben im Menü die Schaltfläche Cloud Shell aus.

So verwenden Sie Azure Cloud Shell:

Starten Sie Cloud Shell.
Wählen Sie die Schaltfläche Kopieren für einen Codeblock (oder Befehlsblock) aus, um den Code oder Befehl zu kopieren.
Fügen Sie den Code oder Befehl mit STRG+UMSCHALT+V unter Windows und Linux oder CMD+UMSCHALT+V unter macOS in die Cloud Shell-Sitzung ein.
Drücken Sie die EINGABETASTE, um den Code oder Befehl auszuführen.

Einrichten

In diesem Abschnitt erfahren Sie, wie Sie ein API für Gremlin-Konto erstellen und ein Python-Projekt einrichten, um die Bibliothek zum Herstellen einer Verbindung mit dem Konto zu verwenden.

Erstellen eines API für Gremlin-Kontos

Das API für Gremlin-Konto sollte vor der Verwendung der Python-Bibliothek erstellt werden. Darüber hinaus ist es hilfreich, wenn die Datenbank und der Graph bereits vorhanden sind.

Erstellen Sie Shellvariablen für accountName, resourceGroupName und location.

# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
location="westus"

# Variable for account name with a randomly generated suffix

let suffix=$RANDOM*$RANDOM
accountName="msdocs-gremlin-$suffix"

Melden Sie sich mithilfe von az login bei der Azure CLI an, falls Sie dies noch nicht getan haben.
Verwenden Sie az group create, um eine neue Ressourcengruppe in Ihrem Abonnement zu erstellen.
```
az group create \
    --name $resourceGroupName \
    --location $location
```
Verwenden Sie az cosmosdb create, um ein neues „API für Gremlin“-Konto mit Standardeinstellungen zu erstellen.
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
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. Ist dieser Befehl zum Anwenden des tarifspezifischen Rabatts für den Free-Tarif nicht erfolgreich, bedeutet dies, dass bereits ein anderes Konto im Abonnement mit dem Free-Tarif aktiviert wurde.

Rufen Sie mithilfe von az cosmosdb show den API für Gremlin-Endpunkt NAME für das Konto ab:

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"

Ermitteln Sie mit az-cosmosdb-keys-list den SCHLÜSSEL in der Liste der Schlüssel für das Konto:

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

Notieren Sie sich die Werte für NAME und SCHLÜSSEL. Sie verwenden diese Anmeldeinformationen später.

Erstellen Sie mithilfe von az cosmosdb gremlin database create eine Datenbank mit der Bezeichnung cosmicworks:

az cosmosdb gremlin database create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --name "cosmicworks"

Erstellen Sie mithilfe von az cosmosdb gremlin graph create einen Graphen. Nennen Sie den Graphen products, und legen Sie den Durchsatz auf 400 und den Partitionsschlüsselpfad auf /category fest.

az cosmosdb gremlin graph create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category" \
    --throughput 400

Erstellen einer neuen Python-Konsolenanwendung

Erstellen Sie mithilfe Ihres bevorzugten Terminals in einem leeren Ordner eine Python-Konsolenanwendung.

Öffnen Sie Ihr Terminal in einem leeren Ordner.
Erstellen Sie die Datei app.py.
```
touch app.py
```

Installieren des PyPI-Pakets

Fügen Sie dem Python-Projekt das PyPI-Paket gremlinpython hinzu.

Erstellen Sie die Datei requirements.txt.
```
touch requirements.txt
```
Fügen Sie das Paket gremlinpython aus dem Python-Paketindex der Anforderungsdatei hinzu.
```
gremlinpython==3.7.0
```
Installieren Sie alle Anforderungen für Ihr Projekt.
```
python install -r requirements.txt
```

Konfigurieren von Umgebungsvariablen

Um die zuvor in diesem Schnellstart abgerufenen Werte von NAME und URI zu verwenden, speichern Sie sie in neuen Umgebungsvariablen auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird.

Um die Umgebungsvariable festzulegen, verwenden Sie Ihr Terminal, um die Werte als COSMOS_ENDPOINT bzw. COSMOS_KEY zu speichern.
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```
Überprüfen Sie, ob die Umgebungsvariablen richtig festgelegt wurden.
```
printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY
```

Der Code in diesem Artikel stellt eine Verbindung mit einer Datenbank namens cosmicworks und einem Graphen mit dem Namen products her. Der Code fügt dem Graphen dann Vertices und Kanten hinzu, bevor die hinzugefügten Elemente durchlaufen werden.

Authentifizieren des Clients

Anwendungsanforderungen an die meisten Azure-Dienste müssen autorisiert werden. Verwenden Sie für die API für Gremlin die Werte für NAME und URI, die Sie zuvor in dieser Schnellstartanleitung abgerufen haben.

Öffnen Sie die Datei app.py.
Importieren Sie client und serializer aus dem Modul gremlin_python.driver.
```
import os
from gremlin_python.driver import client, serializer
```
Warnung

Abhängig von Ihrer Python-Version müssen Sie möglicherweise auch asyncio importieren und die Ereignisschleifenrichtlinie außer Kraft setzen:
```
import asyncio
import sys

if sys.platform == "win32":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
```
Erstellen Sie die Variablen ACCOUNT_NAME und ACCOUNT_KEY. Speichern Sie die Umgebungsvariablen COSMOS_GREMLIN_ENDPOINT und COSMOS_GREMLIN_KEY als Werte für die jeweiligen Variablen.
```
ACCOUNT_NAME = os.environ["COSMOS_GREMLIN_ENDPOINT"]
ACCOUNT_KEY = os.environ["COSMOS_GREMLIN_KEY"]
```

Verwenden Sie Client, um unter Verwendung der Kontoanmeldeinformationen und des Serialisierungsmoduls GraphSON 2.0 eine Verbindung herzustellen.

client = client.Client(
    url=f"wss://{ACCOUNT_NAME}.gremlin.cosmos.azure.com:443/",
    traversal_source="g",
    username="/dbs/cosmicworks/colls/products",
    password=f"{ACCOUNT_KEY}",
    message_serializer=serializer.GraphSONSerializersV2d0(),
)

Erstellen von Vertices

Nachdem die Anwendung mit dem Konto verbunden wurde, verwenden Sie die Gremlin-Standardsyntax, um Vertices zu erstellen.

Verwenden Sie submit, um serverseitig einen Befehl für das API für Gremlin-Konto auszuführen. Erstellen Sie den Vertex product mit den folgenden Eigenschaften:

	Wert
label	`product`
id	`68719518371`
`name`	`Kiama classic surfboard`
`price`	`285.55`
`category`	`surfboards`

client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "prop_id": "68719518371",
        "prop_name": "Kiama classic surfboard",
        "prop_price": 285.55,
        "prop_partition_key": "surfboards",
    },
)

Erstellen Sie einen zweiten Vertex vom Typ product mit den folgenden Eigenschaften:

	Wert
label	`product`
id	`68719518403`
`name`	`Montau Turtle Surfboard`
`price`	`600.00`
`category`	`surfboards`

client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "prop_id": "68719518403",
        "prop_name": "Montau Turtle Surfboard",
        "prop_price": 600.00,
        "prop_partition_key": "surfboards",
    },
)

Erstellen Sie einen dritten Vertex vom Typ product mit den folgenden Eigenschaften:

	Wert
label	`product`
id	`68719518409`
`name`	`Bondi Twin Surfboard`
`price`	`585.50`
`category`	`surfboards`

client.submit(
    message=(
        "g.addV('product')"
        ".property('id', prop_id)"
        ".property('name', prop_name)"
        ".property('price', prop_price)"
        ".property('category', prop_partition_key)"
    ),
    bindings={
        "prop_id": "68719518409",
        "prop_name": "Bondi Twin Surfboard",
        "prop_price": 585.50,
        "prop_partition_key": "surfboards",
    },
)

Erstellen von Kanten

Erstellen Sie Kanten mithilfe der Gremlin-Syntax, um Beziehungen zwischen Vertices zu definieren.

Erstellen Sie zwischen dem Produkt Montau Turtle Surfboard und dem Produkt Kiama classic surfboard eine Kante mit dem Namen replaces.

client.submit(
    message=(
        "g.V([prop_partition_key, prop_source_id])"
        ".addE('replaces')"
        ".to(g.V([prop_partition_key, prop_target_id]))"
    ),
    bindings={
        "prop_partition_key": "surfboards",
        "prop_source_id": "68719518403",
        "prop_target_id": "68719518371",
    },
)

Tipp

Diese Kantendefinition verwendet die Syntax g.V(['<partition-key>', '<id>']). Alternativ können Sie g.V('<id>').has('category', '<partition-key>') verwenden.

Erstellen Sie eine weitere Kante vom Typ replaces zwischen demselben Produkt und Bondi Twin Surfboard.

client.submit(
    message=(
        "g.V([prop_partition_key, prop_source_id])"
        ".addE('replaces')"
        ".to(g.V([prop_partition_key, prop_target_id]))"
    ),
    bindings={
        "prop_partition_key": "surfboards",
        "prop_source_id": "68719518403",
        "prop_target_id": "68719518409",
    },
)

Abfragescheitelpunkte und Kanten

Verwenden Sie die Gremlin-Syntax, um den Graphen zu durchlaufen und Beziehungen zwischen Vertices zu ermitteln.

Durchlaufen Sie den Graphen, und suchen Sie alle Vertices, die durch Montau Turtle Surfboard ersetzt werden.

result = client.submit(
    message=(
        "g.V().hasLabel('product')"
        ".has('category', prop_partition_key)"
        ".has('name', prop_name)"
        ".outE('replaces').inV()"
    ),
    bindings={
        "prop_partition_key": "surfboards",
        "prop_name": "Montau Turtle Surfboard",
    },
)

Schreiben Sie das Ergebnis dieses Durchlaufs in die Konsole.
```
print(result)
```

Ausführen des Codes

Überprüfen Sie, ob Ihre Anwendung wie erwartet funktioniert, indem Sie die Anwendung ausführen. Die Anwendung sollte ohne Fehler oder Warnungen ausgeführt werden. Die Ausgabe der Anwendung enthält Daten zu den erstellten und abgefragten Elementen.

Öffnen Sie das Terminal im Python-Projektordner.
Verwenden Sie python <filename>, um die Anwendung auszuführen: Beachten Sie die Ausgabe der Anwendung:
```
python app.py
```

Bereinigen von Ressourcen

Wenn Sie das API für Gremlin-Konto nicht mehr benötigen, löschen Sie die entsprechende Ressourcengruppe.

Erstellen Sie eine Shell-Variable für resourceGroupName, wenn sie noch nicht vorhanden ist.
```
# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
```
Verwenden Sie az group delete, um die Ressourcengruppe zu löschen:
```
az group delete \
    --name $resourceGroupName
```

Nächster Schritt

Erstellen und Abfragen von Daten mithilfe von Azure Cosmos DB for Apache Gremlin