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

PLATÍ PRO: Gremlin

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

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. Screenshot that shows an example of Try It for Azure Cloud Shell.
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. Button to launch Azure Cloud Shell.
Zvolte tlačítko Cloud Shell v pruhu nabídky v pravém horním rohu webu Azure Portal. Screenshot that shows the Cloud Shell button in the Azure portal

Použití Azure Cloud Shellu:

  1. Spusťte Cloud Shell.

  2. Výběrem tlačítka Kopírovat v bloku kódu (nebo bloku příkazů) zkopírujte kód nebo příkaz.

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

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

  1. 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"
    
  2. Pokud jste to ještě neudělali, přihlaste se k Azure CLI pomocí az login.

  3. Slouží az group create k vytvoření nové skupiny prostředků ve vašem předplatném.

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

  5. 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"
    
  6. 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"
    
  7. Poznamenejte si hodnoty NAME a KEY . Tyto přihlašovací údaje použijete později.

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

  1. Otevřete terminál v prázdné složce.

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

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

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

  1. 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>"
    
  2. Ověřte, že proměnné prostředí byly správně nastaveny.

    printenv COSMOS_GREMLIN_ENDPOINT
    printenv COSMOS_GREMLIN_KEY
    

Příklady kódu

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.

  1. Otevřete soubor Program.cs.

  2. Odstraňte veškerý existující obsah v souboru.

  3. Přidejte blok using pro Gremlin.Net.Driver obor názvů.

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

  1. 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
    Popisek 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. Vytvořte druhý vrchol produktu s těmito vlastnostmi:

    Hodnota
    Popisek 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. Vytvořte třetí vrchol produktu s těmito vlastnostmi:

    Hodnota
    Popisek 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.

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

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

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

  1. Otevřete terminál ve složce projektu .NET.

  2. Slouží dotnet run ke spuštění aplikace.

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

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

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-gremlin-quickstart"
    
  2. Slouží az group delete k odstranění skupiny prostředků.

    az group delete \
        --name $resourceGroupName
    

Další krok