Szybki start: biblioteka Azure Cosmos DB dla języka Apache Gremlin dla platformy .NET

Artykuł
08/15/2024

DOTYCZY: Gremlin

Azure Cosmos DB for Apache Gremlin to w pełni zarządzana usługa bazy danych grafów, która implementuje popularną Apache Tinkerpopplatformę obliczeniową grafu przy użyciu języka zapytań Gremlin. Interfejs API dla języka Gremlin umożliwia rozpoczęcie pracy z językiem Gremlin z usługą, która może rozwijać się i skalować w poziomie tak samo, jak w przypadku minimalnego zarządzania.

W tym przewodniku Gremlin.Net Szybki start użyjesz biblioteki do nawiązania połączenia z nowo utworzonym kontem usługi Azure Cosmos DB dla języka Gremlin.

Pakiet kodu | źródłowego biblioteki (NuGet)

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją.
- Brak subskrypcji platformy Azure? Utwórz bezpłatne konto platformy Azure.
- Nie chcesz subskrypcji platformy Azure? Możesz wypróbować usługę Azure Cosmos DB bezpłatnie bez konieczności korzystania z subskrypcji.
.NET (LTS)
- Nie masz zainstalowanego programu .NET? Wypróbuj ten przewodnik Szybki start w usłudze GitHub Codespaces.
Interfejs wiersza polecenia platformy Azure

Azure Cloud Shell

Na platforma Azure hostowane jest Azure Cloud Shell, interaktywne środowisko powłoki, z którego można korzystać w przeglądarce. Do pracy z usługami platformy Azure można używać programu Bash lub PowerShell w środowisku Cloud Shell. Aby uruchomić kod w tym artykule, możesz użyć wstępnie zainstalowanych poleceń usługi Cloud Shell bez konieczności instalowania niczego w środowisku lokalnym.

Aby uruchomić środowisko Azure Cloud Shell:

Opcja	Przykład/link
Wybierz pozycję Wypróbuj w prawym górnym rogu bloku kodu lub polecenia. Wybranie pozycji Wypróbuj nie powoduje automatycznego skopiowania kodu lub polecenia do usługi Cloud Shell.
Przejdź do witryny https://shell.azure.com lub wybierz przycisk Uruchom Cloud Shell, aby otworzyć środowisko Cloud Shell w przeglądarce.
Wybierz przycisk Cloud Shell na pasku menu w prawym górnym rogu witryny Azure Portal.

Aby użyć usługi Azure Cloud Shell:

Uruchom usługę Cloud Shell.
Wybierz przycisk Kopiuj w bloku kodu (lub bloku poleceń), aby skopiować kod lub polecenie.
Wklej kod lub polecenie do sesji usługi Cloud Shell, wybierając Ctrl+Shift V w systemach Windows i Linux lub wybierając pozycję Cmd+Shift++V w systemie macOS.
Wybierz Enter, aby uruchomić kod lub polecenie.

Konfigurowanie

W tej sekcji opisano proces tworzenia interfejsu API dla konta języka Gremlin i konfigurowania projektu platformy .NET w celu używania biblioteki do nawiązywania połączenia z kontem.

Tworzenie interfejsu API dla konta języka Gremlin

Przed użyciem biblioteki .NET należy utworzyć interfejs API dla konta języka Gremlin. Ponadto ułatwia także umieszczenie bazy danych i grafu.

Utwórz zmienne powłoki dla parametrów accountName, resourceGroupName i 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"

Jeśli jeszcze tego nie zrobiono, zaloguj się do interfejsu wiersza polecenia platformy Azure przy użyciu polecenia az login.
Użyj az group create polecenia , aby utworzyć nową grupę zasobów w ramach subskrypcji.
```
az group create \
    --name $resourceGroupName \
    --location $location
```
Użyj az cosmosdb create polecenia , aby utworzyć nowy interfejs API dla konta języka Gremlin z ustawieniami domyślnymi.
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
Uwaga

W ramach jednej subskrypcji platformy Azure można korzystać z maksymalnie jednego konta usługi Azure Cosmos DB w warstwie Bezpłatna. Tę opcję należy wybrać podczas tworzenia konta. Jeśli to polecenie nie zastosuje rabatu w warstwie Bezpłatna, oznacza to, że inne konto w subskrypcji zostało już włączone z warstwą Bezpłatna.
Pobierz interfejs API dla nazwy punktu końcowego języka Gremlin dla konta przy użyciu polecenia az cosmosdb show.
```
az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"
```

Znajdź klucz z listy kluczy dla konta za pomocą polecenia az-cosmosdb-keys-list.

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

Zapisz wartości NAME i KEY. Te poświadczenia będą używane później.

Utwórz bazę danych o nazwie cosmicworks przy użyciu polecenia az cosmosdb gremlin database create.

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

Utwórz graf przy użyciu polecenia az cosmosdb gremlin graph create. Nadaj grafowi productsnazwę , a następnie ustaw przepływność na 400, a na koniec ustaw ścieżkę klucza partycji na /category.

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

Tworzenie nowej aplikacji konsolowej .NET

Utwórz aplikację konsolową platformy .NET w pustym folderze przy użyciu preferowanego terminalu.

Otwórz terminal w pustym folderze.
dotnet new Użyj polecenia określającego szablon konsoli.
```
dotnet new console
```

Instalowanie pakietu NuGet

Gremlin.NET Dodaj pakiet NuGet do projektu .NET.

dotnet add package Użyj polecenia określającego Gremlin.Net pakiet NuGet.
```
dotnet add package Gremlin.Net
```
Skompiluj projekt platformy .NET przy użyciu polecenia dotnet build.
```
dotnet build
```
Upewnij się, że kompilacja zakończyła się pomyślnie bez błędów. Oczekiwane dane wyjściowe z kompilacji powinny wyglądać mniej więcej tak:
```
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)
```

Skonfiguruj zmienne środowiskowe

Aby użyć wartości NAME i URI uzyskanych wcześniej w tym przewodniku Szybki start, utrwali je w nowych zmiennych środowiskowych na komputerze lokalnym z uruchomioną aplikacją.

Aby ustawić zmienną środowiskową, użyj terminalu, aby utrwał wartości odpowiednio jako COSMOS_ENDPOINT i COSMOS_KEY .
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```
Sprawdź, czy zmienne środowiskowe zostały poprawnie ustawione.
```
printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY
```

Kod w tym artykule łączy się z bazą danych o nazwie cosmicworks i grafem o nazwie products. Następnie kod dodaje wierzchołki i krawędzie do grafu przed przejściem przez dodane elementy.

Uwierzytelnianie użytkownika

Żądania aplikacji do większości usług platformy Azure muszą być autoryzowane. W przypadku interfejsu API dla języka Gremlin użyj wartości NAME i URI uzyskanych wcześniej w tym przewodniku Szybki start.

Otwórz plik Program.cs.
Usuń dowolną istniejącą zawartość w pliku.
Dodaj blok using dla Gremlin.Net.Driver przestrzeni nazw.
```
using Gremlin.Net.Driver;
```
Tworzenie accountName zmiennych i accountKey ciągów. COSMOS_GREMLIN_ENDPOINT Zapisz zmienne środowiskowe i COSMOS_GREMLIN_KEY jako wartości dla każdej odpowiedniej zmiennej.
```
string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
```

Utwórz nowe wystąpienie GremlinServer przy użyciu poświadczeń konta.

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

Utwórz nowe wystąpienie GremlinClient przy użyciu poświadczeń serwera zdalnego i serializatora GraphSON 2.0 .

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

Tworzenie wierzchołków

Teraz, gdy aplikacja jest połączona z kontem, użyj standardowej składni języka Gremlin do tworzenia wierzchołków.

Użyj SubmitAsync polecenia , aby uruchomić polecenie po stronie serwera w interfejsie API dla konta gremlin. Utwórz wierzchołek produktu z następującymi właściwościami:

Wartość

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

Utwórz drugi wierzchołek produktu z następującymi właściwościami:

	Wartość
etykieta	`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')"
);

Utwórz trzeci wierzchołek produktu z następującymi właściwościami:

	Wartość
etykieta	`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')"
);

Tworzenie krawędzi

Tworzenie krawędzi przy użyciu składni języka Gremlin w celu zdefiniowania relacji między wierzchołkami.

Utwórz krawędź z Montau Turtle Surfboard produktu o nazwie replaces do Kiama classic surfboard produktu.
```
await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))"
);
```
Napiwek

Ta defincja krawędzi używa g.V(['<partition-key>', '<id>']) składni . Alternatywnie możesz użyć polecenia g.V('<id>').has('category', '<partition-key>').

Utwórz inny element zastępujący krawędź z tego samego produktu do elementu Bondi Twin Surfboard.

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

Wierzchołki i krawędzie zapytań

Składnia języka Gremlin umożliwia przechodzenie przez graf i odnajdywanie relacji między wierzchołkami.

Przechodzenie przez graf i znajdowanie wszystkich wierzchołków, które Montau Turtle Surfboard zastępują.

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

Zapisz w konsoli ciąg [CREATED PRODUCT]\t68719518403statyczny . Następnie należy wykonać iterację po każdym pasującym wierzchołku za pomocą foreach pętli i zapisać w konsoli komunikat rozpoczynający się od [REPLACES PRODUCT] i zawierający zgodne pole produktu id jako sufiks.
```
Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
{
    Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
}
```

Uruchamianie kodu

Sprawdź, czy aplikacja działa zgodnie z oczekiwaniami, uruchamiając aplikację. Aplikacja powinna być wykonywana bez błędów ani ostrzeżeń. Dane wyjściowe aplikacji zawierają dane dotyczące utworzonych i zapytanych elementów.

Otwórz terminal w folderze projektu .NET.
Użyj polecenia dotnet run , aby uruchomić aplikację.
```
dotnet run
```

Obserwuj dane wyjściowe z aplikacji.

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

Czyszczenie zasobów

Jeśli nie potrzebujesz już interfejsu API dla konta gremlin, usuń odpowiednią grupę zasobów.

Utwórz zmienną powłoki dla właściwości resourceGroupName , jeśli jeszcze nie istnieje.
```
# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
```
Użyj polecenia az group delete , aby usunąć grupę zasobów.
```
az group delete \
    --name $resourceGroupName
```

Następny krok

Tworzenie i wykonywanie zapytań dotyczących danych przy użyciu usługi Azure Cosmos DB dla języka Apache Gremlin

Udostępnij za pośrednictwem