hızlı başlangıç: Azure Cosmos DB SQL apı hesabı kaynaklarını yönetmek için .net V4 SDK 'sını (önizleme) kullanarak bir konsol uygulaması oluşturma

UYGULANDıĞı YER: SQL API

.net için Azure Cosmos DB SQL apı istemci kitaplığı ile çalışmaya başlayın. .net V4 (Azure. Cosmos) paketini yüklemek ve bir uygulama oluşturmak için bu makaledeki adımları izleyin. daha sonra, Azure Cosmos DB depolanan verilerde temel oluşturma, okuma, güncelleştirme ve silme (crud) işlemleri için örnek kodu deneyin.

Önemli

Azure Cosmos DB için .net V4 SDK 'sı şu anda genel önizlemededir. Bu önizleme sürümü bir hizmet düzeyi sözleşmesi olmadan sağlanır ve bunu üretim iş yükleri için önermiyoruz. Bazı özellikler desteklenmiyor olabileceği gibi özellikleri sınırlandırılmış da olabilir.

Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.

Azure Cosmos DB, Microsoft 'un herhangi bir ölçekte açık apı 'leri olan hızlı nosql veritabanıdır. anahtar/değer, belge ve grafik veritabanlarını hızlıca oluşturmak ve sorgulamak için Azure Cosmos DB kullanabilirsiniz. .net için Azure Cosmos DB SQL apı istemci kitaplığını kullanın:

  • Azure Cosmos veritabanı ve kapsayıcısı oluşturun.
  • Kapsayıcıya örnek veriler ekleyin.
  • Verileri sorgulayın.
  • Veritabanını silin.

Kitaplık kaynak kodu | Paket (NuGet)

Önkoşullar

Kurulum

bu bölümde, kaynakları yönetmek üzere .net için Azure Cosmos DB SQL apı istemci kitaplığı 'nı kullanan bir Azure Cosmos hesabı oluşturma ve bir proje ayarlama işlemi adım adım açıklanmaktadır.

Bu makalede açıklanan örnek kod, bu FamilyDatabase veritabanı içinde bir veritabanı ve aile üyeleri oluşturur. Her aile üyesi bir öğedir ve,,,,, ve gibi özelliklere sahiptir Id FamilyName FirstName LastName Parents Children Address . LastNameÖzelliği kapsayıcı için bölüm anahtarı olarak kullanılır.

Azure Cosmos hesabı oluşturma

azure Cosmos hesabı oluşturmak için ücretsiz deneme Azure Cosmos DB seçeneğini kullanırsanız, SQL apı türünde bir azure Cosmos hesabı oluşturmanız gerekir. sizin için bir Azure Cosmos test hesabı zaten oluşturulmuş. Hesabı açıkça oluşturmanız gerekmez; bu sayede bu bölümü atlayabilir ve sonraki bölüme geçebilirsiniz.

kendi azure aboneliğiniz varsa veya ücretsiz bir abonelik oluşturduysanız, açıkça bir azure Cosmos hesabı oluşturmanız gerekir. aşağıdaki kod, oturum tutarlılığı olan bir Azure Cosmos hesabı oluşturacaktır. Hesap ve ' de çoğaltılır South Central US North Central US .

Azure Cosmos hesabını oluşturmak için Azure Cloud Shell kullanabilirsiniz. Azure Cloud Shell, Azure kaynaklarını yönetmek için kullanabileceğiniz etkileşimli, kimliği doğrulanmış ve tarayıcı ile erişilebilen bir kabuktur. Çalışma biçiminize en uygun kabuk deneyimini seçme esnekliği sağlar: bash veya PowerShell.

Bu hızlı başlangıç için bash kullanın. Azure Cloud Shell Ayrıca bir depolama hesabı gerektirir. İstendiğinde bir tane oluşturabilirsiniz.

  1. Aşağıdaki kodun yanındaki deneyin düğmesini seçin, Bash modu ' nu seçin, depolama hesabı oluştur' u seçin ve Cloud Shell için oturum açın.

  2. Aşağıdaki kodu kopyalayıp Azure Cloud Shell ve çalıştırmak için yapıştırın. Azure Cosmos hesap adı genel olarak benzersiz olmalıdır; bu nedenle, mysqlapicosmosdb komutu çalıştırmadan önce değeri güncelleştirdiğinizden emin olun.

    
    # Set variables for the new SQL API account, database, and container
    resourceGroupName='myResourceGroup'
    location='southcentralus'
    
    # The Azure Cosmos account name must be globally unique, so be sure to update the `mysqlapicosmosdb` value before you run the command
    accountName='mysqlapicosmosdb'
    
    # Create a resource group
    az group create \
        --name $resourceGroupName \
        --location $location
    
    # Create a SQL API Cosmos DB account with session consistency and multi-region writes enabled
    az cosmosdb create \
        --resource-group $resourceGroupName \
        --name $accountName \
        --kind GlobalDocumentDB \
        --locations regionName="South Central US" failoverPriority=0 --locations regionName="North Central US" failoverPriority=1 \
        --default-consistency-level "Session" \
        --enable-multiple-write-locations true
    
    

Azure Cosmos hesabının oluşturulması biraz zaman alabilir. İşlem başarılı olduktan sonra, onay çıkışını görebilirsiniz. Azure portal oturum açın ve belirtilen ada sahip Azure Cosmos hesabının var olduğunu doğrulayın. Kaynak oluşturulduktan sonra Azure Cloud Shell penceresini kapatabilirsiniz.

.NET uygulaması oluşturma

Tercih ettiğiniz düzenleyicide veya IDE 'de bir .NET uygulaması oluşturun. Windows komut istemi veya yerel bilgisayarınızdan bir terminal penceresi açın. Komut istemi veya terminalden sonraki bölümlerde bulunan tüm komutları çalıştıracaksınız.

dotnet newAdında bir uygulama oluşturmak için aşağıdaki komutu çalıştırın todo . --langVersionParametresi, LangVersion oluşturulan proje dosyasındaki özelliği ayarlar.

dotnet new console --langVersion:8 -n todo

Dizininizi yeni oluşturulan uygulama klasörüyle değiştirmek ve uygulamayı derlemek için aşağıdaki komutları kullanın:

cd todo
dotnet build

Derlemeden beklenen çıktı şuna benzemelidir:

  Restore completed in 100.37 ms for C:\Users\user1\Downloads\CosmosDB_Samples\todo\todo.csproj.
  todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp3.0\todo.dll

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

Time Elapsed 00:00:34.17

Azure Cosmos DB paketini yükler

hala uygulama dizininde olduğunuzda, komutunu kullanarak .net Core için Azure Cosmos DB istemci kitaplığı ' nı da yükleyebilirsiniz dotnet add package :

dotnet add package Azure.Cosmos --version 4.0.0-preview3

Azure Cosmos hesabı kimlik bilgilerinizi Azure portal kopyalayın

örnek uygulamanın Azure Cosmos hesabınızda kimlik doğrulaması yapması gerekir. kimlik doğrulaması yapmak için Azure Cosmos hesabı kimlik bilgilerini uygulamaya geçirin. aşağıdaki adımları izleyerek Azure Cosmos hesabı kimlik bilgilerinizi alın:

  1. Azure Portal oturum açın.

  2. Azure Cosmos hesabınıza gidin.

  3. Anahtarlar bölmesini açın ve hesabınız için URI ve birincil anahtar değerlerini kopyalayın. Bir sonraki yordamda bir ortam değişkenine URI ve anahtar değerleri ekleyeceksiniz.

Nesne modelini öğrenme

uygulamayı oluşturmaya devam etmeden önce Azure Cosmos DB içindeki kaynak hiyerarşisine ve bu kaynakları oluşturmak ve bunlara erişmek için kullanılan nesne modeline göz atalım. Azure Cosmos DB, kaynakları aşağıdaki sırayla oluşturur:

  • Azure Cosmos hesabı
  • Veritabanları
  • Kapsayıcılar
  • Öğeler

varlıkların hiyerarşisi hakkında daha fazla bilgi edinmek için Azure Cosmos DB kaynak modeli makalesine bakın. Şu kaynaklarla etkileşim kurmak 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 temsili sağlar. İstemci nesnesi, hizmete yönelik istekleri yapılandırmak ve yürütmek için kullanılır.
  • CreateDatabaseIfNotExistsAsync. Bu Yöntem (yoksa) oluşturur veya (zaten varsa) zaman uyumsuz bir işlem olarak veritabanı kaynağını alır.
  • CreateContainerIfNotExistsAsync. Bu Yöntem (yoksa) oluşturur veya bir kapsayıcıyı zaman uyumsuz bir işlem olarak (zaten varsa) alır. Kapsayıcının yeni oluşturulup oluşturulmayacağını (201) veya var olan bir kapsayıcının döndürülüp döndürülmediğini (200) öğrenmek için yanıttan durum kodunu kontrol edebilirsiniz.
  • CreateItemAsync. Bu yöntem, kapsayıcı içinde bir öğe oluşturur.
  • UpsertItemAsync. Bu yöntem, zaten yoksa kapsayıcı içinde bir öğe oluşturur veya zaten varsa öğeyi değiştirir.
  • GetItemQueryIterator. bu yöntem, parametreli değerler içeren bir SQL ifadesini kullanarak bir Azure Cosmos veritabanındaki kapsayıcı altındaki öğeler için bir sorgu oluşturur.
  • DeleteAsync. bu yöntem, Azure Cosmos hesabınızdan belirtilen veritabanını siler.

Kod örneklerini yapılandırma

bu makalede açıklanan örnek kod, Azure Cosmos DB bir aile veritabanı oluşturur. Aile veritabanı ad, adres, konum, üst öğeler, alt öğeler ve Evcil hayvan gibi aile ayrıntılarını içerir.

Azure Cosmos hesabınız için verileri doldurmadan önce, bir aile öğesinin özelliklerini tanımlayın. Örnek uygulamanızın kök düzeyinde adlı yeni bir sınıf oluşturun Family.cs ve buna aşağıdaki kodu ekleyin:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace todo
{
    public class Family
    {
        [JsonPropertyName("id")]
        public string Id { get; set; }
        public string LastName { get; set; }
        public Parent[] Parents { get; set; }
        public Child[] Children { get; set; }
        public Address Address { get; set; }
        public bool IsRegistered { get; set; }
        public override string ToString()
        {
            return JsonSerializer.Serialize(this);
        }
    }

    public class Parent
    {
        public string FamilyName { get; set; }
        public string FirstName { get; set; }
    }

    public class Child
    {
        public string FamilyName { get; set; }
        public string FirstName { get; set; }
        public string Gender { get; set; }
        public int Grade { get; set; }
        public Pet[] Pets { get; set; }
    }

    public class Pet
    {
        public string GivenName { get; set; }
    }

    public class Address
    {
        public string State { get; set; }
        public string County { get; set; }
        public string City { get; set; }
    }
}

Using yönergelerini ekleme ve istemci nesnesini tanımlama

Proje dizininden, düzenleyicinizdeki program. cs dosyasını açın ve using uygulamanızın en üstüne aşağıdaki yönergeleri ekleyin:

using System;
using System.Collections.Generic;
using System.Net;
using System.Threading.Tasks;
using Azure.Cosmos;

Sınıfınıza aşağıdaki genel değişkenleri ekleyin Program . Bu değişkenler, uç nokta ve yetkilendirme anahtarlarını, veritabanının adını ve oluşturacağınız kapsayıcıyı içerir. Uç nokta ve yetkilendirme anahtarı değerlerini ortamınıza göre değiştirdiğinizden emin olun.

private const string EndpointUrl = "https://<your-account>.documents.azure.com:443/";
private const string AuthorizationKey = "<your-account-key>";
private const string DatabaseId = "FamilyDatabase";
private const string ContainerId = "FamilyContainer";

Son olarak, Main yöntemini değiştirin:

static async Task Main(string[] args)
{
    
    CosmosClient cosmosClient = new CosmosClient(EndpointUrl, AuthorizationKey);
    await Program.CreateDatabaseAsync(cosmosClient);
    await Program.CreateContainerAsync(cosmosClient);
    await Program.AddItemsToContainerAsync(cosmosClient);
    await Program.QueryItemsAsync(cosmosClient);
    await Program.ReplaceFamilyItemAsync(cosmosClient);
    await Program.DeleteFamilyItemAsync(cosmosClient);
    await Program.DeleteDatabaseAndCleanupAsync(cosmosClient);
}

Veritabanı oluşturma

CreateDatabaseAsyncSınıfında yöntemini tanımlayın program.cs . Bu yöntem, FamilyDatabase zaten mevcut değilse veritabanını oluşturur.

/// <summary>
/// Create the database if it does not exist
/// </summary>
private static async Task CreateDatabaseAsync(CosmosClient cosmosClient)
{
    // Create a new database
    CosmosDatabase database = await cosmosClient.CreateDatabaseIfNotExistsAsync(Program.DatabaseId);
    Console.WriteLine("Created Database: {0}\n", database.Id);
}

Kapsayıcı oluşturma

CreateContainerAsyncSınıfında yöntemini tanımlayın Program . Bu yöntem, FamilyContainer zaten mevcut değilse kapsayıcıyı oluşturur.

/// <summary>
/// Create the container if it does not exist. 
/// Specify "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
/// </summary>
/// <returns></returns>
private static async Task CreateContainerAsync(CosmosClient cosmosClient)
{
    // Create a new container
    CosmosContainer container = await cosmosClient.GetDatabase(Program.DatabaseId).CreateContainerIfNotExistsAsync(Program.ContainerId, "/LastName");
    Console.WriteLine("Created Container: {0}\n", container.Id);
}

Öğe oluşturma

Aşağıdaki kodla metodunu ekleyerek bir aile öğesi oluşturun AddItemsToContainerAsync . CreateItemAsync UpsertItemAsync Bir öğe oluşturmak için veya yöntemini kullanabilirsiniz.

/// <summary>
/// Add Family items to the container
/// </summary>
private static async Task AddItemsToContainerAsync(CosmosClient cosmosClient)
{
    // Create a family object for the Andersen family
    Family andersenFamily = new Family
    {
        Id = "Andersen.1",
        LastName = "Andersen",
        Parents = new Parent[]
        {
            new Parent { FirstName = "Thomas" },
            new Parent { FirstName = "Mary Kay" }
        },
        Children = new Child[]
        {
            new Child
            {
                FirstName = "Henriette Thaulow",
                Gender = "female",
                Grade = 5,
                Pets = new Pet[]
                {
                    new Pet { GivenName = "Fluffy" }
                }
            }
        },
        Address = new Address { State = "WA", County = "King", City = "Seattle" },
        IsRegistered = false
    };

    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);
    try
    {
        // Read the item to see if it exists.  
        ItemResponse<Family> andersenFamilyResponse = await container.ReadItemAsync<Family>(andersenFamily.Id, new PartitionKey(andersenFamily.LastName));
        Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamilyResponse.Value.Id);
    }
    catch(CosmosException ex) when (ex.Status == (int)HttpStatusCode.NotFound)
    {
        // Create an item in the container representing the Andersen family. Note we provide the value of the partition key for this item, which is "Andersen"
        ItemResponse<Family> andersenFamilyResponse = await container.CreateItemAsync<Family>(andersenFamily, new PartitionKey(andersenFamily.LastName));

        // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse.
        Console.WriteLine("Created item in database with id: {0}\n", andersenFamilyResponse.Value.Id);
    }

    // Create a family object for the Wakefield family
    Family wakefieldFamily = new Family
    {
        Id = "Wakefield.7",
        LastName = "Wakefield",
        Parents = new Parent[]
        {
            new Parent { FamilyName = "Wakefield", FirstName = "Robin" },
            new Parent { FamilyName = "Miller", FirstName = "Ben" }
        },
        Children = new Child[]
        {
            new Child
            {
                FamilyName = "Merriam",
                FirstName = "Jesse",
                Gender = "female",
                Grade = 8,
                Pets = new Pet[]
                {
                    new Pet { GivenName = "Goofy" },
                    new Pet { GivenName = "Shadow" }
                }
            },
            new Child
            {
                FamilyName = "Miller",
                FirstName = "Lisa",
                Gender = "female",
                Grade = 1
            }
        },
        Address = new Address { State = "NY", County = "Manhattan", City = "NY" },
        IsRegistered = true
    };

    // Create an item in the container representing the Wakefield family. Note we provide the value of the partition key for this item, which is "Wakefield"
    ItemResponse<Family> wakefieldFamilyResponse = await container.UpsertItemAsync<Family>(wakefieldFamily, new PartitionKey(wakefieldFamily.LastName));

    // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
    Console.WriteLine("Created item in database with id: {0}\n", wakefieldFamilyResponse.Value.Id);
}

Öğeleri sorgulama

Bir öğeyi ekledikten sonra, Andersen ailesinin ayrıntılarını almak için bir sorgu çalıştırabilirsiniz. aşağıdaki kod, SQL sorgusunu doğrudan kullanarak sorgunun nasıl yürütüleceğini gösterir. andersen aile ayrıntılarını almak için SQL sorgusu SELECT * FROM c WHERE c.LastName = 'Andersen' . QueryItemsAsyncSınıfında yöntemi tanımlayın Program ve aşağıdaki kodu buna ekleyin:

/// <summary>
/// Run a query (using Azure Cosmos DB SQL syntax) against the container
/// </summary>
private static async Task QueryItemsAsync(CosmosClient cosmosClient)
{
    var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";

    Console.WriteLine("Running query: {0}\n", sqlQueryText);

    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);

    QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);

    List<Family> families = new List<Family>();

    await foreach (Family family in container.GetItemQueryIterator<Family>(queryDefinition))
    {
        families.Add(family);
        Console.WriteLine("\tRead {0}\n", family);
    }
}

Bir öğeyi değiştirme

Bir aile öğesini okuyun ve ReplaceFamilyItemAsync yöntemi aşağıdaki kodla ekleyerek güncelleştirin:

/// <summary>
/// Replace an item in the container
/// </summary>
private static async Task ReplaceFamilyItemAsync(CosmosClient cosmosClient)
{
    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);

    ItemResponse<Family> wakefieldFamilyResponse = await container.ReadItemAsync<Family>("Wakefield.7", new PartitionKey("Wakefield"));
    Family itemBody = wakefieldFamilyResponse;
    
    // update registration status from false to true
    itemBody.IsRegistered = true;
    // update grade of child
    itemBody.Children[0].Grade = 6;

    // replace the item with the updated content
    wakefieldFamilyResponse = await container.ReplaceItemAsync<Family>(itemBody, itemBody.Id, new PartitionKey(itemBody.LastName));
    Console.WriteLine("Updated Family [{0},{1}].\n \tBody is now: {2}\n", itemBody.LastName, itemBody.Id, wakefieldFamilyResponse.Value);
}

Öğeyi silme

Aşağıdaki kodla yöntemini ekleyerek bir aile öğesini silin DeleteFamilyItemAsync :

/// <summary>
/// Delete an item in the container
/// </summary>
private static async Task DeleteFamilyItemAsync(CosmosClient cosmosClient)
{
    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);

    string partitionKeyValue = "Wakefield";
    string familyId = "Wakefield.7";

    // Delete an item. Note we must provide the partition key value and id of the item to delete
    ItemResponse<Family> wakefieldFamilyResponse = await container.DeleteItemAsync<Family>(familyId,new PartitionKey(partitionKeyValue));
    Console.WriteLine("Deleted Family [{0},{1}]\n", partitionKeyValue, familyId);
}

Veritabanını silme

DeleteDatabaseAndCleanupAsyncAşağıdaki kodla yöntemini ekleyerek veritabanını silebilirsiniz:

/// <summary>
/// Delete the database and dispose of the Cosmos Client instance
/// </summary>
private static async Task DeleteDatabaseAndCleanupAsync(CosmosClient cosmosClient)
{
    CosmosDatabase database = cosmosClient.GetDatabase(Program.DatabaseId);
    DatabaseResponse databaseResourceResponse = await database.DeleteAsync();

    Console.WriteLine("Deleted Database: {0}\n", Program.DatabaseId);
}

Tüm gerekli yöntemleri ekledikten sonra program. cs dosyasını kaydedin.

Kodu çalıştırma

Azure Cosmos DB kaynaklarını oluşturmak için uygulamayı çalıştırın:

dotnet run

Uygulamayı çalıştırdığınızda aşağıdaki çıktı oluşturulur:

Created Database: FamilyDatabase

Created Container: FamilyContainer

Created item in database with id: Andersen.1

Running query: SELECT * FROM c WHERE c.LastName = 'Andersen'

        Read {"id":"Andersen.1","LastName":"Andersen","Parents":[{"FamilyName":null,"FirstName":"Thomas"},{"FamilyName":null   "FirstName":"Mary Kay"}],"Children":[{"FamilyName":null,"FirstName":"Henriette Thaulow","Gender":"female","Grade":5,"Pets": [{"GivenName":"Fluffy"}]}],"Address":{"State":"WA","County":"King","City":"Seattle"},"IsRegistered":false}

Updated Family [Wakefield,Wakefield.7].
        Body is now: {"id":"Wakefield.7","LastName":"Wakefield","Parents":[{"FamilyName":"Wakefield","FirstName":"Robin"}   {"FamilyName":"Miller","FirstName":"Ben"}],"Children":[{"FamilyName":"Merriam","FirstName":"Jesse","Gender":"female","Grade":6   "Pets":[{"GivenName":"Goofy"},{"GivenName":"Shadow"}]},{"FamilyName":"Miller","FirstName":"Lisa","Gender":"female","Grade":1   "Pets":null}],"Address":{"State":"NY","County":"Manhattan","City":"NY"},"IsRegistered":true}

Deleted Family [Wakefield,Wakefield.7]

Deleted Database: FamilyDatabase

End of demo, press any key to exit.

Azure portal oturum açarak ve Azure Cosmos hesabınızda gerekli öğeleri görerek, verilerin oluşturulduğunu doğrulayabilirsiniz.

Kaynakları temizleme

artık azure Cosmos hesabına ve ilgili kaynak grubuna ihtiyacınız kalmadığında, bunları kaldırmak için azure clı veya Azure PowerShell kullanabilirsiniz. Aşağıdaki komut, Azure CLı kullanılarak kaynak grubunun nasıl silineceğini göstermektedir:

az group delete -g "myResourceGroup"

Sonraki adımlar

bu hızlı başlangıçta, bir Azure Cosmos hesabı oluşturmayı, veritabanı oluşturmayı ve bir .net Core uygulamasını kullanarak kapsayıcı oluşturmayı öğrendiniz. artık aşağıdaki makaledeki yönergeleri kullanarak Azure Cosmos hesabınıza daha fazla veri aktarabilirsiniz:

Azure Cosmos DB bir geçişe yönelik kapasite planlaması yapılmaya çalışılıyor musunuz? Kapasite planlaması için mevcut veritabanı kümeniz hakkında bilgi kullanabilirsiniz.