Udostępnij za pośrednictwem


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

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

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. Zrzut ekranu przedstawiający przykład narzędzia Try It dla usługi Azure Cloud Shell.
Przejdź do witryny https://shell.azure.com lub wybierz przycisk Uruchom Cloud Shell, aby otworzyć środowisko Cloud Shell w przeglądarce. Przycisk uruchamiania usługi Azure Cloud Shell.
Wybierz przycisk Cloud Shell na pasku menu w prawym górnym rogu witryny Azure Portal. Zrzut ekranu przedstawiający przycisk usługi Cloud Shell w witrynie Azure Portal

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

  1. Uruchom usługę Cloud Shell.

  2. Wybierz przycisk Kopiuj w bloku kodu (lub bloku poleceń), aby skopiować kod lub polecenie.

  3. 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.

  4. 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.

  1. 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"
    
  2. Jeśli jeszcze tego nie zrobiono, zaloguj się do interfejsu wiersza polecenia platformy Azure przy użyciu polecenia az login.

  3. Użyj az group create polecenia , aby utworzyć nową grupę zasobów w ramach subskrypcji.

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. 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.

  5. 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"
    
  6. 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"
    
  7. Zapisz wartości NAME i KEY. Te poświadczenia będą używane później.

  8. 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"
    
  9. 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.

  1. Otwórz terminal w pustym folderze.

  2. dotnet new Użyj polecenia określającego szablon konsoli.

    dotnet new console
    

Instalowanie pakietu NuGet

Gremlin.NET Dodaj pakiet NuGet do projektu .NET.

  1. dotnet add package Użyj polecenia określającego Gremlin.Net pakiet NuGet.

    dotnet add package Gremlin.Net
    
  2. 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ą.

  1. 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>"
    
  2. Sprawdź, czy zmienne środowiskowe zostały poprawnie ustawione.

    printenv COSMOS_GREMLIN_ENDPOINT
    printenv COSMOS_GREMLIN_KEY
    

Przykłady kodu

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.

  1. Otwórz plik Program.cs.

  2. Usuń dowolną istniejącą zawartość w pliku.

  3. Dodaj blok using dla Gremlin.Net.Driver przestrzeni nazw.

    using Gremlin.Net.Driver;
    
  4. 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")!;
    
  5. 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
    );
    
  6. 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.

  1. 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')"
    );
    
  2. 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')"
    );
    
  3. 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.

  1. 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>').

  2. 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.

  1. 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()"
    );
    
  2. 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.

  1. Otwórz terminal w folderze projektu .NET.

  2. Użyj polecenia dotnet run , aby uruchomić aplikację.

    dotnet run
    
  3. 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.

  1. 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"
    
  2. Użyj polecenia az group delete , aby usunąć grupę zasobów.

    az group delete \
        --name $resourceGroupName
    

Następny krok