Hızlı Başlangıç: .NET tablosu için Azure Cosmos DB

ŞUNLAR IÇIN GEÇERLIDIR: Tablo

Bu hızlı başlangıçta bir .NET uygulamasından Tablo için Azure Cosmos DB'yi kullanmaya başlama adımları gösterilmektedir. Tablo için Azure Cosmos DB, uygulamaların yapılandırılmış tablo verilerini bulutta depolamasına olanak sağlayan şemasız bir veri deposudur. Azure.Data.Tables Paketi'ni (NuGet) kullanarak Azure Cosmos DB kaynağınızda tablo, satır oluşturma ve temel görevleri gerçekleştirme hakkında bilgi edineceksiniz.

Not

Örnek kod parçacıkları GitHub'da .NET projesi olarak kullanılabilir.

Tablo başvuru belgeleri | için API Azure.Data.Tables Paketi (NuGet)

Önkoşullar

Ayarlama

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

Open in GitHub Codespaces

Open in Dev Container

Ö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.

  1. Projenin kök dizininde bir terminal açın.

  2. 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
    
  3. Projeyi başlatmak için kullanın azd init .

    azd init
    
  4. 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-dbgöz önünde bulundurun.

  5. Kullanarak azd upAzure Cosmos DB hesabını dağıtın. Bicep şablonları ayrıca örnek bir web uygulaması dağıtır.

    azd up
    
  6. 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.

  7. 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.
    
  8. Tarayıcıda web uygulamanıza gitmek için konsoldaki URL'yi kullanın. Çalışan uygulamanın çıkışını gözlemleyin.

    Screenshot of the running web application.

İstemci kitaplığını yükleme

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

  1. Bir terminal açın ve klasöre /src/web gidin.

    cd ./src/web
    
  2. Henüz yüklü değilse, kullanarak paketini dotnet add packageyükleyinMicrosoft.Azure.Cosmos.

    dotnet add package Microsoft.Azure.Cosmos
    
  3. Ayrıca, henüz yüklü değilse paketi yükleyin Azure.Identity .

    dotnet add package Azure.Identity
    
  4. src/web/Cosmos.Samples.Table.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.

Kod örnekleri

Bu makalede açıklanan örnek kod adlı adventureworksbir tablo oluşturur. Her tablo satırı ad, kategori, miktar ve satış göstergesi gibi bir ürünün ayrıntılarını içerir. Her ürün benzersiz bir tanımlayıcı da içerir.

Tablo sınıfları için aşağıdaki API'yi kullanarak bu kaynaklarla etkileşim kuracaksınız:

  • TableServiceClient - Bu sınıf, Tablo için Azure Cosmos DB ile hizmet düzeyi işlemleri gerçekleştirmek için yöntemler sağlar.
  • TableClient - Bu sınıf, Azure Cosmos DB tablo API'sinde barındırılan tablolarla etkileşim kurmanızı sağlar.
  • TableEntity - Bu sınıf, özellikleri ve sütun verilerini yönetmenizi sağlayan tablodaki bir satıra başvurudur.

İstemcinin kimliğini doğrulama

Proje dizininden Program.cs dosyasını açın. Düzenleyicinizde için Azure.Data.Tablesbir using yönergesi ekleyin.

using Azure.Data.Tables;

Oluşturucuyu TableServiceClient kullanarak sınıfının yeni bir örneğini tanımlayın ve Environment.GetEnvironmentVariable daha önce ayarladığınız bağlantı dizesi okuyun.

// New instance of the TableClient class
TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));

Tablo oluştur

sınıfını TableClient kullanarak öğesinin bir örneğini TableServiceClient alın. TableClient.CreateIfNotExistsAsync Henüz yoksa yeni bir tablo oluşturmak için üzerindeki TableClient yöntemini kullanın. Bu yöntem var olan veya yeni oluşturulan tabloya bir başvuru döndürür.

// New instance of TableClient class referencing the server-side table
TableClient tableClient = tableServiceClient.GetTableClient(
    tableName: "adventureworks"
);

await tableClient.CreateIfNotExistsAsync();

Öğe oluşturma

Tabloda yeni öğe oluşturmanın en kolay yolu arabirimini uygulayan ITableEntity bir sınıf oluşturmaktır. Ardından, bu tablo satırındaki veri sütunlarını doldurmak için sınıfına kendi özelliklerinizi ekleyebilirsiniz.

// C# record type for items in the table
public record Product : ITableEntity
{
    public string RowKey { get; set; } = default!;

    public string PartitionKey { get; set; } = default!;

    public string Name { get; init; } = default!;

    public int Quantity { get; init; }

    public bool Sale { get; init; }

    public ETag ETag { get; set; } = default!;

    public DateTimeOffset? Timestamp { get; set; } = default!;
}

öğesini çağırarak TableClient.AddEntityAsync<T>sınıfını Product kullanarak koleksiyonda bir öğe oluşturun.

// Create new item using composite key constructor
var prod1 = new Product()
{
    RowKey = "68719518388",
    PartitionKey = "gear-surf-surfboards",
    Name = "Ocean Surfboard",
    Quantity = 8,
    Sale = true
};

// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(prod1);

Öğe alma

Yöntemini kullanarak tablodan belirli bir öğeyi TableEntity.GetEntityAsync<T> alabilirsiniz. Bu öğenin hızlı bir nokta okumasını partitionKey gerçekleştirmek için doğru satırı tanımlamak için ve rowKey parametresini belirtin.

// Read a single item from container
var product = await tableClient.GetEntityAsync<Product>(
    rowKey: "68719518388",
    partitionKey: "gear-surf-surfboards"
);
Console.WriteLine("Single product:");
Console.WriteLine(product.Value.Name);

Sorgu öğeleri

Öğe ekledikten sonra, yöntemini kullanarak TableClient.Query<T> belirli bir filtreyle eşleşen tüm öğeleri almak için bir sorgu da çalıştırabilirsiniz. Bu örnek, sınıf gibi yazılan ITableEntity modelleri kullanmanın bir avantajı olan Linq söz dizimini kullanarak ürünleri kategoriye Product göre filtreler.

Not

Ayrıca, OData söz dizimlerini kullanarak da öğeleri sorgulayabilirsiniz. Bu yaklaşımın bir örneğini Sorgu Verileri öğreticisinde görebilirsiniz.

// Read multiple items from container
var prod2 = new Product()
{
    RowKey = "68719518390",
    PartitionKey = "gear-surf-surfboards",
    Name = "Sand Surfboard",
    Quantity = 5,
    Sale = false
};

await tableClient.AddEntityAsync<Product>(prod2);

var products = tableClient.Query<Product>(x => x.PartitionKey == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var item in products)
{
    Console.WriteLine(item.Name);
}

Kodu çalıştırma

Bu uygulama bir Azure Cosmos DB Tablo API'si tablosu oluşturur. Örnek daha sonra bir öğe oluşturur ve tam olarak aynı öğeyi yeniden okur. Son olarak, örnek ikinci bir öğe oluşturur ve birden çok öğe döndürmesi gereken bir sorgu gerçekleştirir. Her adımda örnek, konsola gerçekleştirdiği adımlarla ilgili meta veriler gönderir.

Uygulamayı çalıştırmak için bir terminal kullanarak uygulama dizinine gidin ve uygulamayı çalıştırın.

dotnet run

Uygulamanın çıkışı şu örneğe benzer olmalıdır:

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

Kaynakları temizleme

Tablo için Azure Cosmos DB hesabına artık ihtiyacınız kalmadığında ilgili kaynak grubunu silebilirsiniz.

az group delete Kaynak grubunu silmek için komutunu kullanın.

az group delete --name $resourceGroupName

Sonraki adımlar

Bu hızlı başlangıçta, .NET SDK'sını kullanarak Tablo hesabı için Azure Cosmos DB oluşturmayı, tablo oluşturmayı ve girişleri yönetmeyi öğrendiniz. Artık Tablo kaynakları için Azure Cosmos DB'nizde daha gelişmiş veri sorguları ve yönetim görevleri gerçekleştirmeyi öğrenmek için SDK'nın ayrıntılarına inebilirsiniz.