rychlý start: vytvoření .NET Framework nebo základní aplikace pomocí účtu rozhraní API Azure Cosmos DB Gremlin

  • Článek
  • 10 min ke čtení

PLATÍ pro: rozhraní Gremlin API

Azure Cosmos DB je globálně distribuovaná databázová služba Microsoftu pro více modelů. Můžete snadno vytvořit a dotazovat databáze dotazů, klíčů/hodnot a grafů, které tak můžou využívat výhody použitelnosti v celosvětovém měřítku a možností horizontálního škálování v jádru Azure Cosmos DB.

tento rychlý start ukazuje, jak vytvořit Azure Cosmos DB účet rozhraní API Gremlin , databázi a graf (kontejner) pomocí Azure Portal. Potom sestavíte a spustíte konzolovou aplikaci pomocí open source ovladače Gremlin.Net.

Požadavky

pokud ještě nemáte nainstalované Visual Studio 2019, můžete si stáhnout a použít bezplatnou edici Visual Studio 2019 Community. Nezapomeňte při instalaci sady Visual Studio povolit možnost Azure Development.

Pokud ještě nemáte předplatné Azure,vytvořte si bezplatný účet před tím, než začnete.

Vytvoření účtu databáze

  1. V novém okně prohlížeče se přihlaste k webu Azure Portal.

  2. V nabídce vlevo vyberte Vytvořit prostředek.

    Vytvoření prostředku na portálu Azure Portal

  3. Na stránce Nový vyberte Databáze > Azure Cosmos DB.

    Podokno Databáze na webu Azure Portal

  4. Na stránce Vytvořit účet Azure Cosmos DB zadejte nastavení pro nový účet Azure Cosmos DB.

    Nastavení Hodnota Popis
    Předplatné Název předplatného Vyberte předplatné Azure, které chcete pro tento účet Azure Cosmos azure.
    Skupina prostředků Název skupiny prostředků Vyberte skupinu prostředků nebo vyberte Vytvořit novou a pak zadejte jedinečný název nové skupiny prostředků.
    Account Name Zadejte jedinečný název. Zadejte jedinečný název, který identifikuje váš účet služby Azure Cosmos DB. Identifikátor URI vašeho účtu se gremlin.azure.com k vašemu jedinečnému názvu účtu připojí.

    Název účtu může obsahovat pouze malá písmena, číslice a spojovníky (-) a musí být dlouhý 3 až 44 znaků.
    Rozhraní API Gremlin (graf) Rozhraní API určuje typ účtu, který se má vytvořit. Azure Cosmos DB poskytuje pět rozhraní API: Core (SQL) pro dokumentové databáze, Gremlin pro grafové databáze, MongoDB pro dokumentové databáze, Azure Table a Cassandra. Pro každé rozhraní API musíte vytvořit samostatný účet.

    Vyberte Gremlin (graf), protože v tomto rychlém startu vytváříte tabulku, která funguje s rozhraním Gremlin API.

    Přečtěte si další informace o rozhraní Gremlin API.
    Umístění Oblast nejbližší vašim uživatelům Vyberte zeměpisné umístění, ve kterém chcete účet služby Azure Cosmos DB hostovat. Použijte umístění, které je vašim uživatelům nejblíže, a podejte jim nejrychlejší přístup k datům.
    Režim kapacity Zřízená propustnost nebo bez serveru Vyberte Zřízená propustnost a vytvořte účet v režimu zřízené propustnosti. Vyberte Bez serveru a vytvořte účet v režimu bez serveru.
    Použití slevy na bezplatnou úroveň Azure Cosmos DB Použít nebo Neakusovat S úrovní Free služby Azure Cosmos DB získáte v účtu prvních 1 000 RU/s a 25 GB úložiště zdarma. Přečtěte si další informace o úrovni Free.

    Poznámka

    Pro jedno předplatné Azure můžete mít až jeden účet Azure Cosmos DB úrovně Free a při vytváření účtu se musíte přihlásit. Pokud nevidíte možnost uplatnit slevu na bezplatnou úroveň, znamená to, že u jiného účtu v předplatném už je povolená úroveň Free.

    Stránka nového účtu pro službu Azure Cosmos DB

  5. Na kartě Globální distribuce nakonfigurujte následující podrobnosti. Pro účely tohoto rychlého startu můžete ponechat výchozí hodnoty:

    Nastavení Hodnota Popis
    Geografická redundance Zakázat Povolte nebo zakažte globální distribuci vašeho účtu spárováním oblasti s párovou oblastí. Další oblasti můžete do svého účtu přidat později.
    Zápisy do více oblastí Zakázat Funkce zápisu do více oblastí umožňuje využít zřízenou propustnost pro databáze a kontejnery po celém světě.

    Poznámka

    Pokud jako Režim kapacity vyberete Bez serveru, nejsou k dispozici následující možnosti:

    • Použít slevu založenou na bezplatné úrovni
    • Geografická redundance
    • Zápisy do více oblastí

  6. Volitelně můžete nakonfigurovat další podrobnosti na následujících kartách:

  7. Vyberte Zkontrolovat a vytvořit.

  8. Vytvoření účtu trvá několik minut. Počkejte, až se na portálu zobrazí blahopřejeme! Váš účet Azure Cosmos DB byl vytvořen.

    Stránka vytvoření účtu Azure Cosmos DB

Přidání grafu

Teď můžete pomocí nástroje Průzkumník dat na webu Azure Portal vytvořit databázi grafu.

  1. vyberte Průzkumník dat > nová Graph.

    Úplně vpravo se zobrazí oblast Přidat graf. Pokud ji nevidíte, možná se budete muset posunout doprava.

    Průzkumník dat na portálu Azure – stránka Přidat graf

  2. Na stránce Přidat graf zadejte nastavení pro nový graf.

    Nastavení Navrhovaná hodnota Popis
    ID databáze sample-database Jako název nové databáze zadejte sample-database. Názvy databází musí mít délku 1 až 255 znaků a nesmí obsahovat znaky / \ # ? ani koncové mezery.
    Propustnost 400 RU/s Změňte propustnost na 400 jednotek žádostí za sekundu (RU/s). Pokud budete chtít snížit latenci, můžete propustnost později navýšit.
    ID grafu sample-graph Jako název nové kolekce zadejte sample-graph. U názvů grafů platí stejné požadavky na znaky jako u ID databází.
    Partition Key (Klíč oddílu) /pk všechny účty Cosmos DB potřebují ke horizontálnímu škálování klíč oddílu. naučte se, jak vybrat vhodný klíč oddílu v článku Graphho dělení dat.

  3. Po vyplnění formuláře vyberte OK.

Klonování ukázkové aplikace

Teď naklonujeme aplikaci rozhraní Gremlin API z GitHubu, nastavíme připojovací řetězec a spustíme ji. Přesvědčíte se, jak snadno se pracuje s daty prostřednictvím kódu programu.

  1. Otevřete příkazový řádek, vytvořte novou složku git-samples a pak příkazový řádek zavřete.

    md "C:\git-samples"

  2. Otevřete okno terminálu Git, například Git Bash, a pomocí příkazu cd přejděte do nové složky, do které chcete nainstalovat ukázkovou aplikaci.

    cd "C:\git-samples"

  3. Ukázkové úložiště naklonujete spuštěním následujícího příkazu. Tento příkaz vytvoří na vašem počítači kopii ukázkové aplikace.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-gremlindotnet-getting-started.git

  4. Potom otevřete sadu Visual Studio a otevřete soubor řešení.

  5. Obnovte balíčky NuGet v projektu. Ty by měly zahrnovat ovladač Gremlin.Net i balíček Newtonsoft.Json.

  6. Ovladač můžete nainstalovat také Gremlin.Net@v3.4.6 ručně pomocí Správce balíčků NuGet nebo pomocí nástroje příkazového řádku NuGet:

    nuget install Gremlin.NET -Version 3.4.6

Poznámka

Rozhraní Gremlin API aktuálně podporuje pouze Gremlin.NET až v 3.4.6. Pokud nainstalujete nejnovější verzi, zobrazí se při používání služby chybové zprávy.

Kontrola kódu

Tento krok je volitelný. Pokud chcete zjistit, jak se v kódu vytvářejí prostředky databáze, můžete si prohlédnout následující fragmenty kódu. Jinak můžete přeskočit přímo k části Aktualizace informací o připojení.

Všechny následující fragmenty kódu pocházejí ze souboru Program.cs.

  • Nastavte parametry připojení na základě účtu vytvořeného výše:

    private static string Host => Environment.GetEnvironmentVariable("Host") ?? throw new ArgumentException("Missing env var: Host");
private static string PrimaryKey => Environment.GetEnvironmentVariable("PrimaryKey") ?? throw new ArgumentException("Missing env var: PrimaryKey");
private static string Database => Environment.GetEnvironmentVariable("DatabaseName") ?? throw new ArgumentException("Missing env var: DatabaseName");
private static string Container => Environment.GetEnvironmentVariable("ContainerName") ?? throw new ArgumentException("Missing env var: ContainerName");

private static bool EnableSSL
{
    get
    {
        if (Environment.GetEnvironmentVariable("EnableSSL") == null)
        {
            return true;
        }

        if (!bool.TryParse(Environment.GetEnvironmentVariable("EnableSSL"), out bool value))
        {
            throw new ArgumentException("Invalid env var: EnableSSL is not a boolean");
        }

        return value;
    }
}

private static int Port
{
    get
    {
        if (Environment.GetEnvironmentVariable("Port") == null)
        {
            return 443;
        }

        if (!int.TryParse(Environment.GetEnvironmentVariable("Port"), out int port))
        {
            throw new ArgumentException("Invalid env var: Port is not an integer");
        }

        return port;
    } 
}

  • Gremlin příkazy, které se mají spustit, jsou uvedené ve slovníku:

    private static Dictionary<string, string> gremlinQueries = new Dictionary<string, string>
{
    { "Cleanup",        "g.V().drop()" },
    { "AddVertex 1",    "g.addV('person').property('id', 'thomas').property('firstName', 'Thomas').property('age', 44).property('pk', 'pk')" },
    { "AddVertex 2",    "g.addV('person').property('id', 'mary').property('firstName', 'Mary').property('lastName', 'Andersen').property('age', 39).property('pk', 'pk')" },
    { "AddVertex 3",    "g.addV('person').property('id', 'ben').property('firstName', 'Ben').property('lastName', 'Miller').property('pk', 'pk')" },
    { "AddVertex 4",    "g.addV('person').property('id', 'robin').property('firstName', 'Robin').property('lastName', 'Wakefield').property('pk', 'pk')" },
    { "AddEdge 1",      "g.V('thomas').addE('knows').to(g.V('mary'))" },
    { "AddEdge 2",      "g.V('thomas').addE('knows').to(g.V('ben'))" },
    { "AddEdge 3",      "g.V('ben').addE('knows').to(g.V('robin'))" },
    { "UpdateVertex",   "g.V('thomas').property('age', 44)" },
    { "CountVertices",  "g.V().count()" },
    { "Filter Range",   "g.V().hasLabel('person').has('age', gt(40))" },
    { "Project",        "g.V().hasLabel('person').values('firstName')" },
    { "Sort",           "g.V().hasLabel('person').order().by('firstName', decr)" },
    { "Traverse",       "g.V('thomas').out('knows').hasLabel('person')" },
    { "Traverse 2x",    "g.V('thomas').out('knows').hasLabel('person').out('knows').hasLabel('person')" },
    { "Loop",           "g.V('thomas').repeat(out()).until(has('id', 'robin')).path()" },
    { "DropEdge",       "g.V('thomas').outE('knows').where(inV().has('id', 'mary')).drop()" },
    { "CountEdges",     "g.E().count()" },
    { "DropVertex",     "g.V('thomas').drop()" },
};

  • Vytvořte nové GremlinServer objekty a GremlinClient objekty připojení pomocí výše uvedených parametrů:

    string containerLink = "/dbs/" + Database + "/colls/" + Container;
Console.WriteLine($"Connecting to: host: {Host}, port: {Port}, container: {containerLink}, ssl: {EnableSSL}");
var gremlinServer = new GremlinServer(Host, Port, enableSsl: EnableSSL, 
                                        username: containerLink, 
                                        password: PrimaryKey);

ConnectionPoolSettings connectionPoolSettings = new ConnectionPoolSettings()
{
    MaxInProcessPerConnection = 10,
    PoolSize = 30, 
    ReconnectionAttempts= 3,
    ReconnectionBaseDelay = TimeSpan.FromMilliseconds(500)
};

var webSocketConfiguration =
    new Action<ClientWebSocketOptions>(options =>
    {
        options.KeepAliveInterval = TimeSpan.FromSeconds(10);
    });


using (var gremlinClient = new GremlinClient(
    gremlinServer, 
    new GraphSON2Reader(), 
    new GraphSON2Writer(), 
    GremlinClient.GraphSON2MimeType, 
    connectionPoolSettings, 
    webSocketConfiguration))
{

  • Spusťte každý dotaz Gremlin pomocí GremlinClient objektu s asynchronní úlohou. Můžete číst dotazy Gremlin ze slovníku definovaného v předchozím kroku a provést je. Později Získejte výsledek a přečtěte si hodnoty, které jsou formátovány jako slovník, pomocí JsonSerializer třídy z balíčku Newtonsoft. JSON:

    foreach (var query in gremlinQueries)
{
    Console.WriteLine(String.Format("Running this query: {0}: {1}", query.Key, query.Value));

    // Create async task to execute the Gremlin query.
    var resultSet = SubmitRequest(gremlinClient, query).Result;
    if (resultSet.Count > 0)
    {
        Console.WriteLine("\tResult:");
        foreach (var result in resultSet)
        {
            // The vertex results are formed as Dictionaries with a nested dictionary for their properties
            string output = JsonConvert.SerializeObject(result);
            Console.WriteLine($"\t{output}");
        }
        Console.WriteLine();
    }

    // Print the status attributes for the result set.
    // This includes the following:
    //  x-ms-status-code            : This is the sub-status code which is specific to Cosmos DB.
    //  x-ms-total-request-charge   : The total request units charged for processing a request.
    //  x-ms-total-server-time-ms   : The total time executing processing the request on the server.
    PrintStatusAttributes(resultSet.StatusAttributes);
    Console.WriteLine();
}

Aktualizace připojovacího řetězce

Teď se vraťte zpátky na portál Azure Portal, kde najdete informace o připojovacím řetězci, a zkopírujte je do aplikace.

  1. Na webu Azure Portal přejděte k vašemu účtu databáze grafů. Na kartě Přehled se zobrazují dva koncové body:

    .NET SDK URI – tato hodnota se používá, když se připojíte k účtu grafu pomocí knihovny Microsoft. Azure. Graphs.

    Koncový bod Gremlin – Tato hodnota se použije, když se k účtu databáze grafů připojíte s využitím knihovny Gremlin.Net.

    Kopírování koncového bodu

    Pokud chcete tuto ukázku spustit, zkopírujte hodnotu Gremlin koncového bodu , odstraňte číslo portu na konci, což znamená, že se identifikátor URI naplní https://<your cosmos db account name>.gremlin.cosmosdb.azure.com . Hodnota koncového bodu by měla vypadat nějak takto. testgraphacct.gremlin.cosmosdb.azure.com

  2. Potom přejděte na kartu klíče a zkopírujte hodnotu primárního klíče z Azure Portal.

  3. Po zkopírování identifikátoru URI a primárního klíče účtu ho uložte do nové proměnné prostředí v místním počítači, na kterém je spuštěná aplikace. Chcete-li nastavit proměnnou prostředí, otevřete okno příkazového řádku a spusťte následující příkaz. Nezapomeňte nahradit <Your_Azure_Cosmos_account_URI> a hodnoty <Your_Azure_Cosmos_account_PRIMARY_KEY>.

    setx Host "<your Azure Cosmos account name>.gremlin.cosmosdb.azure.com"
setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

  4. Otevřete soubor program. cs a aktualizujte proměnné "Database a Container" pomocí databáze a kontejneru (což je také název grafu), které jste vytvořili výše.

    private static string database = "your-database-name"; private static string container = "your-container-or-graph-name";

  5. Uložte soubor Program.cs.

Teď jste aktualizovali aplikaci a zadali do ní všechny informace potřebné ke komunikaci s Azure Cosmos DB.

Spuštění aplikace konzoly

Spusťte aplikaci stisknutím CTRL+F5. Aplikace vypíše v konzole příkazy i výsledky dotazů Gremlin.

V okně konzoly se zobrazí vrcholy a hrany, které se přidávají do grafu. Po dokončení skriptu stisknutím klávesy ENTER zavřete okno konzoly.

Procházení pomocí Průzkumníku dat

Teď se můžete vrátit do Průzkumníku dat na webu Azure Portal, procházet nová data grafu a zadávat na ně dotazy.

  1. V Průzkumníku dat se nová databáze zobrazí v podokně Graphs (Grafy). Rozbalte uzly databáze a kontejneru a pak klikněte na Graph.

  2. Kliknutím na tlačítko Použít filtr použijte výchozí dotaz k zobrazení všech vrcholů v grafu. V podokně Graphs (Grafy) se zobrazí data vygenerovaná ukázkovou aplikací.

    Graf můžete přiblížit nebo oddálit, můžete rozšířit prostor pro zobrazení grafu, přidat další vrcholy a přesouvat vrcholy na zobrazovací ploše.

    Zobrazení grafu v Průzkumníku dat na webu Azure Portal

Ověření smluv SLA na webu Azure Portal

Tento Azure Portal monitoruje propustnost Cosmos DB účtu, úložiště, dostupnost, latenci a konzistenci vašeho účtu. Grafy metrik přidružených k Azure Cosmos DB smlouva SLA (SLA) zobrazují hodnotu SLA v porovnání se skutečným výkonem. Díky této metrice je monitorování smluv SLA transparentní.

Kontrola metrik a smluv SLA:

  1. V navigační nabídce vašeho Cosmos DB účtu vyberte Metriky.

  2. Vyberte kartu, například Latence, a vpravo vyberte časový rámec. Porovnejte čáry Actual (Skutečný) a SLA (Sla) v grafech.

    Sada metrik Azure Cosmos DB

  3. Zkontrolujte metriky na ostatních kartách.

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

Až budete s aplikací a Azure Cosmos DB účtem hotovi, můžete odstranit prostředky Azure, které jste vytvořili, abyste se neúčtují další poplatky. Odstranění prostředků:

  1. Na panelu hledání Azure Portal vyhledejte a vyberte skupiny prostředků.

  2. V seznamu vyberte skupinu prostředků, kterou jste vytvořili pro tento rychlý Start.

    Vyberte skupinu prostředků, kterou chcete odstranit.

  3. Na stránce Přehled skupiny prostředků vyberte Odstranit skupinu prostředků.

    Odstranění skupiny prostředků

  4. V dalším okně zadejte název skupiny prostředků, kterou chcete odstranit, a pak vyberte Odstranit.

Další kroky

V tomto rychlém startu jste se seznámili s postupem vytvoření účtu databáze Azure Cosmos, vytvoření grafu pomocí Průzkumníku dat a spuštění aplikace. Teď můžete pomocí konzoly Gremlin vytvářet složitější dotazy a implementovat účinnou logiku procházení grafů.

Dotazování pomocí konzoly Gremlin