Snabbstart: Skapa ett .NET Framework- eller Core-program med hjälp Azure Cosmos DB Gremlin API-konto

Artikel
11/24/2021
10 minuter för att läsa

GÄLLER för: Gremlin-API

Azure Cosmos DB är Microsofts globalt distribuerade databastjänst för flera datamodeller. Du kan snabbt skapa och ställa frågor mot databaser med dokument, nyckel/värde-par och grafer. Du får fördelar av den globala distributionen och den horisontella skalningsförmågan som ligger i grunden hos Azure Cosmos DB.

Den här snabbstarten visar hur du skapar ett Azure Cosmos DB Gremlin API-konto, databas och graf (container) med hjälp av Azure Portal. Sedan skapar och kör du en konsolapp med drivrutinen Gremlin.Net (öppen källkod).

Förutsättningar

Om du inte redan har installerat Visual Studio 2019 kan du ladda ned och använda den kostnadsfria versionen Visual Studio 2019 Community Edition. Se till att du aktiverar Azure-utveckling under installationen av Visual Studio.

Om du inte har en Azure-prenumerationkan du skapa ett kostnads fritt konto innan du börjar.

Skapa ett databaskonto

Logga in på Azure Portal i ett nytt webbläsarfönster.
I den vänstra menyn väljer du Skapa en resurs.
På sidan Nytt väljer du Databaser > Azure Cosmos DB.

På sidan Skapa Azure Cosmos DB konto anger du inställningarna för det nya Azure Cosmos DB konto.

Inställning	Värde	Beskrivning
Prenumeration	Prenumerationens namn	Välj den Azure-prenumeration som ska användas för det här Azure Cosmos-kontot.
Resursgrupp	Namn på resursgrupp	Välj en resursgrupp eller välj Skapa ny och ange sedan ett unikt namn för den nya resursgruppen.
Account Name	Ange ett unikt namn	Ange ett unikt namn som identifierar ditt Azure Cosmos DB-konto. Din konto-URI gremlin.azure.com till ditt unika kontonamn. Kontonamnet får bara innehålla gemener, siffror och bindestreck (-) och måste vara mellan 3 och 44 tecken långt.
API	Gremlin (graf)	API:et avgör vilken typ av konto som skapas. Azure Cosmos DB innehåller fem API:er: Core (SQL) för dokumentdatabaser, Gremlin för grafdatabaser, MongoDB för dokumentdatabaser, Azure Table och Cassandra. Du måste skapa ett separat konto för varje API. Välj Gremlin (graf) eftersom du i den här snabbstarten skapar en tabell som fungerar med Gremlin-API:et. Läs mer om Gremlin-API:et.
Location	Den region som är närmast dina användare	Välj en geografisk plats som värd för ditt Azure Cosmos DB-konto. Använd den plats som är närmast dina användare för att ge dem så snabb åtkomst till data som möjligt.
Kapacitetsläge	Etablerat dataflöde eller serverlöst	Välj Etablerat dataflöde för att skapa ett konto i etablerat dataflödesläge. Välj Serverlös för att skapa ett konto i serverlöst läge.
Tillämpa Azure Cosmos DB rabatt på den kostnadsfria nivån	Tillämpa eller Tillämpa inte	Med Azure Cosmos DB kostnadsfri nivå får du de första 1 000 RU/s och 25 GB lagringsutrymme kostnadsfritt i ett konto. Läs mer om den kostnadsfria nivån.

Anteckning

Du kan ha upp till en kostnadsfri nivå Azure Cosmos DB per Azure-prenumeration och måste välja när du skapar kontot. Om du inte ser alternativet för att tillämpa rabatten på den kostnadsfria nivån innebär det att ett annat konto i prenumerationen redan har aktiverats med den kostnadsfria nivån.

Den nya kontosidan för Azure Cosmos DB

Konfigurera följande information på fliken Global distribution. Du kan lämna standardvärdena för den här snabbstarten:

Inställning	Värde	Beskrivning
Geo-redundans	Inaktivera	Aktivera eller inaktivera global distribution på ditt konto genom att koppla ihop din region med en parregion. Du kan lägga till fler regioner i ditt konto senare.
Skrivåtgärder för flera regioner	Inaktivera	Med skrivfunktioner för flera regioner kan du dra nytta av det etablerade dataflödet för dina databaser och containrar över hela världen.

Anteckning

Följande alternativ är inte tillgängliga om du väljer Serverlös som Kapacitetsläge:

Tillämpa rabatt för kostnadsfri nivå
Geo-redundans
Skrivåtgärder för flera regioner

Du kan också konfigurera ytterligare information på följande flikar:
- Nätverk – Konfigurera åtkomst från ett virtuellt nätverk.
- Säkerhetskopieringspolicy – Konfigurera antingen periodisk eller kontinuerlig säkerhetskopieringspolicy.
- Kryptering – Använd antingen en tjänst hanterad nyckel eller en kund hanterad nyckel.
- Taggar – Taggar är namn/värde-par som gör att du kan kategorisera resurser och visa konsoliderad fakturering genom att tillämpa samma tagg på flera resurser och resursgrupper.
Välj Granska + skapa.
Det tar några minuter att skapa kontot. Vänta tills portalen visar grattis! Din Azure Cosmos DB-konto har skapats.

Lägga till en graf

Nu kan du använda datautforskarverktyget i Azure Portal för att skapa en grafdatabas.

Välj Datautforskaren > Ny Graph.

Området Lägg till diagram visas längst till höger, du kan behöva bläddra åt höger för att se det.

På sidan Lägg till diagram anger du inställningarna för den nya grafen.

Inställning	Föreslaget värde	Beskrivning
Databas-id	sample-database	Ange sample-database som namn på den nya databasen. Databasnamn måste innehålla mellan 1 och 255 tecken och får inte innehålla `/ \ # ?` eller avslutande blanksteg.
Dataflöde	400 RU:er	Ändra genomflödet till 400 begäransenheter per sekund (RU/s). Du kan skala upp dataflödet senare om du vill minska svarstiden.
Graf-id	sample-graph	Ange sample-graph som namnet på den nya samlingen. Samma teckenkrav gäller för diagramnamn som databas-ID:n.
Partition Key (Partitionsnyckel)	/pk	Alla Cosmos DB-konton behöver en partitionsnyckel för horisontell skalning. Lär dig hur du väljer en lämplig partitionsnyckel i artikeln Graph datapartitionering.

När formuläret har fyllts i väljer du OK.

Klona exempelprogrammet

Nu ska vi klona en Gremlin-API-app från GitHub, ange anslutningssträngen och köra appen. Du kommer att se hur lätt det är att arbeta med data programmässigt.

Öppna en kommandotolk, skapa en ny mapp som heter git-samples och stäng sedan kommandotolken.
```
md "C:\git-samples"
```
Öppna ett git-terminalfönster, t.ex. git bash, och använd kommandot cd för att ändra till den nya mappen där du vill installera exempelappen.
```
cd "C:\git-samples"
```
Klona exempellagringsplatsen med följande kommando. Detta kommando skapar en kopia av exempelappen på din dator.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-gremlindotnet-getting-started.git
```
Öppna sedan Visual Studio och öppna lösningsfilen.
Återställ NuGet-paketen i projektet. Det bör inkludera Gremlin.Net-drivrutinen och Newtonsoft.Json-paketet.
Du kan också installera Gremlin.Net@v3.4.6 drivrutinen manuellt med nuget-pakethanteraren eller kommandoradsverktyget nuget:
```
nuget install Gremlin.NET -Version 3.4.6
```

Anteckning

Gremlin-API:et stöder för närvarande endast Gremlin.Net upp till v3.4.6. Om du installerar den senaste versionen får du felmeddelanden när du använder tjänsten.

Granska koden

Det här är valfritt. Om du vill lära dig hur databasresurserna skapas i koden kan du granska följande kodavsnitt. Annars kan du gå vidare till Uppdatera din anslutningssträng.

Följande kodfragment är alla hämtade från filen Program.cs.

Ange anslutningsparametrarna baserat på kontot som skapades ovan:

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-kommandona som ska köras visas i en ordlista:

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()" },
};

Skapa ett nytt GremlinServer objekt GremlinClient och anslutningsobjekt med hjälp av parametrarna ovan:

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))
{

Kör varje Gremlin-fråga med GremlinClient hjälp av objektet med en asynkron uppgift. Du kan läsa Gremlin-frågorna från ordlistan som definierades i föregående steg och köra dem. Senare hämtar du resultatet och läser värdena, som formateras som en ordlista, med hjälp av klassen JsonSerializer från Newtonsoft.Json-paketet:

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();
}

Uppdatera din anslutningssträng

Gå nu tillbaka till Azure Portal för att hämta information om din anslutningssträng och kopiera den till appen.

Öppna Azure Portal och navigera till ditt Graph-databaskonto. På fliken Översikt ser du två slutpunkter:

.NET SDK-URI – Det här värdet används när du ansluter till graph-kontot med hjälp av biblioteket Microsoft.Azure.Graphs.

Gremlin-slutpunkt – Det här värdet används när du ansluter till Graph-kontot via biblioteket Gremlin.Net.

Kör det här exemplet genom att kopiera värdet för Gremlin-slutpunkten, ta bort portnumret i slutet, det vill säga URI:en blir https://<your cosmos db account name>.gremlin.cosmosdb.azure.com . Slutpunktsvärdet bör se ut så här testgraphacct.gremlin.cosmosdb.azure.com
Gå sedan till fliken Nycklar och kopiera värdet för PRIMÄRNYCKEL från Azure Portal.
När du har kopierat URI och PRIMÄRNYCKEL för ditt konto sparar du dem i en ny miljövariabel på den lokala dator som kör programmet. Ange miljövariabeln genom att öppna ett kommandotolkfönster och köra följande kommando. Se till att ersätta <Your_Azure_Cosmos_account_URI> och <Your_Azure_Cosmos_account_PRIMARY_KEY> värden.
```
setx Host "<your Azure Cosmos account name>.gremlin.cosmosdb.azure.com"
setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"
```
Öppna filen Program.cs och uppdatera variablerna "database och "container" med databas- och containernamnen (som också är grafnamnet) som skapades ovan.

private static string database = "your-database-name"; private static string container = "your-container-or-graph-name";
Spara filen Program.cs.

Du har nu uppdaterat appen med all information som behövs för kommunikation med Azure Cosmos DB.

Kör konsolappen

Tryck på Ctrl + F5 för att köra programmet. Programmet skriver ut både Gremlin-frågekommandona och resultatet i konsolen.

Hörn och gränser som läggs till i tabellen visas i konsolfönstret. Stäng konsolfönstret genom att trycka på RETUR när skriptet har körts.

Bläddra med datautforskaren

Nu kan du gå tillbaka till datautforskaren i Azure Portal och bläddra bland och ställa frågor mot dina nya grafdata.

Den nya databasen visas i fönstret Graphs (Diagram) i Datautforskaren. Expandera databasen och containernoderna och klicka sedan på Diagram.
Klicka på knappen Använd filter för att använda standardfrågan och visa alla hörn i diagrammet. Data som genereras av den här exempelappen visas i fönstret Graphs (Grafer).

Du kan zooma in och ut i diagrammet, du kan expandera diagrammets skärmutrymme, lägga till ytterligare hörn och flytta hörn på skärmytan.

Granska serviceavtal i Azure-portalen

Den Azure Portal övervakar Cosmos DB dataflöde, lagring, tillgänglighet, svarstid och konsekvens för ditt konto. Diagram för mått som är associerade med Azure Cosmos DB Serviceavtal (SLA) visar SLA-värdet jämfört med faktiska prestanda. Den här måttsviten gör övervakningen av dina serviceavtal transparent.

Så här granskar du mått och serviceavtal:

Välj Mått i Cosmos DB-kontots navigeringsmeny.
Välj en flik, till exempel Svarstid, och välj en tidsram till höger. Jämför linjerna Actual och SLA i diagrammen.
Granska måtten på de andra flikarna.

Rensa resurser

När du är klar med din app och Azure Cosmos DB-konto kan du ta bort de Azure-resurser som du skapade så att du inte debiteras mer. Ta bort resurser:

I sökfältet Azure Portal du efter och väljer Resursgrupper.
I listan väljer du den resursgrupp som du skapade för den här snabbstarten.
På sidan Översikt för resursgruppen väljer du Ta bort resursgrupp.
I nästa fönster anger du namnet på den resursgrupp som ska tas bort och väljer sedan Ta bort.

Nästa steg

I den här snabbstarten har du fått lära dig att skapa ett Azure Cosmos DB-konto, skapa en graf med datautforskaren och att köra en app. Nu kan du skapa mer komplexa frågor och implementera kraftfull logik för grafbläddring med Gremlin.

Fråga med hjälp av Gremlin

Snabbstart: Skapa ett .NET Framework- eller Core-program med hjälp Azure Cosmos DB Gremlin API-konto

Betygsätta din upplevelse

Förutsättningar

Skapa ett databaskonto

Lägga till en graf

Klona exempelprogrammet

Granska koden

Uppdatera din anslutningssträng

Kör konsolappen

Bläddra med datautforskaren

Granska serviceavtal i Azure-portalen

Rensa resurser

Nästa steg