Schnellstart: Azure Cosmos DB für Apache Gremlin-Clientbibliothek für .NET

Erste Schritte mit der Azure Cosmos DB für Apache Gremlin-Clientbibliothek für .NET zum Speichern, Verwalten und Abfragen unstrukturierter Daten. Führen Sie die Schritte in diesem Handbuch aus, um ein neues Konto zu erstellen, eine .NET-Clientbibliothek zu installieren, eine Verbindung mit dem Konto herzustellen, allgemeine Vorgänge auszuführen und ihre endgültigen Beispieldaten abzufragen.

Quellcode der Bibliothek | Paket (NuGet)

Voraussetzungen

• Ein Azure-Abonnement

  • Wenn Sie noch kein Azure-Abonnement haben, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.

• Die neueste Version der Azure CLI in Azure Cloud Shell.

  • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen möchten, melden Sie sich mit dem az login Befehl bei der Azure CLI an.

• .NET SDK 9.0 oder höher

Einrichten

Richten Sie zunächst die Konto- und Entwicklungsumgebung für diesen Leitfaden ein. In diesem Abschnitt erfahren Sie, wie Sie ein Konto erstellen, die Anmeldeinformationen des Kontos abrufen und Ihre Entwicklungsumgebung vorbereiten.

Erstellen eines Kontos

Erstellen Sie zunächst eine API für Apache Gremlin-Konto. Nachdem das Konto erstellt wurde, erstellen Sie die Datenbank- und Diagrammressourcen.

Abrufen von Anmeldeinformationen

Rufen Sie nun das Kennwort für die Clientbibliothek ab, um eine Verbindung mit dem vor Kurzem erstellten Konto herzustellen.

Vorbereiten der Entwicklungsumgebung

Konfigurieren Sie dann Ihre Entwicklungsumgebung mit einem neuen Projekt und der Clientbibliothek. Dieser Schritt ist die letzte erforderliche Voraussetzung, bevor Sie mit dem Rest dieses Handbuchs fortfahren.

1. Starten Sie in einem leeren Ordner.

2. Erstellen einer neuen .NET-Konsolenanwendung

   dotnet new console
   

3. Importieren Sie das Gremlin.Net Paket aus NuGet.

   dotnet add package Gremlin.Net
   

4. Projekt erstellen.

   dotnet build
   

Objektmodell

Codebeispiele

• Authentifizieren des Clients
• Einfügen von Daten
• Lesen von Daten
• Abfragedaten

Authentifizieren des Clients

Beginnen Sie damit, den Client mithilfe der Anmeldeinformationen zu authentifizieren, die zuvor in diesem Handbuch gesammelt wurden.

1. Öffnen Sie die datei Program.cs in Ihrer integrierten Entwicklungsumgebung (IDE).

2. Löschen Sie alle vorhandenen Inhalte in der Datei.

3. Fügen Sie mithilfe von Direktiven für die folgenden Namespaces hinzu:

   • Gremlin.Net.Driver
   • Gremlin.Net.Structure.IO.GraphSON

   using Gremlin.Net.Driver;
   using Gremlin.Net.Structure.IO.GraphSON;
   

4. Erstellen Sie String-Variablen für die zuvor in diesem Handbuch gesammelten Anmeldeinformationen. Benennen Sie die Variablen hostname und primaryKey.

   string hostname = "<host>";
   string primaryKey = "<key>";
   

5. Erstellen Sie eine GremlinServer mit den Anmeldeinformationen und Konfigurationsvariablen, die in den vorherigen Schritten erstellt wurden. Geben Sie der Variablen den Namen server.

   GremlinServer server = new(
       $"{hostname}.gremlin.cosmos.azure.com",
       443,
       enableSsl: true,
       username: "/dbs/cosmicworks/colls/products",
       password: primaryKey
   );
   

6. Erstellen Sie nun eine GremlinClient, indem Sie die server-Variable und die GraphSON2MessageSerializer-Konfiguration verwenden.

   GremlinClient client = new(
       server,
       new GraphSON2MessageSerializer()
   );
   

Einfügen von Daten

Fügen Sie als Nächstes neue Vertex- und Randdaten in das Diagramm ein. Löschen Sie vor dem Erstellen der neuen Daten das Diagramm aller vorhandenen Daten.

1. Führen Sie die g.V().drop() Abfrage aus, um alle Scheitelpunkte und Kanten aus dem Diagramm zu löschen.

   await client.SubmitAsync("g.V().drop()");
   

2. Erstellen Sie eine Gremlin-Abfrage, die einen Scheitelpunkt hinzufügt.

   string insertVertexQuery = """
       g.addV('product')
           .property('id', prop_id)
           .property('name', prop_name)
           .property('category', prop_category)
           .property('quantity', prop_quantity)
           .property('price', prop_price)
           .property('clearance', prop_clearance)
   """;
   

3. Fügen Sie einen Scheitelpunkt für ein einzelnes Produkt hinzu.

   await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       ["prop_name"] = "Yamba Surfboard",
       ["prop_category"] = "gear-surf-surfboards",
       ["prop_quantity"] = 12,
       ["prop_price"] = 850.00,
       ["prop_clearance"] = false
   });
   

4. Fügen Sie zwei weitere Scheitelpunkte für zwei zusätzliche Produkte hinzu.

   await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["prop_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_name"] = "Montau Turtle Surfboard",
       ["prop_category"] = "gear-surf-surfboards",
       ["prop_quantity"] = 5,
       ["prop_price"] = 600.00,
       ["prop_clearance"] = true
   });
   
   await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
   {
       ["prop_id"] = "cccccccc-2222-3333-4444-dddddddddddd",
       ["prop_name"] = "Noosa Surfboard",
       ["prop_category"] = "gear-surf-surfboards",
       ["prop_quantity"] = 31,
       ["prop_price"] = 1100.00,
       ["prop_clearance"] = false
   });
   

5. Erstellen Sie eine weitere Gremlin-Abfrage, die einen Rand hinzufügt.

   string insertEdgeQuery = """
       g.V([prop_partition_key, prop_source_id])
           .addE('replaces')
           .to(g.V([prop_partition_key, prop_target_id]))
   """;
   

6. Fügen Sie zwei Kanten hinzu.

   await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_target_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
   });
   
   await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
       ["prop_target_id"] = "cccccccc-2222-3333-4444-dddddddddddd"
   });
   

Daten lesen

Lesen Sie dann Daten, die zuvor in das Diagramm eingefügt wurden.

1. Erstellen Sie eine Abfrage, die einen Scheitelpunkt mithilfe des eindeutigen Bezeichners und des Partitionsschlüsselwerts liest.

   string readVertexQuery = "g.V([prop_partition_key, prop_id])";
   

2. Lesen Sie dann einen Scheitelpunkt, indem Sie die erforderlichen Parameter angeben.

   ResultSet<Dictionary<string, object>> readResults = await client.SubmitAsync<Dictionary<string, object>>(readVertexQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
   });
   
   Dictionary<string, object> matchedItem = readResults.Single();
   

Abfragedaten

Verwenden Sie schließlich eine Abfrage, um alle Daten zu finden, die einem bestimmten Traversal oder Filter im Diagramm entsprechen.

1. Erstellen Sie eine Abfrage, die alle Scheitelpunkte findet, die von einem bestimmten Scheitelpunkt aus durchlaufen werden.

   string findVerticesQuery = """
       g.V().hasLabel('product')
           .has('category', prop_partition_key)
           .has('name', prop_name)
           .outE('replaces').inV()
   """;
   

2. Führen Sie die Abfrage aus, die das Montau Turtle Surfboard Produkt angibt.

   ResultSet<Dictionary<string, object>> findResults = await client.SubmitAsync<Dictionary<string, object>>(findVerticesQuery, new Dictionary<string, object>
   {
       ["prop_partition_key"] = "gear-surf-surfboards",
       ["prop_name"] = "Montau Turtle Surfboard"
   });
   

3. Iterieren Sie über die Abfrageergebnisse.

   foreach (Dictionary<string, object> result in findResults)
   {
       // Do something here with each result
   }
   

Ausführen des Codes

Führen Sie die neu erstellte Anwendung mit einem Terminal in Ihrem Anwendungsverzeichnis aus.

dotnet run

Bereinigen von Ressourcen

Wenn Sie das Konto nicht mehr benötigen, entfernen Sie das Konto aus Ihrem Azure-Abonnement, indem Sie die Ressource löschen .

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"