Quickstart: Een .NET Framework- of Core-toepassing ontwikkelen met het Azure Cosmos DB Gremlin API-account

Artikel
11/24/2021
11 minuten om te lezen

VAN TOEPASSING OP: Gremlin-API

Azure Cosmos DB is de wereldwijd gedistribueerde multimodel-databaseservice van Microsoft. U kunt snel databases maken van documenten, sleutel/waarde-paren en grafieken en hier query’s op uitvoeren. Deze databases genieten allemaal het voordeel van de globale distributie en horizontale schaalmogelijkheden die ten grondslag liggen aan Azure Cosmos DB.

Deze quickstart laat zien hoe u een Gremlin-API-account van Azure Cosmos DB, een database en een grafiek (container) kunt maken met behulp van Azure Portal. U gaat vervolgens een console-app ontwikkelen en uitvoeren met behulp van het opensourcestuurprogramma Gremlin.Net.

Vereisten

Als u Visual Studio 2019 nog niet hebt geïnstalleerd, kunt u het downloaden en de gratis Community Edition van Visual Studio 2019 gebruiken. Zorg ervoor dat u Azure-ontwikkeling inschakelt tijdens de installatie van Visual Studio.

Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.

Een databaseaccount maken

Meld u in een nieuw browservenster aan bij Azure Portal.
Selecteer Een resource maken in het menu aan de linkerkant.
Selecteer op de pagina Nieuw Databases > Azure Cosmos DB.

Voer op de pagina Azure Cosmos DB-account maken de instellingen in voor het nieuwe Azure Cosmos DB-account.

Instelling	Waarde	Beschrijving
Abonnement	Abonnementsnaam	Selecteer het Azure-abonnement dat u voor dit Azure Cosmos-account wilt gebruiken.
Resourcegroep	Naam van de resourcegroep	Selecteer een resourcegroep of selecteer Nieuwe maken en voer vervolgens een unieke naam in voor de nieuwe resourcegroep.
Accountnaam	Voer een unieke naam in	Voer een unieke naam in om uw Azure Cosmos DB-account te identificeren. Uw account-URI wordt gremlin.azure.com toegevoegd aan uw unieke accountnaam. De accountnaam mag alleen kleine letters, cijfers en afbreekstreelopen (-) gebruiken en moet tussen de 3 en 44 tekens lang zijn.
API	Gremlin (grafiek)	De API bepaalt het type te maken account. Azure Cosmos DB heeft vijf API's: Core(SQL) voor documentdatabases, Gremlin voor grafiekdatabases, MongoDB voor documentdatabases, Azure Table en Cassandra. U moet voor elke API een afzonderlijk account maken. Selecteer Gremlin (grafiek) , omdat u in deze snelstartgids een tabel maakt die geschikt is voor de Gremlin-API. Meer informatie over de Gremlin API.
Locatie	De regio het dichtst bij uw gebruikers	Selecteer een geografische locatie waar u het Azure Cosmos DB-account wilt hosten. Gebruik de locatie die zich het dichtst bij uw gebruikers bevindt, zodat ze de snelst mogelijke toegang tot de gegevens hebben.
Capaciteitsmodus	Ingerichte doorvoer of serverloos	Selecteer Ingerichte doorvoer om een account te maken in de modus Ingerichte doorvoer. Selecteer Serverloos om een account te maken in de modus serverloos.
Niveaukorting op gratis laag van Azure Cosmos DB toepassen	Toepassen of niet toepassen	Met Azure Cosmos DB gratis laag krijgt u de eerste 1000 RU/s en 25 GB aan opslagruimte gratis in een account. Meer informatie over de gratis laag.

Notitie

U kunt per Azure-abonnement maximaal één gratis laag voor het Azure Cosmos DB-account hebben, en u moet zich aanmelden wanneer u het account maakt. Als u de optie voor het toepassen van de korting voor gratis lagen niet ziet, betekent dit dat er al een ander account in het abonnement is ingeschakeld met een gratis laag.

De pagina Nieuw account voor Azure Cosmos DB

Configureer de volgende gegevens op het tabblad Globale distributie. U kunt de standaardwaarden voor deze quickstart laten staan:

Instelling	Waarde	Beschrijving
Georedundantie	Uitschakelen	Schakel globale distributie voor uw account in of uit door uw regio te koppelen met een koppelingsregio. U kunt later meer regio's aan uw account toevoegen.
Schrijven voor meerdere regio's	Uitschakelen	Dankzij de mogelijkheid voor schrijfbewerkingen in meerdere regio's kunt over de hele wereld profiteren van de ingerichte doorvoer voor uw databases en containers.

Notitie

De volgende opties zijn niet beschikbaar als u Serverloos als Capaciteitsmodus selecteert:

Korting voor gratis lagen toepassen
Geografische redundantie
Schrijven voor meerdere regio's

Optioneel kunt u aanvullende details configureren op de volgende tabbladen:
- Netwerken: configureer de toegang vanuit een virtueel netwerk.
- Back-upbeleid: configureer het periodieke of continue back-upbeleid.
- Versleuteling: gebruik een door de service beheerde sleutel of een door de klant beheerde sleutel.
- Tags: tags zijn naam/waarde-paren waarmee u resources kunt categoriseren en geconsolideerde facturering kunt weergeven door dezelfde tag toe te passen op meerdere resources en resourcegroepen.
Selecteer Controleren + maken.
Het duurt enkele minuten om het account te maken. Wacht tot de portal de pagina Gefeliciteerd! Uw Azure Cosmos DB-account is gemaakt weergeeft.

Een graaf toevoegen

U kunt nu het hulpprogramma Data Explorer in Azure Portal gebruiken om een grafiekdatabase te maken.

Selecteer Data Explorer > Nieuwe grafiek.

Uiterst rechts wordt het gebied Grafiek toevoegen weergegeven. Mogelijk moet u naar rechts scrollen om het te bekijken.

Geef op de pagina Grafiek toevoegen de instellingen voor de nieuwe grafiek op.

Instelling	Voorgestelde waarde	Beschrijving
Database-id	voorbeelddatabase	Voer sample-database in als de naam voor de nieuwe database. Databasenamen moeten tussen de 1 en 255 tekens zijn en mogen geen `/ \ # ?` bevatten of eindigen op een spatie.
Doorvoer	400 RU‘s	Wijzig de doorvoer in 400 aanvraageenheden per seconde (RU/s). U kunt de doorvoer later opschalen als u de latentie wilt beperken.
Grafiek-id	voorbeeldgrafiek	Voer sample-graph in als de naam voor uw nieuwe verzameling. Voor namen van grafieken gelden dezelfde tekenvereisten als voor database-id's.
Partitiesleutel	/pk	Alle Cosmos DB-accounts hebben een partitiesleutel nodig voor horizontale schaalaanpassing. Meer informatie over het selecteren van een geschikte partitiesleutel in het artikel over het partitioneren van graafgegevens.

Zodra het formulier is ingevuld, selecteert u OK.

De voorbeeldtoepassing klonen

We gaan nu een Gremlin-API-app klonen vanaf GitHub, de verbindingsreeks instellen en de app uitvoeren. U zult zien hoe gemakkelijk het is om op een programmatische manier met gegevens te werken.

Open een opdrachtprompt, maak een nieuwe map met de naam git-samples en sluit vervolgens de opdrachtprompt.
```
md "C:\git-samples"
```
Open een git-terminalvenster, bijvoorbeeld git bash, en gebruik de cd-opdracht om naar de nieuwe map te gaan voor het installeren van de voorbeeld-app.
```
cd "C:\git-samples"
```
Voer de volgende opdracht uit om de voorbeeldopslagplaats te klonen. Deze opdracht maakt een kopie van de voorbeeld-app op uw computer.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-graph-gremlindotnet-getting-started.git
```
Open vervolgens Visual Studio en open het oplossingenbestand.
Herstel de NuGet-pakketten in het project. Dit geldt voor het stuurprogramma Gremlin.Net, evenals het pakket Newtonsoft.Json.
U kunt het stuurprogramma ook Gremlin.Net@v3.4.6 handmatig installeren met nuget-pakketbeheer of het nuget-opdrachtregelprogramma:
```
nuget install Gremlin.NET -Version 3.4.6
```

Notitie

De Gremlin-API ondersteunt momenteel alleen Gremlin.Net v3.4.6. Als u de nieuwste versie installeert, ontvangt u fouten wanneer u de service gebruikt.

De code bekijken

Deze stap is optioneel. Als u wilt weten hoe de databaseresources in de code worden gemaakt, kunt u de volgende codefragmenten bekijken. Als u deze stap wilt overslaan, kunt u verdergaan naar Uw verbindingsreeks bijwerken.

De volgende codefragmenten zijn allemaal afkomstig uit het bestand Program.cs.

Stel uw verbindingsparameters in op basis van het hierboven gemaakte account:

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

De uit te voeren Gremlin-opdrachten worden vermeld in een woordenlijst:

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

Maak een nieuwe GremlinServer en GremlinClient-verbindingsobjecten met de bovenstaande parameters:

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

Voer elke Gremlin-query uit met behulp van het GremlinClient-object met een asynchrone taak. U kunt de Gremlin-query's in de in de vorige stap gedefinieerde woordenlijst lezen en uitvoeren. Haal het resultaat later op en lees de waarden, die zijn opgemaakt als een woordenlijst, met behulp van de JsonSerializer-klasse vanuit het Newtonsoft.Json-pakket:

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

Uw verbindingsreeks bijwerken

Ga nu terug naar Azure Portal om de verbindingsreeksinformatie op te halen en kopieer deze in de app.

Vanuit Azure Portal gaat u naar uw grafiekdatabaseaccount. In het tabblad Overzicht ziet u twee eindpunten:

.NET SDK URI: deze waarde wordt gebruikt wanneer u verbinding met het grafiekaccount maakt met behulp van de Microsoft.Azure.Graphs-bibliotheek.

Gremlin-eindpunt: deze waarde wordt gebruikt wanneer u verbinding met het grafiekaccount maakt met behulp van de Gremlin.Net-bibliotheek.

Als u dit voorbeeld wilt uitvoeren, moet u de waarde voor het Gremlin-eindpunt kopiëren, het poortnummer aan het eind verwijderen, zodat de URI https://<your cosmos db account name>.gremlin.cosmosdb.azure.com wordt. De eindpuntwaarde moet er als volgt uitzien testgraphacct.gremlin.cosmosdb.azure.com
Ga vervolgens naar het tabblad Sleutels en kopieer de waarde voor PRIMAIRE SLEUTEL uit Azure Portal.
Nadat u de URI en PRIMAIRE SLEUTEL van uw account hebt gekopieerd, slaat u deze op in een nieuwe omgevingsvariabele op de lokale computer waarop de toepassing wordt uitgevoerd. Als u de omgevingsvariabele wilt instellen, opent u een opdrachtpromptvenster en voert u de volgende opdracht uit. Zorg ervoor dat u de waarden voor < Your_Azure_Cosmos_account_URI > en < Your_Azure_Cosmos_account_PRIMARY_KEY> vervangt.
```
setx Host "<your Azure Cosmos account name>.gremlin.cosmosdb.azure.com"
setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"
```
Open het bestand Program.cs en werk de variabelen database en container bij met de database en container (dit is ook de naam van de grafiek) die hierboven zijn gemaakt.

private static string database = "your-database-name"; private static string container = "your-container-or-graph-name";
Sla het bestand Program.cs op.

U hebt uw app nu bijgewerkt met alle informatie die nodig is voor de communicatie met Azure Cosmos DB.

De console-app uitvoeren

Klik op Ctrl+F5 om de toepassing uit te voeren. De toepassing drukt zowel de Gremlin-queryopdrachten als de -resultaten af in de console.

In het consolevenster worden de hoekpunten en randen weergegeven die aan de graaf worden toegevoegd. Zodra het script is voltooid, drukt u op Enter om het consolevenster te sluiten.

Bladeren met Data Explorer

U kunt nu teruggaan naar Data Explorer in Azure Portal en door uw nieuwe graafgegevens bladeren en er query’s op uitvoeren.

De nieuwe database wordt in Data Explorer weergegeven in het deelvenster Grafieken. Vouw de database en containerknooppunten uit en klik op Graph.
Klik op de knop Filter toepassen om de standaardquery te gebruiken om alle hoekpunten in de grafiek weer te geven. De gegevens die worden gegenereerd door de voorbeeldapp worden weergegeven in het deelvenster Grafen.

U kunt op de grafiek in- en uitzoomen, u kunt u de grafiek uitvouwen voor meer ruimte, extra hoekpunten toevoegen en hoekpunten verplaatsen in de weergaveruimte.

SLA’s bekijken in Azure Portal

De doorvoer, opslag, beschikbaarheid, latentie en consistentie van uw Cosmos DB-account worden in Azure Portal bewaakt. Grafieken voor metrische gegevens die zijn gekoppeld aan een Azure Cosmos DB Service Level Agreement (SLA) tonen de SLA-waarde in vergelijking met de werkelijke prestaties. Deze suite van metrische gegevens zorgt voor een transparante bewaking van uw SLA's.

Metrische gegevens en SLA's weergeven:

Selecteer Metrische gegevens in het navigatiemenu van uw Cosmos DB-account.
Selecteer een tabblad, bijvoorbeeld Latentie, en selecteer aan de rechterkant een tijdsbestek. Vergelijk de lijnen Werkelijk en SLA in de grafieken met elkaar.
Bekijk de metrische gegevens op de andere tabbladen.

Resources opschonen

Wanneer u uw app en Azure Cosmos DB-account niet meer nodig hebt, kunt u de Azure-resources die u hebt gemaakt, verwijderen zodat er geen kosten meer voor in rekening worden gebracht. Om de resources te verwijderen:

Zoek en selecteer Resourcegroepen in de zoekbalk op Azure Portal.
Selecteer de resourcegroep die u eerder voor deze quickstart hebt gemaakt uit de lijst.
Selecteer Resourcegroep verwijderen op de pagina Overzicht van de resourcegroep.
Selecteer in het volgende venster de naam van de resourcegroep die u wilt verwijderen en selecteer vervolgens Verwijderen.

Volgende stappen

In deze Quick Start hebt u geleerd hoe u een Azure Cosmos DB-account kunt maken, hebt u een graaf gemaakt met Data Explorer en hebt u een app uitgevoerd. U kunt nu complexere query's maken en met Gremlin krachtige logica implementeren om door een graaf te gaan.

Query’s uitvoeren met Gremlin

Quickstart: Een .NET Framework- of Core-toepassing ontwikkelen met het Azure Cosmos DB Gremlin API-account

Beoordeel uw ervaring

Vereisten

Een databaseaccount maken

Een graaf toevoegen

De voorbeeldtoepassing klonen

De code bekijken

Uw verbindingsreeks bijwerken

De console-app uitvoeren

Bladeren met Data Explorer

SLA’s bekijken in Azure Portal

Resources opschonen

Volgende stappen