Quickstart: Azure Cosmos DB voor Apache Gremlin-bibliotheek voor .NET

VAN TOEPASSING OP: Gremlin

• Console
• Python
• Node.js
• .NET

Azure Cosmos DB voor Apache Gremlin is een volledig beheerde graafdatabaseservice die het populaire Apache Tinkerpop, een graafcomputingframework implementeert met behulp van de Gremlin-querytaal. De API voor Gremlin biedt u een lage wrijving manier om aan de slag te gaan met Gremlin met een service die zo veel mogelijk kan groeien en uitschalen als u nodig hebt met minimaal beheer.

In deze quickstart gebruikt u de Gremlin.Net bibliotheek om verbinding te maken met een zojuist gemaakt Azure Cosmos DB voor Gremlin-account.

Broncode van de bibliotheek | Pakket (NuGet)

Vereisten

• Een Azure-account met een actief abonnement.
  • Geen Azure-abonnement? Meld u aan voor een gratis Azure-account.
  • Wilt u geen Azure-abonnement? U kunt Azure Cosmos DB gratis proberen zonder dat u een abonnement nodig hebt.
• .NET (LTS)
  • Is .NET niet geïnstalleerd? Probeer deze quickstart in GitHub Codespaces.
• Azure-opdrachtregelinterface (CLI)

Azure Cloud Shell

Azure host Azure Cloud Shell, een interactieve shell-omgeving die u via uw browser kunt gebruiken. U kunt Bash of PowerShell gebruiken met Cloud Shell om met Azure-services te werken. U kunt de vooraf geïnstalleerde Cloud Shell-opdrachten gebruiken om de code in dit artikel uit te voeren zonder dat u iets hoeft te installeren in uw lokale omgeving.

Om Azure Cloud Shell op te starten:

Optie	Voorbeeld/koppeling
Selecteer Uitproberen in de rechterbovenhoek van een code- of opdrachtblok. Als u Try It selecteert, wordt de code of opdracht niet automatisch gekopieerd naar Cloud Shell.
Ga naar https://shell.azure.com, of selecteer de knop Cloud Shell starten om Cloud Shell in uw browser te openen.
Klik op de knop Cloud Shell in het menu in de balk rechtsboven in de Azure-portal.

Azure Cloud Shell gebruiken:

1. Start Cloud Shell.

2. Selecteer de knop Kopiëren op een codeblok (of opdrachtblok) om de code of opdracht te kopiëren.

3. Plak de code of opdracht in de Cloud Shell-sessie door Ctrl+Shift+V in Windows en Linux te selecteren of door Cmd+Shift+V te selecteren in macOS.

4. Selecteer Enter om de code of opdracht uit te voeren.

Instellen

In deze sectie wordt u begeleid bij het maken van een API voor een Gremlin-account en het instellen van een .NET-project om de bibliotheek te gebruiken om verbinding te maken met het account.

Een API voor Gremlin-account maken

De API voor het Gremlin-account moet worden gemaakt voordat u de .NET-bibliotheek gebruikt. Daarnaast helpt het ook om de database en grafiek op hun plaats te krijgen.

1. Maak shell-variabelen voor accountName, resourceGroupName en locatie.

   # 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"
   

2. Als u dat nog niet hebt gedaan, meldt u zich aan bij de Azure CLI met behulp van az login.

3. Hiermee az group create maakt u een nieuwe resourcegroep in uw abonnement.

   az group create \
       --name $resourceGroupName \
       --location $location
   

4. Hiermee az cosmosdb create maakt u een nieuwe API voor een Gremlin-account met standaardinstellingen.

   az cosmosdb create \
       --resource-group $resourceGroupName \
       --name $accountName \
       --capabilities "EnableGremlin" \
       --locations regionName=$location \
       --enable-free-tier true
   

   Notitie

   U kunt per Azure-abonnement maximaal één gratis laag voor het Azure Cosmos DB-account hebben, en u moet zich aanmelden wanneer u het account maakt. Als deze opdracht de korting op de gratis laag niet kan toepassen, betekent dit dat er al een ander account in het abonnement is ingeschakeld met de gratis laag.

5. Haal de API voor Gremlin-eindpuntNAAM op voor het account met behulp van az cosmosdb show.

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

6. Zoek de SLEUTEL in de lijst met sleutels voor het account met az-cosmosdb-keys-list.

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

7. Noteer de waarden NAME en KEY . U gebruikt deze referenties later.

8. Maak een database met de naam cosmicworks .az cosmosdb gremlin database create

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

9. Een grafiek maken met behulp van az cosmosdb gremlin graph create. Geef de grafiek productseen naam en stel vervolgens de doorvoer 400in op en stel ten slotte het pad naar de partitiesleutel in op /category.

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

Een nieuwe .NET-consoletoepassing maken

Maak een .NET-consoletoepassing in een lege map met behulp van uw favoriete terminal.

1. Open de terminal in een lege map.

2. Gebruik de dotnet new opdracht die de consolesjabloon opgeeft.

   dotnet new console
   

Installeer het NuGet-pakket van

Voeg het Gremlin.NET NuGet-pakket toe aan het .NET-project.

1. Gebruik de dotnet add package opdracht die het Gremlin.Net NuGet-pakket opgeeft.

   dotnet add package Gremlin.Net
   

2. Bouw het .NET-project met behulp van dotnet build.

   dotnet build
   

   Zorg ervoor dat de build zonder fouten is geslaagd. De verwachte uitvoer van de build moet er ongeveer als volgt uitzien:

   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)
   

Omgevingsvariabelen configureren

Als u de eerder in deze quickstart verkregen NAAM - en URI-waarden wilt gebruiken, moet u deze behouden tot nieuwe omgevingsvariabelen op de lokale computer waarop de toepassing wordt uitgevoerd.

1. Als u de omgevingsvariabele wilt instellen, gebruikt u de terminal om de waarden als COSMOS_ENDPOINT en COSMOS_KEY respectievelijk vast te houden.

   export COSMOS_GREMLIN_ENDPOINT="<account-name>"
   export COSMOS_GREMLIN_KEY="<account-key>"
   

2. Controleer of de omgevingsvariabelen juist zijn ingesteld.

   printenv COSMOS_GREMLIN_ENDPOINT
   printenv COSMOS_GREMLIN_KEY
   

Codevoorbeelden

• De client verifiëren
• Hoekpunten maken
• Randen maken
• Hoekpunten en randen van query's

De code in dit artikel maakt verbinding met een database met de naam cosmicworks en een grafiek met de naam products. De code voegt vervolgens hoekpunten en randen toe aan de grafiek voordat u de toegevoegde items doorkruist.

De client verifiëren

Toepassingsaanvragen voor de meeste Azure-services moeten worden geautoriseerd. Gebruik voor de API voor Gremlin de waarden NAME en URI die u eerder in deze quickstart hebt verkregen.

1. Open het Program.cs-bestand .

2. Verwijder alle bestaande inhoud in het bestand.

3. Voeg een using-blok toe voor de Gremlin.Net.Driver naamruimte.

   using Gremlin.Net.Driver;
   

4. Variabelen maken accountName en accountKey tekenreeksen maken. Sla de COSMOS_GREMLIN_ENDPOINT en COSMOS_GREMLIN_KEY omgevingsvariabelen op als de waarden voor elke respectieve variabele.

   string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
   string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
   

5. Maak een nieuw exemplaar van het gebruik van de referenties van GremlinServer het account.

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

6. Maak een nieuw exemplaar van het gebruik van de referenties van GremlinClient de externe server en de GraphSON 2.0-serializer .

   using var client = new GremlinClient(
       gremlinServer: server,
       messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
   );
   

Hoekpunten maken

Nu de toepassing is verbonden met het account, gebruikt u de standaard Gremlin-syntaxis om hoekpunten te maken.

1. Gebruik SubmitAsync dit om een opdrachtserverzijde uit te voeren op de API voor het Gremlin-account. Maak een productpunt met de volgende eigenschappen:

   	Waarde
   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')"
   );
   

2. Maak een tweede productpunt met de volgende eigenschappen:

   	Waarde
   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')"
   );
   

3. Maak een derde productpunt met de volgende eigenschappen:

   	Waarde
   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')"
   );
   

Randen maken

Maak randen met behulp van de Gremlin-syntaxis om relaties tussen hoekpunten te definiëren.

1. Maak een rand van het product met de Montau Turtle Surfboard naam vervangt door het Kiama classic surfboard product.

   await client.SubmitAsync(
       requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))"
   );
   

   Tip

   Deze randaffintion maakt gebruik van de g.V(['<partition-key>', '<id>']) syntaxis. U kunt g.V('<id>').has('category', '<partition-key>')ook .

2. Als u een andere rand maakt, vervangt u de rand van hetzelfde product in het Bondi Twin Surfboard.

   await client.SubmitAsync(
       requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518409']))"
   );
   

Hoekpunten en randen van query's

Gebruik de Gremlin-syntaxis om de grafiek te doorlopen en relaties tussen hoekpunten te ontdekken.

1. Ga door de grafiek en zoek alle hoekpunten die Montau Turtle Surfboard worden vervangen.

   var results = await client.SubmitAsync<Dictionary<string, object>>(
       requestScript: "g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()"
   );
   

2. Schrijf naar de console met de statische tekenreeks [CREATED PRODUCT]\t68719518403. Herhaal vervolgens elk overeenkomend hoekpunt met behulp van een foreach lus en schrijf naar de console een bericht dat begint met [REPLACES PRODUCT] en het overeenkomende productveld id als achtervoegsel bevat.

   Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
   foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
   {
       Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
   }
   

De code uitvoeren

Controleer of uw toepassing werkt zoals verwacht door de toepassing uit te voeren. De toepassing moet zonder fouten of waarschuwingen worden uitgevoerd. De uitvoer van de toepassing bevat gegevens over de gemaakte en opgevraagde items.

1. Open de terminal in de .NET-projectmap.

2. Gebruik dotnet run dit om de toepassing uit te voeren.

   dotnet run
   

3. Bekijk de uitvoer van de toepassing.

   [CREATED PRODUCT]       68719518403
   [REPLACES PRODUCT]      68719518371
   [REPLACES PRODUCT]      68719518409
   

Resources opschonen

Wanneer u de API voor het Gremlin-account niet meer nodig hebt, verwijdert u de bijbehorende resourcegroep.

1. Maak een shellvariabele voor resourceGroupName als deze nog niet bestaat.

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

2. Gebruik az group delete dit om de resourcegroep te verwijderen.

   az group delete \
       --name $resourceGroupName
   

Volgende stap

Gegevens maken en er query's op uitvoeren met Behulp van Azure Cosmos DB voor Apache Gremlin