Hızlı Başlangıç: Azure COSMOS DB veya API kaynaklarını yönetmek SQL .NET konsol uygulaması oluşturma

UYGULAMANIN UYGULAMASI: SQL API

.NET için Azure Cosmos DB SQL API istemci kitaplığını çalışmaya başlama. Bu belge'de .NET paketini yüklemek, uygulama oluşturmak ve Azure Cosmos DB'de depolanan veriler üzerinde temel CRUD işlemleri için örnek kodu denemek için bu belge Cosmos izleyin.

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

  • Azure Cosmos veritabanı ve kapsayıcı oluşturma
  • Kapsayıcıya örnek veri ekleme
  • Verileri sorgulama
  • Veritabanını silme

API başvurusu belgeleriKitaplık kaynak koduPaket (NuGet)

Önkoşullar

Ayarlama

Bu bölüm, kaynakları yönetmek için Azure Cosmos hesabı oluşturma ve .NET için Azure Cosmos DB SQL API istemci kitaplığı kullanan bir projeyi ayarlama konusunda size yol gösterir. Bu makalede açıklanan örnek kod, bu veritabanında bir veritabanı ve aile üyeleri FamilyDatabase (her aile üyesi bir öğedir) oluşturur. Her aile üyesinin . Id, FamilyName, FirstName, LastName, Parents, Children, Address, Özellik, LastName kapsayıcı için bölüm anahtarı olarak kullanılır.

Azure Cosmos hesabı oluşturma

Azure Cosmos hesabı oluşturmak için Azure Cosmos DB'yi ücretsiz deneyin seçeneğini kullanırsanız, API türüne sahip bir Azure Cosmos DB SQL oluşturmanız gerekir. Sizin Cosmos bir Azure DB test hesabı zaten oluşturuldu. Hesabı açıkça oluşturmanız gerekmez; dolayısıyla bu bölümü atlayıp bir sonraki bölüme geçebilirsiniz.

Kendi Azure aboneliğiniz varsa veya ücretsiz bir abonelik oluşturduysanız, açıkça bir Azure Cosmos oluşturmanız gerekir. Aşağıdaki kod, oturum tutarlılığı Cosmos bir Azure Cosmos hesabı oluşturacak. Hesap ve içinde South Central USNorth Central US çoğaltılır.

Azure Bulut Kabuğu'nu kullanarak Azure Bulut Kabuğu hesabını Cosmos kullanabilirsiniz. Azure Bulut Kabuğu, Azure kaynaklarını yönetmek için etkileşimli, kimliği doğrulanmış, tarayıcıyla erişilebilir bir kabuk. Bash veya PowerShell gibi çalışma yolunuz için en uygun kabuk deneyimini seçme esnekliği sağlar. Bu hızlı başlangıç için Bash modunu seçin. Azure Bulut Kabuğu bir depolama hesabı da gerektirir, istendiğinde bir hesap oluşturabilirsiniz.

Aşağıdaki kodun yanındaki Deneyin düğmesini seçin, Bash modu'nu seçin, bir depolama hesabı oluşturun ve Bulut Kabuğu'da oturum açın. Ardından, aşağıdaki kodu kopyalayıp Azure Bulut Kabuğu'ya yapıştırın ve çalıştırın. Azure Cosmos adı genel olarak benzersiz olmalıdır, komutu çalıştırmadan önce değeri mysqlapicosmosdb güncelleştirin.


# Set variables for the new SQL API account, database, and container
resourceGroupName='myResourceGroup'
location='southcentralus'

# The Azure Cosmos account name must be globally unique, make 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 alır, işlem başarılı olduktan sonra onay çıktısını kullanabilirsiniz. Komut başarıyla tamamlandıktan sonra, Azure portalda oturum açın ve belirtilen adla Azure Cosmos hesabı olduğunu doğrulayın. Kaynak oluşturulduktan sonra Azure Bulut Kabuğu penceresini kapatabilirsiniz.

Yeni bir .NET uygulaması oluşturma

Tercih ettiğiniz düzenleyicide veya IDE'de yeni bir .NET uygulaması oluşturun. Yerel Windows komut istemini veya Terminal penceresini açın. Komut isteminden veya terminalden sonraki bölümlerdeki tüm komutları çalıştırın. adıyla yeni bir uygulama oluşturmak için aşağıdaki dotnet yeni komutunu todo çalıştırın. --langVersion parametresi, oluşturulan proje dosyasında LangVersion özelliğini ayarlar.

dotnet new console --langVersion 7.1 -n todo

Dizininizi yeni oluşturulan uygulama klasörüne değiştirebilirsiniz. Uygulamayı şu şekilde kurabilirsiniz:

cd todo
dotnet build

Derlemeden beklenen çıktı şuna benzer bir görünümde olur:

  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\netcoreapp2.2\todo.dll
  todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp2.2\todo.Views.dll

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

Time Elapsed 00:00:34.17

Azure Cosmos DB paketini yükleme

Uygulama dizinindeyken, dotnet add package komutunu Cosmos .NET Core için Azure Cosmos DB istemci kitaplığını yükleyin.

dotnet add package Microsoft.Azure.Cosmos

Azure portaldan Azure Cosmos hesap kimlik bilgilerinizi kopyalama

Örnek uygulamanın Azure Cosmos hesabınızla kimlik doğrulaması gerekiyor. Kimlik doğrulaması yapmak için, Azure Cosmos bilgilerini uygulamaya geçmeniz gerekir. Aşağıdaki adımları Cosmos Azure Cosmos kimlik bilgilerinizi edinin:

  1. Azure portalında oturum açın.

  2. Azure Cosmos hesabınıza gidin.

  3. Anahtarlar bölmesini açın ve hesabın URI ve PRIMARY ANAHTARıNı kopyalayın. Sonraki adımda, ortam değişkenine URI ve anahtar değerlerini ekleyebilirsiniz.

Ortam değişkenlerini ayarlama

Hesap URI'nizi ve PRIMARY KEY'i kopya belirttikten sonra, bunları uygulamayı çalıştıran yerel makinede yeni bir ortam değişkenine kaydedin. Ortam değişkenını ayarlamak için bir konsol penceresi açın ve aşağıdaki komutu çalıştırın. Değerleri ve değerleri <Your_Azure_Cosmos_account_URI> değiştir'i <Your_Azure_Cosmos_account_PRIMARY_KEY> seçin.

Windows

setx EndpointUrl "<Your_Azure_Cosmos_account_URI>"
setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

Linux

export EndpointUrl = "<Your_Azure_Cosmos_account_URI>"
export PrimaryKey = "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

macOS

export EndpointUrl = "<Your_Azure_Cosmos_account_URI>"
export PrimaryKey = "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

Nesne modeli

Uygulamayı oluşturmadan önce, Azure Cosmos DB'de kaynakların hiyerarşisini ve bu kaynakları oluşturmak ve bu kaynaklara erişmek için kullanılan nesne modelini incelemeye başlayalım. Azure Cosmos DB kaynakları aşağıdaki sırada oluşturur:

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

Farklı varlıkların hiyerarşisi hakkında daha fazla bilgi edinmek için, Azure Veritabanı Veritabanı DB'de veritabanları, kapsayıcılar ve öğelerle Cosmos bakın. Bu kaynaklarla etkileşim kurmak için aşağıdaki .NET sınıflarını kullanırsiniz:

  • Client - Bu sınıf, Azure DB hizmeti için istemci tarafı mantıksal Cosmos sunar. İstemci nesnesi, hizmetteki istekleri yapılandırmak ve yürütmek için kullanılır.

  • CreateDatabaseIfNotExistsAsync - Bu yöntem, bir veritabanı kaynağını zaman uyumsuz işlem olarak oluşturur (yoksa) veya alır (zaten varsa).

  • CreateContainerIfNotExistsAsync- Bu yöntem (yoksa) oluşturur veya bir kapsayıcıyı (zaten varsa) zaman uyumsuz işlem olarak alır. Kapsayıcının yeni oluşturularak (201) veya var olan bir kapsayıcının (200) döndürüldü olup olmadığını belirlemek için yanıttan durum kodunu kontrol edin.

  • CreateItemAsync - Bu yöntem kapsayıcı içinde bir öğe oluşturur.

  • UpsertItemAsync - Bu yöntem, önceden yoksa kapsayıcı içinde bir öğe oluşturur veya öğe zaten varsa bunun yerine başka bir öğe oluşturur.

  • GetItemQueryIterator - Bu yöntem, parametreli değerlere sahip bir SQL deyimi kullanarak Azure Cosmos veritabanındaki bir kapsayıcının altındaki öğeler için bir sorgu oluşturur.

  • DeleteAsync - Belirtilen veritabanını Azure Cosmos siler. DeleteAsync yöntemi yalnızca veritabanını siler. Örneği silme ayrı olarak Cosmosclient gerçekleşecektir (DeleteDatabaseAndCleanupAsync yönteminde bunu yapar).

Kod örnekleri

Bu makalede açıklanan örnek kod, Azure Cosmos DB'de bir aile Cosmos oluşturur. Aile veritabanı ad, adres, konum, ilişkili ebeveynler, çocuklar ve evcil hayvanlar gibi aile ayrıntılarını içerir. Verileri Azure Cosmos hesabınızla toplamadan önce, bir aile öğesinin özelliklerini tanımlayın. Örnek uygulamanın kök Family.cs düzeyinde adı olan yeni bir sınıf oluşturun ve sınıfa aşağıdaki kodu ekleyin:

using Newtonsoft.Json;

namespace todo
{
    public class Family
    {
        [JsonProperty(PropertyName = "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; }
        // The ToString() method is used to format the output, it's used for demo purpose only. It's not required by Azure Cosmos DB
        public override string ToString()
        {
            return JsonConvert.SerializeObject(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; }
    }
}

Yönergeleri kullanmanın istemci & nesnesini tanımlaması

Proje dizininden dosyayı düzenleyicide açın ve uygulamanın üst kısmında yer alan yönergeleri Program.cs kullanarak aşağıdaki yönergeleri ekleyin:


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

Program.cs dosyasına, önceki adımda ayar istediğiniz ortam değişkenlerini okumak için kod ekleyin. , CosmosClient ve Database nesneleri Container tanımlayın. Ardından, Azure kaynaklarınızı yönetme yönteminizi GetStartedDemoAsync çağıran ana yönteme Cosmos ekleyin.

namespace todo
{
public class Program
{

    /// The Azure Cosmos DB endpoint for running this GetStarted sample.
    private string EndpointUrl = Environment.GetEnvironmentVariable("EndpointUrl");

    /// The primary key for the Azure DocumentDB account.
    private string PrimaryKey = Environment.GetEnvironmentVariable("PrimaryKey");

    // The Cosmos client instance
    private CosmosClient cosmosClient;

    // The database we will create
    private Database database;

    // The container we will create.
    private Container container;

    // The name of the database and container we will create
    private string databaseId = "FamilyDatabase";
    private string containerId = "FamilyContainer";

    public static async Task Main(string[] args)
    {
       try
       {
           Console.WriteLine("Beginning operations...\n");
           Program p = new Program();
           await p.GetStartedDemoAsync();

        }
        catch (CosmosException de)
        {
           Exception baseException = de.GetBaseException();
           Console.WriteLine("{0} error occurred: {1}", de.StatusCode, de);
        }
        catch (Exception e)
        {
            Console.WriteLine("Error: {0}", e);
        }
        finally
        {
            Console.WriteLine("End of demo, press any key to exit.");
            Console.ReadKey();
        }
    }
}
}

Veritabanı oluşturma

Yöntemi CreateDatabaseAsync sınıf içinde program.cs tanımlayın. Bu FamilyDatabase yöntem, daha önce yoksa oluşturur.

private async Task CreateDatabaseAsync()
{
    // Create a new database
    this.database = await this.cosmosClient.CreateDatabaseIfNotExistsAsync(databaseId);
    Console.WriteLine("Created Database: {0}\n", this.database.Id);
}

Kapsayıcı oluşturma

Yöntemi CreateContainerAsync sınıf içinde program.cs tanımlayın. Bu FamilyContainer yöntem, daha önce yoksa oluşturur.

/// Create the container if it does not exist. 
/// Specifiy "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
private async Task CreateContainerAsync()
{
    // Create a new container
    this.container = await this.database.CreateContainerIfNotExistsAsync(containerId, "/LastName");
    Console.WriteLine("Created Container: {0}\n", this.container.Id);
}

Öğe oluşturma

Aşağıdaki kodla yöntemi ekleyerek AddItemsToContainerAsync bir aile öğesi oluşturun. Öğe oluşturmak için CreateItemAsyncUpsertItemAsync veya yöntemlerini kullanabilirsiniz:

private async Task AddItemsToContainerAsync()
{
    // 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
    };

    try
    {
        // 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 this.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 of 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} Operation consumed {1} RUs.\n", andersenFamilyResponse.Resource.Id, andersenFamilyResponse.RequestCharge);
    }
    catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
    {
        Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamily.Id);                
    }
}

Öğeleri sorgulama

Öğe ekledikten sonra, "Andersen" ailesinin ayrıntılarını almak için sorgu çalıştırabilirsiniz. Aşağıdaki kodda, sorgunun doğrudan Sorgu Tasarımcısı SQL yürütül olduğu gösterir. "SQL" aile ayrıntılarını almak için aşağıdaki sorguyu kullanın: SELECT * FROM c WHERE c.LastName = 'Andersen' . Yöntemi QueryItemsAsync sınıf içinde program.cs tanımlayın ve aşağıdaki kodu sınıfa ekleyin:

private async Task QueryItemsAsync()
{
    var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";

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

    QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);
    FeedIterator<Family> queryResultSetIterator = this.container.GetItemQueryIterator<Family>(queryDefinition);

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

    while (queryResultSetIterator.HasMoreResults)
    {
        FeedResponse<Family> currentResultSet = await queryResultSetIterator.ReadNextAsync();
        foreach (Family family in currentResultSet)
        {
            families.Add(family);
            Console.WriteLine("\tRead {0}\n", family);
        }
    }
}

Veritabanını silme

Son olarak, yöntemi ekleyen veritabanını DeleteDatabaseAndCleanupAsync aşağıdaki kodla silebilirsiniz:

private async Task DeleteDatabaseAndCleanupAsync()
{
   DatabaseResponse databaseResourceResponse = await this.database.DeleteAsync();
   // Also valid: await this.cosmosClient.Databases["FamilyDatabase"].DeleteAsync();

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

   //Dispose of CosmosClient
    this.cosmosClient.Dispose();
}

CRUD işlemlerini yürütme

Gerekli tüm yöntemleri tanımdikten sonra, bunları yöntemde GetStartedDemoAsync yürütün. Bu yöntem yürütülürse hiç kaynak görmey DeleteDatabaseAndCleanupAsync olamayacak olduğundan, bu kodda açıklama yapılan yöntem. Azure portalda oluşturulmuş Azure Cosmos DB kaynaklarınızı doğruladikten sonra bu kaynakla ilgili onayları geri alırsınız.

public async Task GetStartedDemoAsync()
{
    // Create a new instance of the Cosmos Client
    this.cosmosClient = new CosmosClient(EndpointUrl, PrimaryKey);
    await this.CreateDatabaseAsync();
    await this.CreateContainerAsync();
    await this.AddItemsToContainerAsync();
    await this.QueryItemsAsync();
}

Gerekli tüm yöntemleri ekledikten sonra dosyayı Program.cs kaydedin.

Kodu çalıştırın

Azure Cosmos DB kaynaklarını oluşturmak için sonraki derlemeyi Cosmos çalıştırın. Yeni bir komut istemi penceresi açmayı lütfen ortam değişkenlerini ayarlamak içinle aynı örneği kullanmayın. Ortam değişkenleri geçerli açık pencerede ayarlanmaz. Güncelleştirmeleri görmek için yeni bir komut istemi açabilirsiniz.

dotnet build
dotnet run

Uygulamayı çalıştırarak aşağıdaki çıktı oluşturulur. Ayrıca, Azure portalda oturum açın ve kaynakların oluşturulmuş olduğunu doğrulayın:

Created Database: FamilyDatabase

Created Container: FamilyContainer

Created item in database with id: Andersen.1 Operation consumed 11.62 RUs.

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}

End of demo, press any key to exit.

Azure portalda oturum açın ve Azure Cosmos.

Kaynakları temizleme

Artık gerekli değilken, Azure CLI veya Azure PowerShell'i kullanarak Azure Cosmos hesabını ve ilgili kaynak grubunu kaldırabilirsiniz. Aşağıdaki komut, Azure CLI kullanarak kaynak grubunun nasıl silineceklerini gösterir:

az group delete -g "myResourceGroup"

Sonraki adımlar

Bu hızlı başlangıçta, Azure Cosmos, bir veritabanı ve bir .NET Core uygulaması kullanarak kapsayıcı oluşturmayı öğrendiniz. Artık, aşağıdaki makaledeki yönergelerle Azure Cosmos hesabınıza ek verileri aktarabilirsiniz.

Azure Cosmos DB'ye geçiş için kapasite planlaması yapmaya mı Cosmos çalışıyor musunuz? Kapasite planlaması için var olan veritabanı kümeniz hakkında bilgi kullanabilirsiniz.

  • Tek biliyorsanız, var olan veritabanı kümenizin vcore'larının ve sunucuların sayısıyla ilgili bilgi için, vCore veya vCPUs kullanarak tahmin istekleri birimleri hakkında bilgi edinebilirsiniz
  • Geçerli veritabanı iş yükünüz için genel istek oranlarını biliyorsanız Azure COSMOS DB kapasite planlayıcısı kullanarak tahmin tahmin birimleri hakkında bilgi edinin