Snabbstart: Azure Cosmos DB för Apache Gremlin-biblioteket för .NET

GÄLLER FÖR: Gremlin

• Konsol
• Python
• Node.js
• .NET

Azure Cosmos DB för Apache Gremlin är en fullständigt hanterad grafdatabastjänst som implementerar det populära Apache Tinkerpop, ett diagramberäkningsramverk med hjälp av Gremlin-frågespråket. API:et för Gremlin ger dig ett sätt att komma igång med gremlin med en tjänst som kan växa och skalas ut så mycket du behöver med minimal hantering.

I den här snabbstarten Gremlin.Net använder du biblioteket för att ansluta till ett nyligen skapat Azure Cosmos DB för Gremlin-konto.

Bibliotekets källkodspaket | (NuGet)

Förutsättningar

• Ett Azure-konto med en aktiv prenumeration.
  • Ingen Azure-prenumeration? Registrera dig för ett kostnadsfritt Azure-konto.
  • Vill du inte ha en Azure-prenumeration? Du kan prova Azure Cosmos DB kostnadsfritt utan att någon prenumeration krävs.
• .NET (LTS)
  • Har du inte installerat .NET? Prova den här snabbstarten i GitHub Codespaces.
• Kommandoradsgränssnitt för Azure (CLI)

Azure Cloud Shell

Azure är värd för Azure Cloud Shell, en interaktiv gränssnittsmiljö som du kan använda via webbläsaren. Du kan använda antingen Bash eller PowerShell med Cloud Shell för att arbeta med Azure-tjänster. Du kan använda förinstallerade Cloud Shell-kommandon för att köra koden i den här artikeln, utan att behöva installera något i din lokala miljö.

Så här startar du Azure Cloud Shell:

Alternativ	Exempel/länk
Välj Prova i det övre högra hörnet i en kod eller ett kommandoblock. Om du väljer Prova kopieras inte koden eller kommandot automatiskt till Cloud Shell.
Gå till https://shell.azure.com eller Välj knappen Starta Cloud Shell för att öppna Cloud Shell i webbläsaren.
Välj knappen Cloud Shell på menyn längst upp till höger i Azure-portalen.

Så här använder du Azure Cloud Shell:

1. Starta Cloud Shell.

2. Välj knappen Kopiera i ett kodblock (eller kommandoblock) för att kopiera koden eller kommandot.

3. Klistra in koden eller kommandot i Cloud Shell-sessionen genom att välja Ctrl+Skift+V i Windows och Linux, eller genom att välja Cmd+Shift+V på macOS.

4. Välj Retur för att köra koden eller kommandot.

Konfigurera

Det här avsnittet beskriver hur du skapar ett API för Gremlin-konto och konfigurerar ett .NET-projekt för att använda biblioteket för att ansluta till kontot.

Skapa ett API för Gremlin-konto

API:et för Gremlin-kontot ska skapas innan du använder .NET-biblioteket. Dessutom hjälper det att även ha databasen och grafen på plats.

1. Skapa gränssnittsvariabler för accountName, resourceGroupName och plats.

   # 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. Om du inte redan har gjort det loggar du in på Azure CLI med .az login

3. Använd az group create för att skapa en ny resursgrupp i din prenumeration.

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

4. Använd az cosmosdb create för att skapa ett nytt API för Gremlin-konto med standardinställningar.

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

   Kommentar

   Du kan högst ha ett Azure Cosmos DB-konto med kostnadsfri nivå per Azure-prenumeration och du måste välja det när du skapar kontot. Om det här kommandot inte kan tillämpa rabatten på den kostnadsfria nivån innebär det att ett annat konto i prenumerationen redan har aktiverats med den kostnadsfria nivån.

5. Hämta API:et för Gremlin-slutpunktens NAMN för kontot med hjälp av az cosmosdb show.

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

6. Hitta nyckeln i listan med nycklar för kontot med az-cosmosdb-keys-list.

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

7. Registrera värdena NAME och KEY. Du använder dessa autentiseringsuppgifter senare.

8. Skapa en databas med namnet cosmicworks med .az cosmosdb gremlin database create

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

9. Skapa en graf med hjälp av az cosmosdb gremlin graph create. Namnge grafen productsoch ange sedan dataflödet till 400och ställ slutligen in partitionsnyckelsökvägen till /category.

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

Skapa ett nytt .NET-konsolprogram

Skapa ett .NET-konsolprogram i en tom mapp med hjälp av önskad terminal.

1. Öppna terminalen i en tom mapp.

2. Använd kommandot dotnet new som anger konsolmallen.

   dotnet new console
   

Installera NuGet-paketet

Gremlin.NET Lägg till NuGet-paketet i .NET-projektet.

1. dotnet add package Använd kommandot som Gremlin.Net anger NuGet-paketet.

   dotnet add package Gremlin.Net
   

2. Skapa .NET-projektet med .dotnet build

   dotnet build
   

   Kontrollera att bygget lyckades utan fel. Förväntade utdata från bygget bör se ut ungefär så här:

   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)
   

Konfigurera miljövariabler

Om du vill använda de NAMN- och URI-värden som hämtades tidigare i den här snabbstarten sparar du dem i nya miljövariabler på den lokala dator som kör programmet.

1. Om du vill ange miljövariabeln använder du terminalen för att spara värdena som COSMOS_ENDPOINT respektive COSMOS_KEY .

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

2. Kontrollera att miljövariablerna har angetts korrekt.

   printenv COSMOS_GREMLIN_ENDPOINT
   printenv COSMOS_GREMLIN_KEY
   

Kodexempel

• Autentisera klienten
• Skapa hörn
• Skapa kanter
• Frågehörn och kanter

Koden i den här artikeln ansluter till en databas med namnet cosmicworks och ett diagram med namnet products. Koden lägger sedan till hörn och kanter i diagrammet innan du går igenom de tillagda objekten.

Autentisera klienten

Programbegäranden till de flesta Azure-tjänster måste auktoriseras. För API:et för Gremlin använder du de NAME- och URI-värden som hämtades tidigare i den här snabbstarten.

1. Öppna filen Program.cs .

2. Ta bort befintligt innehåll i filen.

3. Lägg till ett användningsblock för Gremlin.Net.Driver namnområdet.

   using Gremlin.Net.Driver;
   

4. Skapa accountName och accountKey strängvariabler. COSMOS_GREMLIN_ENDPOINT Lagra miljövariablerna och COSMOS_GREMLIN_KEY som värden för varje variabel.

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

5. Skapa en ny instans av GremlinServer med kontots autentiseringsuppgifter.

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

6. Skapa en ny instans av GremlinClient att använda fjärrserverns autentiseringsuppgifter och GraphSON 2.0-serialiseraren.

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

Skapa hörn

Nu när programmet är anslutet till kontot använder du Gremlin-standardsyntaxen för att skapa hörn.

1. Använd SubmitAsync för att köra en kommandoserversida på API:et för Gremlin-kontot. Skapa ett produkthörn med följande egenskaper:

   	Värde
   etikett	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. Skapa ett andra produkthörn med följande egenskaper:

   	Värde
   etikett	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. Skapa ett tredje produkthörn med följande egenskaper:

   	Värde
   etikett	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')"
   );
   

Skapa kanter

Skapa kanter med Gremlin-syntaxen för att definiera relationer mellan hörn.

1. Skapa en kant från produkten Montau Turtle Surfboard med namnet ersätter produkten Kiama classic surfboard .

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

   Dricks

   Den här gränsdefiniering använder syntaxen g.V(['<partition-key>', '<id>']) . Du kan också använda g.V('<id>').has('category', '<partition-key>').

2. Skapa en annan ersätter gränsen från samma produkt till Bondi Twin Surfboard.

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

Frågehörn och kanter

Använd Gremlin-syntaxen för att bläddra i diagrammet och identifiera relationer mellan hörn.

1. Bläddra i grafen och leta reda på alla hörn som Montau Turtle Surfboard ersätter.

   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. Skriv till konsolen den statiska strängen [CREATED PRODUCT]\t68719518403. Iterera sedan över varje matchande hörn med hjälp av en foreach loop och skriv till konsolen ett meddelande som börjar med [REPLACES PRODUCT] och innehåller det matchande produktfältet id som ett suffix.

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

Kör koden

Kontrollera att programmet fungerar som förväntat genom att köra programmet. Programmet ska köras utan fel eller varningar. Programmets utdata innehåller data om de skapade och efterfrågade objekten.

1. Öppna terminalen i .NET-projektmappen.

2. Använd dotnet run för att köra programmet.

   dotnet run
   

3. Observera utdata från programmet.

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

Rensa resurser

När du inte längre behöver API:et för Gremlin-kontot tar du bort motsvarande resursgrupp.

1. Skapa en gränssnittsvariabel för resourceGroupName om den inte redan finns.

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

2. Använd az group delete för att ta bort resursgruppen.

   az group delete \
       --name $resourceGroupName
   

Gå vidare

Skapa och fråga efter data med Hjälp av Azure Cosmos DB för Apache Gremlin