Schnellstart: Azure Cosmos DB for Apache Gremlin-Bibliothek für .NET
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 Gremlin.Net
-Bibliothek, um eine Verbindung mit einem neu erstellten Azure Cosmos DB for Gremlin-Konto herzustellen.
Quellcode der Bibliothek | Paket (NuGet)
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.
- .NET (LTS)
- Sie haben .NET 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 .NET-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 .NET-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 Bezeichnungcosmicworks
: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 Graphenproducts
, und legen Sie den Durchsatz auf400
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 .NET-Konsolenanwendung
Erstellen Sie mithilfe Ihres bevorzugten Terminals in einem leeren Ordner eine .NET-Konsolenanwendung.
Öffnen Sie Ihr Terminal in einem leeren Ordner.
Verwenden Sie den Befehl
dotnet new
, der die Vorlage Console angibt.dotnet new console
Installieren des NuGet-Pakets
Fügen Sie dem .NET-Projekt das NuGet-Paket Gremlin.NET
hinzu.
Verwenden Sie den
dotnet add package
-Befehl, der das NuGet-PaketGremlin.Net
angibt.dotnet add package Gremlin.Net
Erstellen Sie das .NET-Projekt mithilfe von
dotnet build
.dotnet build
Stellen Sie sicher, dass der Build ohne Fehler erfolgreich war. Die erwartete Ausgabe aus dem Build sollte etwa wie folgt aussehen:
Determining projects to restore... All projects are up-to-date for restore. dslkajfjlksd -> \dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll Build succeeded. 0 Warning(s) 0 Error(s)
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
Codebeispiele
- Authentifizieren des Clients
- Erstellen von Vertices
- Erstellen von Kanten
- Abfragescheitelpunkte und Kanten
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 Program.cs.
Löschen Sie alle vorhandenen Inhalte in der Datei.
Fügen Sie einen using-Block für den
Gremlin.Net.Driver
-Namespace hinzu.using Gremlin.Net.Driver;
Erstellen Sie die Zeichenfolgenvariablen
accountName
undaccountKey
. Speichern Sie die UmgebungsvariablenCOSMOS_GREMLIN_ENDPOINT
undCOSMOS_GREMLIN_KEY
als Werte für die jeweiligen Variablen.string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!; string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
Erstellen Sie unter Verwendung der Anmeldeinformationen des Kontos eine neue Instanz von
GremlinServer
.var server = new GremlinServer( hostname: $"{accountName}.gremlin.cosmos.azure.com", port: 443, username: "/dbs/cosmicworks/colls/products", password: $"{accountKey}", enableSsl: true );
Erstellen Sie unter Verwendung der Remoteserveranmeldeinformationen und des Serialisierungsmoduls GraphSON 2.0 eine neue Instanz von
GremlinClient
.using var client = new GremlinClient( gremlinServer: server, messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer() );
Erstellen von Vertices
Nachdem die Anwendung mit dem Konto verbunden wurde, verwenden Sie die Gremlin-Standardsyntax, um Vertices zu erstellen.
Verwenden Sie
SubmitAsync
, 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
await client.SubmitAsync( requestScript: "g.addV('product').property('id', '68719518371').property('name', 'Kiama classic surfboard').property('price', 285.55).property('category', '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
await client.SubmitAsync( requestScript: "g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600.00).property('category', '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
await client.SubmitAsync( requestScript: "g.addV('product').property('id', '68719518409').property('name', 'Bondi Twin Surfboard').property('price', 585.50).property('category', '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 ProduktKiama classic surfboard
eine Kante mit dem Namen replaces.await client.SubmitAsync( requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))" );
Tipp
Diese Kantendefinition verwendet die Syntax
g.V(['<partition-key>', '<id>'])
. Alternativ können Sieg.V('<id>').has('category', '<partition-key>')
verwenden.Erstellen Sie eine weitere Kante vom Typ replaces zwischen demselben Produkt und
Bondi Twin Surfboard
.await client.SubmitAsync( requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '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.var results = await client.SubmitAsync<Dictionary<string, object>>( requestScript: "g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()" );
Schreiben Sie die statische Zeichenfolge
[CREATED PRODUCT]\t68719518403
in die Konsole. Durchlaufen Sie dann alle übereinstimmenden Vertices mithilfe einerforeach
-Schleife, und schreiben Sie eine Nachricht in die Konsole, die mit[REPLACES PRODUCT]
beginnt und das übereinstimmende Produktfeldid
als Suffix enthält.Console.WriteLine($"[CREATED PRODUCT]\t68719518403"); foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>()) { Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}"); }
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 .NET-Projektordner.
Verwenden Sie
dotnet run
, um die Anwendung auszuführen:dotnet run
Beachten Sie die Ausgabe der Anwendung:
[CREATED PRODUCT] 68719518403 [REPLACES PRODUCT] 68719518371 [REPLACES PRODUCT] 68719518409
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