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

Makale
01/10/2024

UYGULANANLAR: NoSQL

Kapsayıcılarınızdaki verileri sorgulamak ve tek tek öğeler üzerinde ortak işlemler gerçekleştirmek üzere .NET için NoSQL için Azure Cosmos DB istemci kitaplığını kullanmaya başlayın. Azure Geliştirici CLI'sını kullanarak ortamınıza en düşük çözümü dağıtmak için bu adımları izleyin.

API başvuru belgeleri | Kitaplık kaynak kodu | Paketi (NuGet) | Azure Geliştirici CLI

Önkoşullar

Etkin aboneliği olan bir Azure hesabı. Ücretsiz hesap oluşturun.
GitHub hesabı

Etkin aboneliği olan bir Azure hesabı. Ücretsiz hesap oluşturun.
Azure Geliştirici CLI'sı
Docker Desktop

Ayarlama

Bu projenin geliştirme kapsayıcısını ortamınıza dağıtın. Ardından Azure Geliştirici CLI'sını (azd) kullanarak NoSQL için Azure Cosmos DB hesabı oluşturun ve kapsayıcılı örnek bir uygulama dağıtın. Örnek uygulama örnek verileri yönetmek, oluşturmak, okumak ve sorgulamak için istemci kitaplığını kullanır.

Önemli

GitHub hesapları, hiçbir ücret ödemeden depolama ve çekirdek saat yetkilendirmesi içerir. Daha fazla bilgi için bkz . GitHub hesapları için dahil edilen depolama ve çekirdek saatler.

Projenin kök dizininde bir terminal açın.
kullanarak azd auth loginAzure Geliştirici CLI'sinde kimlik doğrulaması Tercih ettiğiniz Azure kimlik bilgilerini kullanarak CLI'da kimlik doğrulaması yapmak için araç tarafından belirtilen adımları izleyin.
```
azd auth login
```
Projeyi başlatmak için kullanın azd init .
```
azd init
```
Başlatma sırasında benzersiz bir ortam adı yapılandırın.

İpucu

Ortam adı, hedef kaynak grubu adı olarak da kullanılır. Bu hızlı başlangıç için kullanmayı msdocs-cosmos-db-göz önünde bulundurun.
Kullanarak azd upAzure Cosmos DB hesabını dağıtın. Bicep şablonları ayrıca örnek bir web uygulaması dağıtır.
```
azd up
```
Sağlama işlemi sırasında aboneliğinizi ve istediğiniz konumu seçin. Sağlama işleminin tamamlanmasını bekleyin. İşlem yaklaşık beş dakika sürebilir.

Azure kaynaklarınızın sağlanması tamamlandıktan sonra, çalışan web uygulamasının URL'si çıktıya eklenir.

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

Tarayıcıda web uygulamanıza gitmek için konsoldaki URL'yi kullanın. Çalışan uygulamanın çıkışını gözlemleyin.

İstemci kitaplığını yükleme

İstemci kitaplığı NuGet aracılığıyla paket olarak Microsoft.Azure.Cosmos kullanılabilir.

Bir terminal açın ve klasöre /src/web gidin.
```
cd ./src/web
```
Henüz yüklü değilse, kullanarak paketini dotnet add packageyükleyinMicrosoft.Azure.Cosmos.
```
dotnet add package Microsoft.Azure.Cosmos
```
Ayrıca, henüz yüklü değilse paketi yükleyin Azure.Identity .
```
dotnet add package Azure.Identity
```
src/web/Cosmos.Samples.NoSQL.Quickstart.Web.csproj dosyasını açıp gözden geçirerek ve Azure.Identity girdilerinin her ikisinin de var olduğunu Microsoft.Azure.Cosmos doğrulayın.

Nesne modeli

Veri Akışı Adı	Açıklama
CosmosClient	Bu sınıf birincil istemci sınıfıdır ve hesap genelindeki meta verileri veya veritabanlarını yönetmek için kullanılır.
Database	Bu sınıf, hesaptaki bir veritabanını temsil eder.
Container	Bu sınıf öncelikli olarak kapsayıcıda veya kapsayıcıda depolanan öğelerde okuma, güncelleştirme ve silme işlemleri gerçekleştirmek için kullanılır.
PartitionKey	Bu sınıf mantıksal bölüm anahtarını temsil eder. Bu sınıf birçok yaygın işlem ve sorgu için gereklidir.

Şablondaki örnek kod adlı bir veritabanı ve adlı cosmicworksproductskapsayıcıyı kullanır. Kapsayıcı ad products , kategori, miktar, benzersiz tanımlayıcı ve her ürün için satış bayrağı gibi ayrıntıları içerir. Kapsayıcı, mantıksal bölüm anahtarı olarak özelliğini kullanır /category .

İstemcinin kimliğini doğrulama

Çoğu Azure hizmeti için uygulama istekleri yetkilendirilmelidir. DefaultAzureCredential Uygulamalarınız ile NoSQL için Azure Cosmos DB arasında parolasız bağlantı uygulamak için tercih edilen yol olarak türünü kullanın. DefaultAzureCredential birden çok kimlik doğrulama yöntemini destekler ve çalışma zamanında hangi yöntemin kullanılacağını belirler.

Önemli

Ayrıca parolaları, bağlantı dizesi veya diğer kimlik bilgilerini kullanarak Azure hizmetlerine yönelik istekleri doğrudan yetkilendirilebilirsiniz. Ancak bu yaklaşım dikkatli kullanılmalıdır. Geliştiriciler bu gizli dizileri güvenli olmayan bir konumda asla açığa çıkarmamak için dikkatli olmalıdır. Parolaya veya gizli anahtara erişim kazanan herkes veritabanı hizmetinde kimlik doğrulaması yapabilir. DefaultAzureCredential , anahtarları depolama riski olmadan parolasız kimlik doğrulamasına izin vermek için hesap anahtarına göre gelişmiş yönetim ve güvenlik avantajları sunar.

Bu örnek, sınıfın yeni bir örneğini CosmosClient oluşturur ve bir DefaultAzureCredential örnek kullanarak kimlik doğrulaması yapar.

CosmosClient client = new(
    accountEndpoint: builder.Configuration["AZURE_COSMOS_DB_NOSQL_ENDPOINT"]!,
    tokenCredential: new DefaultAzureCredential()
);

Veritabanı alma

adlı cosmicworksmevcut veritabanını almak için kullanınclient.GetDatabase.

Database database = client.GetDatabase("cosmicworks");

Kapsayıcı alma

kullanarak database.GetContainermevcut products kapsayıcıyı alın.

Container container = database.GetContainer("products");

Öğe oluşturma

JSON'da seri hale getirmek istediğiniz tüm üyeleri içeren bir C# kayıt türü oluşturun. Bu örnekte, türün benzersiz bir tanımlayıcısı ve kategori, ad, miktar, fiyat ve satış alanları vardır.

public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);

kullanarak container.UpsertItemkapsayıcıda bir öğe oluşturun. Bu yöntem, zaten varsa öğeyi etkili bir şekilde değiştirerek öğeyi "upsert" eder.

Product item = new(
    id: "68719518391",
    category: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    price: 850.00m,
    clearance: false
);

ItemResponse<Product> response = await container.UpsertItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Öğe okuma

Hem benzersiz tanımlayıcıyı (id) hem de bölüm anahtarı alanlarını kullanarak nokta okuma işlemi gerçekleştirin. Belirli bir öğeyi verimli bir şekilde almak için kullanın container.ReadItem .

ItemResponse<Product> response = await container.ReadItemAsync<Product>(
    id: "68719518391",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Sorgu öğeleri

kullanarak container.GetItemQueryIteratorbir kapsayıcıdaki birden çok öğe üzerinde sorgu gerçekleştirin. Bu parametreli sorguyu kullanarak belirtilen kategorideki tüm öğeleri bulun:

SELECT * FROM products p WHERE p.category = @category

var query = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.category = @category"
)
    .WithParameter("@category", "gear-surf-surfboards");

using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);

kullanarak feed.ReadNextAsyncher sonuç sayfasında döngü yaparak sorgunun sayfalandırılmış sonuçlarını ayrıştırın. Her döngünün başında herhangi bir sonuç olup olmadığını belirlemek için kullanın feed.HasMoreResults .

List<Product> items = new();
double requestCharge = 0d;
while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        items.Add(item);
    }
    requestCharge += response.RequestCharge;
}

Kaynakları temizleme

Örnek uygulamaya veya kaynaklara artık ihtiyacınız kalmadığında, ilgili dağıtımı ve tüm kaynakları kaldırın.

azd down

GitHub Codespaces'ta, depolama alanınızı ve çekirdek yetkilendirmelerinizi en üst düzeye çıkarmak için çalışan kod alanını silin.

Sonraki adım

Öğretici: .NET konsol uygulaması geliştirme