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

UYGULANANLAR: NOSQL

Hesabınızda veritabanları, kapsayıcılar ve öğeler oluşturmak için .NET için Azure Cosmos DB istemci kitaplığını kullanmaya başlayın. Paketi yüklemek için bu adımları izleyin ve temel görevler için örnek kodu deneyin.

Not

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

API başvuru belgeleri | Kitaplık kaynak kodu | Paket (NuGet) | Örnekleri

Önkoşullar

Önkoşul denetimi

  • Terminal veya komut penceresinde komutunu çalıştırarak dotnet --version .NET SDK'sının sürüm 6.0 veya üzeri olup olmadığını denetleyin.
  • Uygun Azure komut satırı araçlarının yüklü olup olmadığını denetlemek için (Azure CLI) veya Get-Module -ListAvailable AzureRM (Azure PowerShell) komutunu çalıştırın az --version .

Ayarlama

Bu bölümde Azure Cosmos DB hesabı oluşturma ve kaynakları yönetmek üzere .NET için NoSQL için Azure Cosmos DB istemci kitaplığını kullanan bir proje ayarlama adımları açıklanmaktadır.

Azure Cosmos DB hesabı oluşturma

İpucu

Azure aboneliği yok mu? Azure Cosmos DB'i kredi kartı gerektirmeden ücretsiz olarak deneyebilirsiniz. Ücretsiz deneme sürümünü kullanarak bir hesap oluşturursanız, Yeni .NET uygulaması oluşturma bölümüne güvenle atlayabilirsiniz.

Bu hızlı başlangıçta NoSQL api'sini kullanarak tek bir Azure Cosmos DB hesabı oluşturulacaktır.

İpucu

Bu hızlı başlangıç için kaynak grubu adını msdocs-cosmos-quickstart-rgkullanmanızı öneririz.

  1. Azure Portal’ında oturum açın.

  2. Azure portal menüsünden veya Giriş sayfasındaKaynak oluştur'u seçin.

  3. Yeni sayfasında Azure Cosmos DB'yi arayın ve seçin.

  4. API seç seçeneği sayfasında NoSQL bölümünde Oluştur seçeneğini belirleyin. Azure Cosmos DB altı API'ye sahiptir: NoSQL, MongoDB, PostgreSQL, Apache Cassandra, Apache Gremlin ve Tablo. NoSQL IÇIN API hakkında daha fazla bilgi edinin.

    Azure Cosmos DB için API seçeneğini belirleme sayfasının ekran görüntüsü.

  5. Azure Cosmos DB Hesabı Oluştur sayfasında aşağıdaki bilgileri girin:

    Ayar Değer Açıklama
    Abonelik Abonelik adı Bu Azure Cosmos hesabı için kullanmak istediğiniz Azure aboneliğini seçin.
    Kaynak Grubu Kaynak grubu adı Bir kaynak grubu seçin veya Yeni oluştur seçeneğini belirleyin ve yeni kaynak grubu için benzersiz bir ad girin.
    Hesap Adı Benzersiz bir ad Azure Cosmos hesabınızı tanımlayan bir ad girin. Ad, documents.azure.com soneki olan tam etki alanı adının (FQDN) bir parçası olarak kullanılır, bu nedenle adın genel olarak benzersiz olması gerekir. Ad yalnızca küçük harf, sayı ve kısa çizgi (-) karakterini içerebilir. Adın uzunluğu da 3-44 karakter arasında olmalıdır.
    Konum Kullanıcılarınıza en yakın bölge Azure Cosmos DB hesabınızın barındırılacağı coğrafi konumu seçin. Verilere en hızlı erişimi sağlamak için kullanıcılarınıza en yakın olan konumu kullanın.
    Kapasite modu Sağlanan aktarım hızı veya Sunucusuz Sağlanan aktarım hızı modunda hesap oluşturmak için Sağlanan aktarım hızı'na tıklayın. Sunucusuz modda hesap oluşturmak için Sunucusuz'u seçin.
    Azure Cosmos DB ücretsiz katman indirimi uygulama Uygula veya Uygulama Azure Cosmos DB ücretsiz katmanını etkinleştirin. Azure Cosmos DB ücretsiz katmanı ile bir hesapta ilk 1000 RU/sn ve 25 GB depolama alanını ücretsiz olarak alırsınız. Ücretsiz katman hakkında daha fazla bilgi edinin.

    Not

    Azure aboneliği başına en fazla bir ücretsiz katman Azure Cosmos DB hesabınız olabilir ve hesabı oluştururken kabul etmeniz gerekir. Ücretsiz katman indirimini uygulama seçeneğini görmüyorsanız bu, abonelikteki başka bir hesabın ücretsiz katmanla zaten etkinleştirildiği anlamına gelir.

    NoSQL api'sinin yeni hesap sayfasının ekran görüntüsü.

  6. Gözden geçir ve oluştur’u seçin.

  7. Sağladığınız ayarları gözden geçirin ve Oluştur'u seçin. Hesabın oluşturulması birkaç dakika sürer. Devam etmeden önce portal sayfasının Dağıtımınız tamamlandı ifadesini görüntülemesini bekleyin.

  8. Azure Cosmos DB hesabı sayfasına gitmek için Kaynağa git seçeneğini belirleyin.

    NoSQL kaynağı için API dağıtım sayfasının ekran görüntüsü.

  9. NoSQL hesabı API'sinin sayfasında Anahtarlar gezinti menüsü seçeneğini belirleyin.

    NoSQL hesabı için API sayfasının ekran görüntüsü. Gezinti menüsünde Anahtarlar seçeneği vurgulanır.

  10. URI ve BİRİnCİl ANAHTAR alanlarındaki değerleri kaydedin. Bu değerleri sonraki bir adımda kullanacaksınız.

    NoSQL hesabı api'sinin çeşitli kimlik bilgilerini içeren Anahtarlar sayfasının ekran görüntüsü.

Yeni bir .NET uygulaması oluşturma

Tercih ettiğiniz terminali kullanarak boş bir klasörde yeni bir .NET uygulaması oluşturun. dotnet newKonsol şablonunu belirten komutunu kullanın.

dotnet new console

Paketi yükleme

Microsoft ekleyin. .NET projesine Azure.Cosmos NuGet paketi. dotnet add package NuGet paketinin adını belirten komutunu kullanın.

dotnet add package Microsoft.Azure.Cosmos

komutuyla dotnet build projeyi 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 -> C:\Users\sidandrews\Demos\dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Ortam değişkenlerini yapılandırma

Kodunuzda 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. Ortam değişkenini ayarlamak için tercih ettiğiniz terminali kullanarak aşağıdaki komutları çalıştırın:

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Nesne modeli

Uygulamayı oluşturmaya başlamadan önce Azure Cosmos DB'deki kaynak hiyerarşisini inceleyelim. Azure Cosmos DB, kaynak oluşturmak ve kaynaklara erişmek için kullanılan belirli bir nesne modeline sahiptir. Azure Cosmos DB, hesaplardan, veritabanlarından, kapsayıcılardan ve öğelerden oluşan bir hiyerarşide kaynaklar oluşturur.

Hesaplar, veritabanları, kapsayıcılar ve öğeler dahil olmak üzere Azure Cosmos DB hiyerarşisinin diyagramı.

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.

Farklı kaynakların hiyerarşisi hakkında daha fazla bilgi için bkz. Azure Cosmos DB'de veritabanları, kapsayıcılar ve öğelerle çalışma.

Bu kaynaklarla etkileşime geçmek için aşağıdaki .NET sınıflarını kullanacaksınız:

  • CosmosClient - Bu sınıf, Azure Cosmos DB hizmeti için istemci tarafı mantıksal bir temsil sağlar. İstemci nesnesi, hizmete yönelik 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 buna 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.
  • QueryDefinition - Bu sınıf bir SQL sorgusunu ve tüm sorgu parametrelerini temsil eder.
  • FeedIterator<> - Bu sınıf, geçerli sonuç sayfasını izleyebilen ve yeni bir sonuç sayfası alabilen bir yineleyiciyi temsil eder.
  • FeedResponse<> - Bu sınıf yineleyiciden gelen yanıtların tek bir sayfasını temsil eder. Bu tür döngü foreach kullanılarak yinelenebilir.

Kod örnekleri

Bu makalede açıklanan örnek kod adlı bir kapsayıcı ile adlı adventureworksproductsbir veritabanı oluşturur. Tablo products ad, kategori, miktar ve satış göstergesi gibi ürün ayrıntılarını içerecek şekilde tasarlanmıştır. Her ürün ayrıca benzersiz bir tanımlayıcı içerir.

Bu örnek kod için kapsayıcı, kategoriyi mantıksal bölüm anahtarı olarak kullanır.

İstemcinin kimliğini doğrulama

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

using Microsoft.Azure.Cosmos;

Oluşturucuyu CosmosClient kullanarak sınıfının yeni bir örneğini tanımlayın ve Environment.GetEnvironmentVariable daha önce oluşturduğunuz iki ortam değişkenini okuyun.

// New instance of CosmosClient class
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);

Örnek oluşturmanın CosmosClient farklı yolları hakkında daha fazla bilgi için bkz. NoSQL ve .NET için Azure Cosmos DB'yi kullanmaya başlama.

Veritabanı oluşturma

CosmosClient.CreateDatabaseIfNotExistsAsync Henüz yoksa yeni bir veritabanı oluşturmak için yöntemini kullanın. Bu yöntem var olan veya yeni oluşturulan veritabanına bir başvuru döndürür.

// Database reference with creation if it does not already exist
Database database = await client.CreateDatabaseIfNotExistsAsync(
    id: "cosmicworks"
);

Console.WriteLine($"New database:\t{database.Id}");

Veritabanı oluşturma hakkında daha fazla bilgi için bkz. .NET kullanarak NoSQL için Azure Cosmos DB'de veritabanı oluşturma.

Kapsayıcı oluşturma

Database.CreateContainerIfNotExistsAsync henüz yoksa yeni bir kapsayıcı oluşturur. Bu yöntem ayrıca kapsayıcıya bir başvuru döndürür.

// Container reference with creation if it does not alredy exist
Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/categoryId",
    throughput: 400
);

Console.WriteLine($"New container:\t{container.Id}");

Kapsayıcı oluşturma hakkında daha fazla bilgi için bkz. .NET kullanarak NoSQL için Azure Cosmos DB'de kapsayıcı oluşturma.

Öğe oluşturma

Kapsayıcıda yeni öğe oluşturmanın en kolay yolu, önce JSON'da seri hale getirmek istediğiniz tüm üyeleri içeren bir C# sınıfı veya kayıt türü oluşturmaktır. Bu örnekte, C# kaydı benzersiz bir tanımlayıcıya, bölüm anahtarı için bir categoryId alanına ve fazladan categoryName, name, quantity ve sale alanlarına sahiptir.

// C# record representing an item in the container
public record Product(
    string id,
    string categoryId,
    string categoryName,
    string name,
    int quantity,
    bool sale
);

çağırarak Container.CreateItemAsynckapsayıcıda bir öğe oluşturun.

// Create new object and upsert (create or replace) to container
Product newItem = new(
    id: "70b63682-b93a-4c77-aad2-65501347265f",
    categoryId: "61dba35b-4f02-45c5-b648-c6badc0cbd79",
    categoryName: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    sale: false
);

Product createdItem = await container.CreateItemAsync<Product>(
    item: newItem,
    partitionKey: new PartitionKey("61dba35b-4f02-45c5-b648-c6badc0cbd79")
);

Console.WriteLine($"Created item:\t{createdItem.id}\t[{createdItem.categoryName}]");

Öğeleri oluşturma, yükseltme veya değiştirme hakkında daha fazla bilgi için bkz. .NET kullanarak NoSQL için Azure Cosmos DB'de öğe oluşturma.

Öğe alma

Azure Cosmos DB'de hem benzersiz tanımlayıcıyı (id) hem de bölüm anahtarı alanlarını kullanarak nokta okuma işlemi gerçekleştirebilirsiniz. SDK'da, C# türünüzün seri durumdan çıkarılmış bir örneğini döndürmek için her iki değeri de geçirme çağrısı Container.ReadItemAsync<> yapın.

// Point read item from container using the id and partitionKey
Product readItem = await container.ReadItemAsync<Product>(
    id: "70b63682-b93a-4c77-aad2-65501347265f",
    partitionKey: new PartitionKey("61dba35b-4f02-45c5-b648-c6badc0cbd79")
);

Öğeleri okuma ve yanıtı ayrıştırma hakkında daha fazla bilgi için bkz. .NET kullanarak NoSQL için Azure Cosmos DB'de öğe okuma.

Sorgu öğeleri

Öğe ekledikten sonra, belirli bir filtreyle eşleşen tüm öğeleri almak için bir sorgu çalıştırabilirsiniz. Bu örnekte SQL sorgusu çalıştırılır: SELECT * FROM products p WHERE p.categoryId = "61dba35b-4f02-45c5-b648-c6badc0cbd79". Bu örnekte, bölüm anahtarı filtresi için QueryDefinition türü ve parametreli sorgu ifadesi kullanılır. Sorgu tanımlandıktan sonra, sonuç sayfalarını yönetecek bir sonuç yineleyicisi almak için çağrısında Container.GetItemQueryIterator<> bulunun. Ardından, sonuç sayfalarını almak ve ardından tek tek öğeler üzerinde yinelemek için ve foreach döngülerinin bir bileşimini while kullanın.

// Create query using a SQL string and parameters
var query = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.categoryId = @categoryId"
)
    .WithParameter("@categoryId", "61dba35b-4f02-45c5-b648-c6badc0cbd79");

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

while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

Kodu çalıştırma

Bu uygulama NoSQL veritabanı ve kapsayıcısı için bir API oluşturur. Örnek daha sonra bir öğe oluşturur ve aynı öğeyi yeniden okur. Son olarak, örnek yalnızca bu tek öğeyi döndürmesi gereken bir sorgu oluşturur. Her adımda örnek, gerçekleştirdiği adımlarla ilgili meta verileri konsola 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:

New database:   adventureworks
New container:  products
Created item:   68719518391     [gear-surf-surfboards]

Kaynakları temizleme

NoSQL hesabının API'sine artık ihtiyacınız kalmadığında ilgili kaynak grubunu silebilirsiniz.

  1. Azure portal önceden oluşturduğunuz kaynak grubuna gidin.

    İpucu

    Bu hızlı başlangıçta adını msdocs-cosmos-quickstart-rgöneririz.

  2. Kaynak grubunu sil'i seçin.

    Bir kaynak grubunun gezinti çubuğundaki Kaynak grubunu sil seçeneğinin ekran görüntüsü.

  3. Silmek istediğinizden emin misiniz iletişim kutusunda kaynak grubunun adını girin ve Sil'i seçin.

    Kaynak grubu için silme onayı sayfasının ekran görüntüsü.

Sonraki adımlar

Bu hızlı başlangıçta, .NET SDK'sını kullanarak NoSQL için Azure Cosmos DB hesabı oluşturmayı, veritabanı oluşturmayı ve kapsayıcı oluşturmayı öğrendiniz. Artık bir .NET konsol uygulaması kullanarak NoSQL için Azure Cosmos DB kaynaklarınızı ve verilerinizi yönettiğiniz bir öğreticiye daha ayrıntılı bir şekilde göz atabilirsiniz.