.NET kullanarak NoSQL için Azure Cosmos DB ile çalışmaya başlama
UYGULANANLAR: NoSQL
Bu makalede, .NET SDK'sını kullanarak NoSQL için Azure Cosmos DB'ye nasıl bağlanabileceğiniz gösterilmektedir. Bağlandıktan sonra veritabanları, kapsayıcılar ve öğeler üzerinde işlemler gerçekleştirebilirsiniz.
Paket (NuGet) | Örnekler | API başvurusu | Kitaplık kaynak kodu | Geri Bildirim Ver
Önkoşullar
- Etkin aboneliği olan bir Azure hesabı. Ücretsiz hesap oluşturun.
- NoSQL için Azure Cosmos DB hesabı. NoSQL hesabı için bir API oluşturun.
- .NET 6.0 veya üzeri
- Azure Komut Satırı Arabirimi (CLI) veya Azure PowerShell
Projenizi ayarlama
.NET konsol uygulamasını oluşturma
konsol şablonuyla komutunu kullanarak dotnet new
yeni bir .NET uygulaması oluşturun.
dotnet new console
komutunu kullanarak Microsoft.Azure.Cosmos NuGet paketini içeri aktarındotnet add package
.
dotnet add package Microsoft.Azure.Cosmos
komutuyla dotnet build
projeyi oluşturun.
dotnet build
NoSQL için Azure Cosmos DB'ye bağlanma
Azure Cosmos DB'nin NoSQL API'sine bağlanmak için sınıfının bir örneğini CosmosClient
oluşturun. Bu sınıf, veritabanlarında tüm işlemleri gerçekleştirmek için başlangıç noktasıdır. CosmosClient sınıfını kullanarak NoSQL hesabına yönelik bir API'ye bağlanmanın üç temel yolu vardır:
- NoSQL uç noktası ve okuma/yazma anahtarı için API ile bağlanma
- NoSQL bağlantı dizesi için API ile bağlanma
- Microsoft Entra Id ile bağlanma
Uç nokta ve anahtarla bağlanma
CosmosClient için en yaygın oluşturucunun iki parametresi vardır:
Parametre | Örnek değer | Açıklama |
---|---|---|
accountEndpoint |
COSMOS_ENDPOINT ortam değişkeni |
Tüm istekler için kullanılacak NoSQL uç noktası API'si |
authKeyOrResourceToken |
COSMOS_KEY ortam değişkeni |
Kimlik doğrulaması sırasında kullanılacak hesap anahtarı veya kaynak belirteci |
Hesap uç noktanızı ve anahtarınızı alma
resourceGroupName için bir kabuk değişkeni oluşturun.
# Variable for resource group name resourceGroupName="msdocs-cosmos-dotnet-howto-rg"
az cosmosdb list
Komutunu kullanarak kaynak grubunuzdaki ilk Azure Cosmos DB hesabının adını alın ve accountName kabuk değişkeninde depolayın.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
komutunu kullanarak hesap için NoSQL uç nokta URI'sine yönelik API'yi
az cosmosdb show
alın.az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "documentEndpoint"
komutuyla hesabın anahtar listesinden BİRİnCİl ANAHTAR'ı
az-cosmosdb-keys-list
bulun.az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"
URI ve BİRİnCİl ANAHTAR değerlerini kaydedin. Bu kimlik bilgilerini daha sonra kullanacaksınız.
.NET kodunuz içinde URI ve BİRİnCİl ANAHTAR değerlerini kullanmak için, bunları uygulamayı çalıştıran yerel makinedeki yeni ortam değişkenlerinde kalıcı hale getirin.
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
Hesap uç noktası ve anahtarıyla CosmosClient oluşturma
ve ortam değişkenlerini parametre olarak kullanarak CosmosClient sınıfının COSMOS_ENDPOINT
COSMOS_KEY
yeni bir örneğini oluşturun.
// New instance of CosmosClient class using an endpoint and key string
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);
bağlantı dizesi ile bağlanma
CosmosClient için başka bir oluşturucu yalnızca tek bir parametre içerir:
Parametre | Örnek değer | Açıklama |
---|---|---|
accountEndpoint |
COSMOS_ENDPOINT ortam değişkeni |
Tüm istekler için kullanılacak NoSQL uç noktası API'si |
connectionString |
COSMOS_CONNECTION_STRING ortam değişkeni |
NoSQL hesabı için API'ye bağlantı dizesi |
Hesap bağlantı dizesi alma
az cosmosdb list
Komutunu kullanarak kaynak grubunuzdaki ilk Azure Cosmos DB hesabının adını alın ve accountName kabuk değişkeninde depolayın.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
komutuyla hesabın bağlantı dizesi listesinden BİRİnCİl BAĞLANTI DIZESİ'ni
az-cosmosdb-keys-list
bulun.az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "connection-strings" \ --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
.NET kodunuz içinde BİRİnCİl BAĞLANTI DIZESİ değerini kullanmak için, uygulamayı çalıştıran yerel makinede yeni bir ortam değişkeninde kalıcı hale getirmek.
$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"
bağlantı dizesi ile CosmosClient oluşturma
Tek parametre olarak ortam değişkeniyle COSMOS_CONNECTION_STRING
CosmosClient sınıfının yeni bir örneğini oluşturun.
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);
Microsoft kimlik platformu kullanarak bağlanma
Microsoft kimlik platformu ve Microsoft Entra Id kullanarak NoSQL hesabına yönelik API'nize bağlanmak için bir güvenlik sorumlusu kullanın. Sorumlunun tam türü, uygulama kodunuzu nerede barındırdığınıza bağlıdır. Aşağıdaki tablo bir hızlı başvuru kılavuzu görevi görür.
Uygulamanın çalıştığı yer | Güvenlik sorumlusu |
---|---|
Yerel makine (geliştirme ve test) | Kullanıcı kimliği veya hizmet sorumlusu |
Azure | Yönetilen kimlik |
Azure dışındaki sunucular veya istemciler | Hizmet sorumlusu |
Azure.Identity'i içeri aktarma
Azure.Identity NuGet paketi, tüm Azure SDK kitaplıkları arasında paylaşılan temel kimlik doğrulama işlevlerini içerir.
komutunu kullanarak Azure.Identity NuGet paketini içeri aktarındotnet add package
.
dotnet add package Azure.Identity
komutunu kullanarak dotnet build
projeyi yeniden oluşturun.
dotnet build
Kod düzenleyicinizde ve Azure.Identity
ad alanları için Azure.Core
using yönergelerini ekleyin.
using Azure.Core;
using Azure.Identity;
Varsayılan kimlik bilgisi uygulamasıyla CosmosClient oluşturma
Yerel bir makinede test ediyorsanız veya uygulamanız yönetilen kimlikler için doğrudan destekle Azure hizmetlerinde çalışacaksa bir örnek oluşturarak OAuth DefaultAzureCredential
belirteci alın.
Bu örnekte örneği, SDK'lar arasında yeniden kullanılabilen daha genel bir tür olduğundan türünde bir değişkene TokenCredential
kaydettik.
// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();
Ortam değişkeni ve TokenCredential nesnesini parametre olarak kullanarak CosmosClient sınıfının COSMOS_ENDPOINT
yeni bir örneğini oluşturun.
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
tokenCredential: credential
);
Özel kimlik bilgisi uygulamasıyla CosmosClient oluşturma
Uygulamayı Azure dışına dağıtmayı planlıyorsanız, .NET için Azure.Identity istemci kitaplığındaki diğer sınıfları kullanarak bir OAuth belirteci alabilirsiniz. Bu diğer sınıflar da sınıfından TokenCredential
türetilir.
Bu örnekte, istemci ve kiracı tanımlayıcılarının yanı sıra bir istemci gizli dizisi kullanarak bir örnek oluştururuz ClientSecretCredential
.
// Custom credential class for servers and clients outside of Azure
TokenCredential credential = new ClientSecretCredential(
tenantId: Environment.GetEnvironmentVariable("AAD_TENANT_ID")!,
clientId: Environment.GetEnvironmentVariable("AAD_CLIENT_ID")!,
clientSecret: Environment.GetEnvironmentVariable("AAD_CLIENT_SECRET")!,
options: new TokenCredentialOptions()
);
Bir uygulamayı Microsoft Entra Id'ye kaydederken istemci kimliğini, kiracı kimliğini ve istemci gizli dizisini alabilirsiniz. Microsoft Entra uygulamalarını kaydetme hakkında daha fazla bilgi için bkz. Uygulamayı Microsoft kimlik platformu kaydetme.
Ortam değişkeni ve TokenCredential nesnesini parametre olarak kullanarak CosmosClient sınıfının COSMOS_ENDPOINT
yeni bir örneğini oluşturun.
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
tokenCredential: credential
);
Uygulamanızı derleme
Uygulamanızı oluştururken kodunuz öncelikli olarak dört tür kaynakla etkileşim kurar:
Azure Cosmos DB verileriniz için benzersiz üst düzey ad alanı olan NoSQL hesabı için API.
Hesabınızdaki kapsayıcıları düzenleyen veritabanları.
Veritabanınızdaki tek tek öğeler kümesini içeren kapsayıcılar.
Kapsayıcınızdaki bir JSON belgesini temsil eden öğeler.
Aşağıdaki diyagramda bu kaynaklar arasındaki ilişki gösterilmektedir.
En üstte bir Azure Cosmos DB hesabını gösteren hiyerarşik diyagram. Hesabın iki alt veritabanı düğümü vardır. Veritabanı düğümlerinden biri iki alt kapsayıcı düğümü içerir. Diğer veritabanı düğümü tek bir alt kapsayıcı düğümü içerir. Bu tek kapsayıcı düğümünde üç alt öğe düğümü vardır.
Her kaynak türü, ilişkili bir veya daha fazla .NET sınıfıyla temsil edilir. En yaygın sınıfların listesi aşağıdadır:
Sınıf | Açıklama |
---|---|
CosmosClient |
Bu sınıf, Azure Cosmos DB hizmeti için istemci tarafı mantıksal gösterimi sağlar. İstemci nesnesi, hizmette istekleri yapılandırmak ve yürütmek için kullanılır. |
Database |
Bu sınıf, hizmette henüz var olabilen veya var olmayan bir veritabanına başvurudur. Veritabanına erişmeye veya ona karşı bir işlem gerçekleştirmeye çalıştığınızda veritabanı sunucu tarafında doğrulanır. |
Container |
Bu sınıf, hizmette henüz mevcut olmayan bir kapsayıcıya başvurudur. Kapsayıcıyla çalışmaya çalıştığınızda sunucu tarafı doğrulanır. |
Aşağıdaki kılavuzlarda, uygulamanızı derlemek için bu sınıfların her birinin nasıl kullanılacağı gösterilmektedir.
Kılavuz | Açıklama |
---|---|
Veritabanı oluşturma | Veritabanları oluşturma |
Kapsayıcı oluşturma | Kapsayıcılar oluşturun |
Öğe okuma | Belirli bir öğeyi nokta okuma |
Sorgu öğeleri | Birden çok öğeyi sorgulama |
Ayrıca bkz.
Sonraki adımlar
Artık NoSQL hesabı için bir API'ye bağlandığınıza göre, veritabanlarını oluşturmak ve yönetmek için sonraki kılavuzu kullanın.
Geri Bildirim
https://aka.ms/ContentUserFeedback.
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz.Gönderin ve geri bildirimi görüntüleyin