Hızlı Başlangıç: .NET için Apache Gremlin kitaplığı için Azure Cosmos DB

Makale
08/15/2024

ŞUNLAR IÇIN GEÇERLIDIR: Gremlin

Apache Gremlin için Azure Cosmos DB, Gremlin sorgu dilini kullanan popüler Apache Tinkerpopbir graf bilgi işlem çerçevesi uygulayan tam olarak yönetilen bir graf veritabanı hizmetidir. Gremlin API'si, minimum yönetimle gremlin'i istediğiniz kadar büyüyebilen ve ölçeği genişletebilen bir hizmetle kullanmaya başlamanız için düşük uyuşmalı bir yol sunar.

Bu hızlı başlangıçta kitaplığını Gremlin.Net kullanarak yeni oluşturulan Gremlin için Azure Cosmos DB hesabına bağlanacaksınız.

Kitaplık kaynak kodu | Paketi (NuGet)

Önkoşullar

Etkin aboneliği olan bir Azure hesabı.
- Azure aboneliği yok mu? Ücretsiz bir Azure hesabına kaydolun.
- Azure aboneliği istemiyor musunuz? Abonelik gerektirmeden Azure Cosmos DB'i ücretsiz deneyebilirsiniz.
.NET (LTS)
- .NET yüklü değil mi? GitHub Codespaces'da bu hızlı başlangıcı deneyin.
Azure Komut Satırı Arabirimi (CLI)

Azure Cloud Shell

Azure, tarayıcınız aracılığıyla kullanabileceğiniz etkileşimli bir kabuk ortamı olan Azure Cloud Shell'i barındırıyor. Azure hizmetleriyle çalışmak için Cloud Shell ile Bash veya PowerShell kullanabilirsiniz. Yerel ortamınıza herhangi bir şey yüklemek zorunda kalmadan bu makaledeki kodu çalıştırmak için Cloud Shell önceden yüklenmiş komutlarını kullanabilirsiniz.

Azure Cloud Shell'i başlatmak için:

Seçenek	Örnek/Bağlantı
Kodun veya komut bloğunun sağ üst köşesindeki Deneyin'i seçin. Deneyin seçildiğinde kod veya komut otomatik olarak Cloud Shell'e kopyalanmaz.
https://shell.azure.comadresine gidin veya Cloud Shell'i tarayıcınızda açmak için Cloud Shell'i Başlat düğmesini seçin.
Azure portalının sağ üst kısmındaki menü çubuğunda Cloud Shell düğmesini seçin.

Azure Cloud Shell'i kullanmak için:

Cloud Shell'i başlatın.
Kodu veya komutu kopyalamak için kod bloğundaki (veya komut bloğundaki) Kopyala düğmesini seçin.
Windows ve Linux'ta Ctrl+Shift V'yi seçerek veya macOS üzerinde Cmd+Shift++V'yi seçerek kodu veya komutu Cloud Shell oturumuna yapıştırın.
Kodu veya komutu çalıştırmak için Enter'ı seçin.

Ayarlama

Bu bölümde Gremlin hesabı için API oluşturma ve hesaba bağlanmak üzere kitaplığı kullanacak bir .NET projesi ayarlama adımları açıklanmıştır.

Gremlin hesabı için API oluşturma

.NET kitaplığını kullanmadan önce Gremlin hesabı için API oluşturulmalıdır. Ayrıca, veritabanının ve grafiğin yerinde olması da yardımcı olur.

accountName, resourceGroupName ve location için kabuk değişkenleri oluşturun.

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

Henüz yapmadıysanız kullanarak az loginAzure CLI'da oturum açın.
Aboneliğinizde yeni bir kaynak grubu oluşturmak için kullanın az group create .
```
az group create \
    --name $resourceGroupName \
    --location $location
```
Varsayılan ayarlarla Gremlin hesabı için yeni bir API oluşturmak için kullanın az cosmosdb create .
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
Not

Azure aboneliği başına bir ücretsiz katman Azure Cosmos DB hesabına sahip olabilirsiniz. Bunu hesabı oluştururken kabul etmeniz gerekir. Bu komut ücretsiz katman indirimini uygulayamazsa, bu abonelikteki başka bir hesabın ücretsiz katmanla zaten etkinleştirildiği anlamına gelir.

kullanarak az cosmosdb showhesabın Gremlin uç nokta ADı API'sini alın.

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

ile hesabın az-cosmosdb-keys-listanahtar listesinden KEY değerini bulun.

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

AD ve ANAHTAR değerlerini kaydedin. Bu kimlik bilgilerini daha sonra kullanacaksınız.

kullanarak az cosmosdb gremlin database createadlı cosmicworks bir veritabanı oluşturun.

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

kullanarak az cosmosdb gremlin graph createbir grafik oluşturun. Grafı productsadlandırın, ardından aktarım hızını olarak 400ayarlayın ve son olarak bölüm anahtarı yolunu olarak /categoryayarlayın.

az cosmosdb gremlin graph create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category" \
    --throughput 400

Yeni bir .NET konsol uygulaması oluşturma

Tercih ettiğiniz terminali kullanarak boş bir klasörde .NET konsol uygulaması oluşturun.

Terminalinizi boş bir klasörde açın.
dotnet new Konsol şablonunu belirten komutunu kullanın.
```
dotnet new console
```

NuGet paketini yükleme

Gremlin.NET NuGet paketini .NET projesine ekleyin.

dotnet add package NuGet paketini belirten Gremlin.Net komutunu kullanın.
```
dotnet add package Gremlin.Net
```

kullanarak dotnet build.NET projesini oluşturun.

dotnet build

Derlemenin hata olmadan başarılı olduğundan emin olun. Derlemeden beklenen çıkış şöyle görünmelidir:

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)

Ortam değişkenlerini yapılandırma

Bu hızlı başlangıçta daha önce elde edilen AD ve URI değerlerini kullanmak için, bunları uygulamayı çalıştıran yerel makinedeki yeni ortam değişkenlerinde kalıcı hale getirin.

Ortam değişkenini ayarlamak için, değerleri sırasıyla ve COSMOS_KEY olarak COSMOS_ENDPOINT kalıcı hale getirmek için terminalinizi kullanın.
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```

Ortam değişkenlerinin doğru ayarlandığını doğrulayın.

printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY

Bu makaledeki kod adlı bir veritabanına ve adlı cosmicworks productsbir grafa bağlanır. Kod daha sonra eklenen öğeleri geçirmeden önce grafiğe köşeler ve kenarlar ekler.

İstemcinin kimliğini doğrulama

Çoğu Azure hizmeti için uygulama istekleri yetkilendirilmelidir. Gremlin API'sinde , bu hızlı başlangıçta daha önce elde edilen AD ve URI değerlerini kullanın.

Program.cs dosyasını açın.
Dosyadaki mevcut tüm içeriği silin.
Ad alanı için Gremlin.Net.Driver bir using bloğu ekleyin.
```
using Gremlin.Net.Driver;
```
Değişken oluşturma accountName ve accountKey dize oluşturma. COSMOS_GREMLIN_ENDPOINT ve COSMOS_GREMLIN_KEY ortam değişkenlerini ilgili her değişkenin değerleri olarak depolayın.
```
string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
```

Hesabın GremlinServer kimlik bilgilerini kullanarak yeni bir örneği oluşturun.

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

Uzak sunucu kimlik bilgilerini ve GraphSON 2.0 seri hale getiricisini kullanarak yeni bir örneği GremlinClient oluşturun.

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

Köşe oluşturma

Uygulama hesaba bağlı olduğuna göre köşe oluşturmak için standart Gremlin söz dizimini kullanın.

Gremlin hesabı için API'de sunucu tarafında bir komut çalıştırmak için kullanın SubmitAsync . Aşağıdaki özelliklere sahip bir ürün köşesi oluşturun:

Değer

etiket 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')"
);
```

Şu özelliklere sahip ikinci bir ürün köşesi oluşturun:

	Değer
etiket	`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')"
);

Şu özelliklere sahip üçüncü bir ürün köşesi oluşturun:

	Değer
etiket	`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')"
);

Kenar oluşturma

Köşeler arasındaki ilişkileri tanımlamak için Gremlin söz dizimini kullanarak kenarlar oluşturun.

Yerine Kiama classic surfboard ürün olarak Montau Turtle Surfboard adlandırılan üründen bir kenar oluşturun.
```
await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))"
);
```
İpucu

Bu kenar tanımlayıcısı söz dizimini g.V(['<partition-key>', '<id>']) kullanır. Alternatif olarak, kullanabilirsiniz g.V('<id>').has('category', '<partition-key>').

Başka bir oluşturma, aynı üründeki kenarı ile Bondi Twin Surfboarddeğiştirir.

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

Sorgu köşeleri ve kenarlar

Grafta geçiş yapmak ve köşeler arasındaki ilişkileri bulmak için Gremlin söz dizimini kullanın.

Grafı çapraz geçin ve yerini alan Montau Turtle Surfboard tüm köşeleri bulun.

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

Konsola statik dizesini [CREATED PRODUCT]\t68719518403yazın. Ardından, bir foreach döngü kullanarak eşleşen her köşeyi yineleyin ve konsola ile [REPLACES PRODUCT] başlayan ve eşleşen ürün id alanını sonek olarak içeren bir ileti yazın.
```
Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
{
    Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
}
```

Kodu çalıştırma

Uygulamayı çalıştırarak uygulamanızın beklendiği gibi çalıştığını doğrulayın. Uygulama hiçbir hata veya uyarı olmadan yürütülmelidir. Uygulamanın çıktısı, oluşturulan ve sorgulanan öğeler hakkındaki verileri içerir.

Terminali .NET proje klasöründe açın.
Uygulamayı çalıştırmak için kullanın dotnet run .
```
dotnet run
```

Uygulamanın çıkışını gözlemleyin.

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

Kaynakları temizleme

Gremlin hesabı için API'ye artık ihtiyacınız kalmadığında ilgili kaynak grubunu silin.

Henüz yoksa resourceGroupName için bir kabuk değişkeni oluşturun.

# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"

Kaynak grubunu silmek için kullanın az group delete .
```
az group delete \
    --name $resourceGroupName
```

Sonraki adım

Apache Gremlin için Azure Cosmos DB kullanarak veri oluşturma ve sorgulama

Aracılığıyla paylaş