Rövid útmutató: Azure Cosmos DB for Apache Gremlin library for .NET

Cikk
01/10/2024

A KÖVETKEZŐKRE VONATKOZIK: Gremlin

Az Apache Gremlinhez készült Azure Cosmos DB egy teljes körűen felügyelt gráfadatbázis-szolgáltatás, amely a gremlin lekérdezési nyelv használatával implementálja a népszerű Apache Tinkerpopgráf-számítási keretrendszert. A Gremlin API-ja alacsony súrlódási módot kínál a Gremlin használatának megkezdéséhez egy olyan szolgáltatással, amely minimális felügyelet mellett a lehető legtöbb növekedést és skálázást teszi lehetővé.

Ebben a rövid útmutatóban a Gremlin.Net kódtár segítségével csatlakozhat egy újonnan létrehozott Azure Cosmos DB for Gremlin-fiókhoz.

Kódtár forráskódcsomagja | (NuGet)

Előfeltételek

Egy Azure-fiók, aktív előfizetéssel.
- Nincs Azure-előfizetés? Regisztráljon egy ingyenes Azure-fiókra.
- Nem szeretne Azure-előfizetést? Ingyenesen kipróbálhatja az Azure Cosmos DB-t előfizetés nélkül.
.NET (LTS)
- Nincs telepítve a .NET? Próbálja ki ezt a rövid útmutatót a GitHub Codespacesben.
Azure parancssori felület (CLI)

Azure Cloud Shell

Az Azure által üzemeltetett Azure Cloud Shell egy interaktív felület, amelyet a böngészőből használhat. A Bash vagy a PowerShell segítségével is használhatja a Cloud Shellt az Azure-szolgáltatásokhoz. A Cloud Shell előre telepített parancsaival futtathatja a jelen cikkben szereplő kódot anélkül, hogy bármit telepítenie kellene a helyi környezetben.

Az Azure Cloud Shell indítása:

Lehetőség	Példa/hivatkozás
Válassza a Kipróbálás lehetőséget egy kód vagy parancsblokk jobb felső sarkában. A Kipróbálás lehetőség választása nem másolja automatikusan a kódot vagy a parancsot a Cloud Shellbe.
Látogasson el a https://shell.azure.com webhelyre, vagy kattintson a Cloud Shell indítása gombra a böngészőben.
Az Azure Portal jobb felső sarkában található menüben kattintson a Cloud Shell gombra.

Az Azure Cloud Shell használata:

Indítsa el a Cloud Shellt.
A kód vagy parancs másolásához kattintson a Másolás gombra egy kódblokkon (vagy parancsblokkon).
Illessze be a kódot vagy parancsot a Cloud Shell-munkamenetbe a Windows és Linux rendszeren a Ctrl Shift+V billentyűkombinációval+, vagy a Cmd+Shift+V macOS rendszeren való kiválasztásával.
A kód vagy parancs futtatásához válassza az Enter lehetőséget .

Beállítás

Ez a szakasz bemutatja, hogyan hozhat létre API-t Gremlin-fiókhoz, és beállíthat egy .NET-projektet a tár használatával a fiókhoz való csatlakozáshoz.

API létrehozása Gremlin-fiókhoz

A Gremlin API-fiókot a .NET-kódtár használata előtt kell létrehozni. Emellett segít az adatbázis és a gráf helyének megőrzésében is.

Hozzon létre rendszerhéjváltozókat az accountName, a resourceGroupName és a hely számára.

# 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"

Ha még nem tette meg, jelentkezzen be az Azure CLI-be a használatával az login.

Új az group create erőforráscsoport létrehozása az előfizetésben.

az group create \
    --name $resourceGroupName \
    --location $location

Új az cosmosdb create API létrehozása Gremlin-fiókhoz alapértelmezett beállításokkal.
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
Feljegyzés

Azure-előfizetésenként egy ingyenes szintű Azure Cosmos DB-fiókkal rendelkezhet, és a fiók létrehozásakor kell feliratkoznia. Ha ez a parancs nem alkalmazza az ingyenes szintű kedvezményt, ez azt jelenti, hogy az előfizetés egy másik fiókja már engedélyezve lett az ingyenes szinttel.

Kérje le a Gremlin api-végpontjának NEVÉT a fiókhoz a használatával az cosmosdb show.

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"

Keresse meg a KULCSOT a fiók az-cosmosdb-keys-listkulcsainak listájából.

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

Jegyezze fel a NAME és a KEY értékeket. Ezeket a hitelesítő adatokat később fogja használni.

Hozzon létre egy, a következővel elnevezett cosmicworks adatbázistaz cosmosdb gremlin database create: .

az cosmosdb gremlin database create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --name "cosmicworks"

Diagram létrehozása a következő használatávalaz cosmosdb gremlin graph create: . Nevezze el a gráfot products, majd állítsa be az átviteli sebességet 400, és végül állítsa a partíciókulcs elérési útját a következőre /category: .
```
az cosmosdb gremlin graph create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category" \
    --throughput 400
```

Új .NET-konzolalkalmazás létrehozása

Hozzon létre egy .NET-konzolalkalmazást egy üres mappában az előnyben részesített terminál használatával.

Nyissa meg a terminált egy üres mappában.
Használja a dotnet new konzolsablont meghatározó parancsot.
```
dotnet new console
```

A NuGet-csomag telepítése

Adja hozzá a Gremlin.NET NuGet-csomagot a .NET-projekthez.

Használja a dotnet add package NuGet-csomagot meghatározó Gremlin.Net parancsot.
```
dotnet add package Gremlin.Net
```

A .NET-projekt létrehozása a következővel dotnet build: .

dotnet build

Győződjön meg arról, hogy a build hiba nélkül sikeres volt. A build várt kimenetének a következőképpen kell kinéznie:

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)

Környezeti változók konfigurálása

A rövid útmutatóban korábban beszerzett NÉV és URI értékek használatához őrizze meg azokat az alkalmazást futtató helyi gépen lévő új környezeti változókhoz.

A környezeti változó beállításához használja a terminált az értékek COSMOS_ENDPOINTCOSMOS_KEY megőrzéséhez.
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```
Ellenőrizze, hogy a környezeti változók helyesen lettek-e beállítva.
```
printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY
```

A cikkben szereplő kód egy elnevezett cosmicworks adatbázishoz és egy gráfhoz productscsatlakozik. A kód ezután a hozzáadott elemek bejárása előtt csúcsokat és éleket ad hozzá a gráfhoz.

Az ügyfél hitelesítése

A legtöbb Azure-szolgáltatáshoz irányuló alkalmazáskéréseket engedélyezni kell. A Gremlin API-hoz használja a rövid útmutatóban korábban beszerzett NAME és URI értékeket.

Nyissa meg a Program.cs fájlt.
Törölje a fájlban lévő összes meglévő tartalmat.
Adjon hozzá egy használatblokkot a Gremlin.Net.Driver névtérhez.
```
using Gremlin.Net.Driver;
```
Változók létrehozása és accountKey sztringek.accountName Az egyes változók értékeiként tárolja a környezeti és COSMOS_GREMLIN_KEY a COSMOS_GREMLIN_ENDPOINT környezeti változókat.
```
string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
```

Hozzon létre egy új példányt GremlinServer a fiók hitelesítő adatainak használatával.

var server = new GremlinServer(
    hostname: $"{accountName}.gremlin.cosmos.azure.com",
    port: 443,
    username: "/dbs/cosmicworks/colls/products",
    password: $"{accountKey}",
    enableSsl: true
);

Hozzon létre egy új példányt GremlinClient a távoli kiszolgáló hitelesítő adatainak és a GraphSON 2.0 szerializálójának használatával.

using var client = new GremlinClient(
    gremlinServer: server,
    messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);

Csúcspontok létrehozása

Most, hogy az alkalmazás csatlakozott a fiókhoz, használja a standard Gremlin szintaxist csúcspontok létrehozásához.

Parancskiszolgálói oldal futtatására használható SubmitAsync a Gremlin-fiók API-ján. Hozzon létre egy termék csúcspontot a következő tulajdonságokkal:

Érték

Címke 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')"
);
```

Hozzon létre egy második termékcsúcsot az alábbi tulajdonságokkal:

	Érték
Címke	`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')"
);

Hozzon létre egy harmadik termékcsúcsot az alábbi tulajdonságokkal:

	Érték
Címke	`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')"
);

Élek létrehozása

Élek létrehozása a Gremlin szintaxissal a csúcsok közötti kapcsolatok definiálásához.

Hozzon létre egy élet a Montau Turtle Surfboard csereként elnevezett termékből a Kiama classic surfboard termékre.
```
await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))"
);
```
Tipp.

Ez a peremvonal-definíció a szintaxist g.V(['<partition-key>', '<id>']) használja. Másik lehetőségként használhatja g.V('<id>').has('category', '<partition-key>')a következőt:

Hozzon létre egy másik helyettesítő élet ugyanabból a termékből a Bondi Twin Surfboard.

await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518409']))"
);

Lekérdezési csúcsok > élek

A Gremlin szintaxis használatával lépkedhet a gráfon, és felfedezheti a csúcsok közötti kapcsolatokat.

Lépkedje át a gráfot, és keresse meg az Montau Turtle Surfboard összes lecserélt csúcsot.

var results = await client.SubmitAsync<Dictionary<string, object>>(
    requestScript: "g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()"
);

Írja be a konzolra a statikus sztringet [CREATED PRODUCT]\t68719518403. Ezután egy ciklus használatával foreach iterálja át az egyes egyező csúcsokat, és írjon a konzolnak egy üzenetet, amely a megfelelő termékmezőt [REPLACES PRODUCT]id utótagként tartalmazza.
```
Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
{
    Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
}
```

A kód futtatása

Ellenőrizze, hogy az alkalmazás az elvárt módon működik-e az alkalmazás futtatásával. Az alkalmazásnak hibák és figyelmeztetések nélkül kell futnia. Az alkalmazás kimenete tartalmazza a létrehozott és lekérdezett elemek adatait.

Nyissa meg a terminált a .NET projektmappában.
Az alkalmazás futtatásához használható dotnet run .
```
dotnet run
```

Figyelje meg az alkalmazás kimenetét.

[CREATED PRODUCT]       68719518403
[REPLACES PRODUCT]      68719518371
[REPLACES PRODUCT]      68719518409

Az erőforrások eltávolítása

Ha már nincs szüksége a Gremlin-fiók API-jára, törölje a megfelelő erőforráscsoportot.

Hozzon létre egy rendszerhéjváltozót a resourceGroupName számára, ha még nem létezik.
```
# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
```
Az erőforráscsoport törlésére használható az group delete .
```
az group delete \
    --name $resourceGroupName
```

Következő lépés

Adatok létrehozása és lekérdezése az Azure Cosmos DB for Apache Gremlin használatával

	Érték
Címke	`product`
id	`68719518371`
`name`	`Kiama classic surfboard`
`price`	`285.55`
`category`	`surfboards`