Rychlý start: Knihovna Azure Cosmos DB pro Apache Gremlin pro .NET

Článek
08/15/2024

PLATÍ PRO: Skřítek

Azure Cosmos DB pro Apache Gremlin je plně spravovaná databázová služba grafů, která implementuje oblíbenou Apache Tinkerpoparchitekturu grafových výpočtů pomocí dotazovacího jazyka Gremlin. Rozhraní API pro Gremlin poskytuje rychlý způsob, jak začít používat Gremlin se službou, která může růst a škálovat podle potřeby s minimální správou.

V tomto rychlém startu Gremlin.Net se pomocí knihovny připojíte k nově vytvořenému účtu Azure Cosmos DB pro Gremlin.

Balíček zdrojového kódu | knihovny (NuGet)

Požadavky

Účet Azure s aktivním předplatným.
- Žádné předplatné Azure? Zaregistrujte si bezplatný účet Azure.
- Nechcete předplatné Azure? Službu Azure Cosmos DB můžete vyzkoušet zdarma bez nutnosti předplatného.
.NET (LTS)
- Nemáte nainstalovaný .NET? Vyzkoušejte tento rychlý start v GitHub Codespaces.
Rozhraní příkazového řádku Azure (CLI)

Azure Cloud Shell

Azure hostí interaktivní prostředí Azure Cloud Shell, které můžete používat v prohlížeči. Pro práci se službami Azure můžete v prostředí Cloud Shell použít buď Bash, nebo PowerShell. Předinstalované příkazy Cloud Shellu můžete použít ke spuštění kódu v tomto článku, aniž byste museli instalovat cokoli do místního prostředí.

Spuštění služby Azure Cloud Shell:

Možnost	Příklad nebo odkaz
Vyberte Vyzkoušet v pravém horním rohu bloku kódu nebo příkazu. Výběrem možnosti Vyzkoušet se kód ani příkaz automaticky nekopíruje do Cloud Shellu.
Přejděte na adresu https://shell.azure.com nebo výběrem tlačítka Spustit Cloud Shell otevřete Cloud Shell v prohlížeči.
Zvolte tlačítko Cloud Shell v pruhu nabídky v pravém horním rohu webu Azure Portal.

Použití Azure Cloud Shellu:

Spusťte Cloud Shell.
Výběrem tlačítka Kopírovat v bloku kódu (nebo bloku příkazů) zkopírujte kód nebo příkaz.
Vložte kód nebo příkaz do relace Cloud Shellu tak, že ve Windows a Linuxu vyberete ctrl+Shift+V nebo vyberete Cmd+Shift+V v macOS.
Stisknutím klávesy Enter spusťte kód nebo příkaz.

Nastavení

Tato část vás provede vytvořením rozhraní API pro účet Gremlin a nastavením projektu .NET pro připojení k účtu pomocí knihovny.

Vytvoření rozhraní API pro účet Gremlin

Rozhraní API pro účet Gremlin by se mělo vytvořit před použitím knihovny .NET. Kromě toho pomáhá mít také databázi a graf na místě.

Vytvořte proměnné prostředí pro accountName, resourceGroupName a umístění.

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

Pokud jste to ještě neudělali, přihlaste se k Azure CLI pomocí az login.
Slouží az group create k vytvoření nové skupiny prostředků ve vašem předplatném.
```
az group create \
    --name $resourceGroupName \
    --location $location
```
Slouží az cosmosdb create k vytvoření nového rozhraní API pro účet Gremlin s výchozím nastavením.
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
Poznámka:

Pro každé předplatné Azure můžete mít maximálně jeden účet Azure Cosmos DB úrovně Free a při vytváření tohoto účtu se musíte přihlásit. Pokud se tomuto příkazu nepodaří uplatnit slevu na úroveň Free, znamená to, že u úrovně Free už byl povolený jiný účet v předplatném.

Získejte rozhraní API pro název koncového bodu Gremlin pro účet pomocí az cosmosdb show.

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

Najděte klíč ze seznamu klíčů pro účet pomocí az-cosmosdb-keys-list.

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

Poznamenejte si hodnoty NAME a KEY . Tyto přihlašovací údaje použijete později.

Vytvořte databázi s názvem cosmicworks using az cosmosdb gremlin database create.

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

Vytvoření grafu pomocí az cosmosdb gremlin graph create. Pojmenujte graf products, nastavte propustnost 400na a nakonec nastavte cestu ke klíči oddílu na /categoryhodnotu .

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

Vytvoření nové konzolové aplikace .NET

Pomocí upřednostňovaného terminálu vytvořte konzolovou aplikaci .NET v prázdné složce.

Otevřete terminál v prázdné složce.
dotnet new Použijte příkaz určující šablonu konzoly.
```
dotnet new console
```

Instalace balíčku NuGet

Gremlin.NET Přidejte balíček NuGet do projektu .NET.

dotnet add package Použijte příkaz určující Gremlin.Net balíček NuGet.
```
dotnet add package Gremlin.Net
```

Sestavení projektu .NET pomocí dotnet build.

dotnet build

Ujistěte se, že sestavení proběhlo úspěšně bez chyb. Očekávaný výstup sestavení by měl vypadat přibližně takto:

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)

Konfigurace proměnných prostředí

Pokud chcete použít hodnoty NAME a URI získané dříve v tomto rychlém startu, zachovají se do nových proměnných prostředí na místním počítači, na kterém běží aplikace.

Pokud chcete nastavit proměnnou prostředí, použijte terminál k uchování hodnot jako COSMOS_ENDPOINT a COSMOS_KEY v uvedeném pořadí.
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```

Ověřte, že proměnné prostředí byly správně nastaveny.

printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY

Kód v tomto článku se připojí k databázi pojmenované cosmicworks a grafu s názvem products. Kód pak přidá vrcholy a hrany do grafu před procházením přidaných položek.

Ověření klienta

Žádosti o aplikace na většinu služeb Azure musí být autorizované. Pro rozhraní API pro Gremlin použijte hodnoty NAME a URI získané dříve v tomto rychlém startu.

Otevřete soubor Program.cs.
Odstraňte veškerý existující obsah v souboru.
Přidejte blok using pro Gremlin.Net.Driver obor názvů.
```
using Gremlin.Net.Driver;
```
Vytváření accountName a accountKey řetězcové proměnné COSMOS_GREMLIN_ENDPOINT Uložte proměnné prostředí a COSMOS_GREMLIN_KEY proměnné prostředí jako hodnoty pro každou příslušnou proměnnou.
```
string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
```

Vytvořte novou instanci s použitím přihlašovacích GremlinServer údajů účtu.

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

Vytvořte novou instanci pomocí přihlašovacích údajů vzdáleného GremlinClient serveru a serializátoru GraphSON 2.0 .

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

Vytváření vrcholů

Teď, když je aplikace připojená k účtu, použijte k vytvoření vrcholů standardní syntaxi Gremlin.

Slouží SubmitAsync ke spuštění příkazového serveru na straně rozhraní API pro účet Gremlin. Vytvořte vrchol produktu s následujícími vlastnostmi:

Hodnota

označit 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')"
);
```

Vytvořte druhý vrchol produktu s těmito vlastnostmi:

	Hodnota
označit	`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')"
);

Vytvořte třetí vrchol produktu s těmito vlastnostmi:

	Hodnota
označit	`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')"
);

Vytvoření okrajů

Vytvořte hrany pomocí syntaxe Gremlin k definování relací mezi vrcholy.

Vytvořte hranu z Montau Turtle Surfboard produktu s názvem nahradit produktem Kiama classic surfboard .
```
await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))"
);
```
Tip

Toto definování hrany používá g.V(['<partition-key>', '<id>']) syntaxi. Alternativně můžete použít g.V('<id>').has('category', '<partition-key>').

Vytvořte další hranu ze stejného produktu do objektu Bondi Twin Surfboard.

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

Vrcholy dotazů a hrany

Pomocí syntaxe Gremlin můžete procházet graf a zjišťovat vztahy mezi vrcholy.

Projděte graf a najděte všechny vrcholy, které Montau Turtle Surfboard nahradí.

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

Zapište do konzoly statický řetězec [CREATED PRODUCT]\t68719518403. Potom iterujte přes každý odpovídající vrchol pomocí foreach smyčky a zapište do konzoly zprávu, která začíná [REPLACES PRODUCT] a obsahuje odpovídající pole produktu id jako příponu.
```
Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
{
    Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
}
```

Spuštění kódu

Spuštěním aplikace ověřte, že aplikace funguje podle očekávání. Aplikace by se měla spouštět bez chyb nebo upozornění. Výstup aplikace obsahuje data o vytvořených a dotazovaných položkách.

Otevřete terminál ve složce projektu .NET.
Slouží dotnet run ke spuštění aplikace.
```
dotnet run
```

Sledujte výstup z aplikace.

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

Vyčištění prostředků

Pokud už rozhraní API pro účet Gremlin nepotřebujete, odstraňte odpovídající skupinu prostředků.

Vytvořte proměnnou prostředí pro resourceGroupName , pokud ještě neexistuje.

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

Slouží az group delete k odstranění skupiny prostředků.
```
az group delete \
    --name $resourceGroupName
```

Další krok

Vytváření a dotazování dat pomocí služby Azure Cosmos DB pro Apache Gremlin

Sdílet prostřednictvím