Rychlý start: Vytvoření aplikace .NET Framework nebo Core pomocí účtu rozhraní Gremlin API služby Azure Cosmos DB

PLATÍ PRO: Gremlin API

Azure Cosmos DB je globálně distribuovaná databázová služba Microsoftu pro více modelů. Můžete rychle vytvářet a dotazovat dokumenty, klíč/hodnotu a grafové databáze. To vše, co přináší výhody globální distribuce a horizontálního škálování v jádru služby Azure Cosmos DB.

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

Požadavky

Nejnovější Visual Studio s úlohu vývoje pro Azure Můžete začít s bezplatným komunitním integrovaném vývojovém prostředím sady Visual Studio. Povolte úlohu vývoje v Azure během instalace sady Visual Studio.

Pokud nemáte předplatné Azure, vytvořte si bezplatný účet Azure , 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.

    Create a resource in the Azure portal

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

    The Azure portal Databases pane

  4. Na stránce Vytvořit účet služby Azure Cosmos DB zadejte nastavení nového účtu služby Azure Cosmos DB.

    Nastavení Hodnota Popis
    Předplatné Název předplatného Vyberte předplatné Azure, které chcete použít pro tento účet Azure Cosmos.
    Skupina prostředků Název skupiny prostředků Vyberte skupinu prostředků nebo vyberte Vytvořit novou a 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 připojí k vašemu jedinečnému názvu účtu.

    Název účtu může používat jenom malá písmena, číslice a spojovníky (-) a musí mít délku 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 databáze dokumentů, Gremlin pro grafové databáze, MongoDB pro databáze dokumentů, 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 nejblíže vašim uživatelům, abyste jim poskytli nejrychlejší přístup k datům.
    Režim kapacity Zřízená propustnost nebo bezserverová Výběrem zřízené propustnosti vytvořte účet v režimu zřízené propustnosti . Výběrem možnosti Bezserverový účet vytvoříte v bezserverovém režimu.
    Použití slevy na úroveň Free služby Azure Cosmos DB Použít nebo neaplikovat S úrovní Free služby Azure Cosmos DB získáte prvních 1000 RU/s a 25 GB úložiště zdarma v účtu. Přečtěte si další informace o úrovni Free.

    Poznámka

    Účet Služby Azure Cosmos DB úrovně Free můžete mít až na jedno předplatné Azure a při vytváření účtu se musíte přihlásit. Pokud nevidíte možnost použít slevu na úroveň Free, znamená to, že u bezplatné úrovně už byl povolený jiný účet v předplatném.

    The new account page for Azure Cosmos DB

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

    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í. Do svého účtu můžete později přidat další oblasti.
    Zápisy do více oblastí Zakázat Funkce zápisů ve více oblastech umožňuje využívat zřízenou propustnost pro databáze a kontejnery po celém světě.

    Poznámka

    Pokud jako režim kapacity vyberete bezserverový režim, 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 na zobrazení blahopřejeme na portálu! Vytvořili jste stránku vašeho účtu služby Azure Cosmos DB .

    Azure Cosmos DB account created page

Přidání grafu

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

  1. VyberteNový graf Průzkumníka>dat.

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

    The Azure portal Data Explorer, Add Graph page

  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í klíč oddílu k horizontálnímu škálování. Přečtěte si, jak vybrat odpovídající klíč oddílu v článku o dělení dat grafu.
  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. Uvidíte, jak snadné je pracovat 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. Příkaz git clone vytvoří kopii ukázkové aplikace na vašem počítači.

    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. Operace obnovení by měla obsahovat ovladač Gremlin.Net a balíček Newtonsoft.Json.

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

    nuget install Gremlin.NET -Version 3.4.13
    

Poznámka

Podporovaná verze ovladače Gremlin.NET pro rozhraní Gremlin API je k dispozici tady. Nejnovější vydané verze Gremlin.NET se můžou zobrazit nekompatibility, proto zkontrolujte propojenou tabulku, jestli není k dispozici aktualizace kompatibility.

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ě výše vytvořeného účtu:

    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;
        } 
    }
    
  • Příkazy Gremlin, které se mají spustit, jsou uvedeny 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()" },
    };
    
  • Pomocí výše uvedených parametrů vytvořte nové GremlinServer objekty a GremlinClient objekty připojení:

    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í objektu GremlinClient s asynchronní úlohou. Dotazy Gremlin si můžete přečíst ze slovníku definovaného v předchozím kroku a spustit 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:

    Identifikátor URI sady .NET SDK – Tato hodnota se používá při připojování 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.

    Copy the endpoint

    Pro tuto ukázku poznamenejte hodnotu hostitelekoncového bodu Gremlin. Pokud je https://graphtest.gremlin.cosmosdb.azure.comnapříklad identifikátor URI , hodnota Hostitele by byla graphtest.gremlin.cosmosdb.azure.com.

  2. Dále přejděte na kartu Klíče a na webu Azure Portal nahrajte hodnotu PRIMÁRNÍHO KLÍČE .

  3. Po zkopírování identifikátoru URI a PRIMÁRNÍho klíče účtu je uložte do nové proměnné prostředí na místním počítači, na kterém běží aplikace. Pokud chcete nastavit proměnnou prostředí, otevřete okno příkazového řádku a spusťte následující příkaz. Nezapomeňte nahradit <cosmos-account-name> a <cosmos-account-primary-key> hodnoty.

    setx Host "<cosmos-account-name>.gremlin.cosmosdb.azure.com"
    setx PrimaryKey "<cosmos-account-primary-key>"
    
  4. Otevřete soubor Program.cs a aktualizujte výše vytvořené názvy databáze a kontejneru pomocí názvů databáze a kontejneru (což je také název grafu).

    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 uzel databáze a kontejneru a pak vyberte Graph.

  2. Výběrem tlačítka 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, rozšířit prostor pro zobrazení grafu, přidat další vrcholy a přesunout vrcholy na plochu displeje.

    View the graph in Data Explorer in the Azure portal

Ověření smluv SLA na webu Azure Portal

Azure Portal monitoruje propustnost, úložiště, dostupnost, latenci a konzistenci účtu Cosmos DB. Grafy metrik přidružených ke smlouvě SLA (Service Level Agreement) služby Azure Cosmos DB zobrazují hodnotu SLA v porovnání se skutečným výkonem. Tato sada metrik zajišťuje transparentní monitorování smluv SLA.

Kontrola metrik a smluv SLA:

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

  2. Vyberte kartu, například Latence, a vyberte časový rámec napravo. Porovnejte skutečné čáry a čárySLA v grafech.

    Azure Cosmos DB metrics suite

  3. Zkontrolujte metriky na dalších kartách.

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

Až skončíte s aplikací a účtem služby Azure Cosmos DB, můžete prostředky Azure, které jste vytvořili, odstranit, takže vám nebudou účtovány další poplatky. Odstranění prostředků:

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

  2. V seznamu vyberte skupinu prostředků, kterou jste vytvořili pro účely tohoto rychlého startu.

    Select the resource group to delete

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

    Delete the resource group

  4. V dalším okně zadejte název skupiny prostředků, která 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ů.