hızlı başlangıç: Azure Cosmos DB SQL apı kaynaklarını yönetmek için bir .net konsol uygulaması oluşturma

Makale
11/25/2021
Okumak için 11 dakika

UYGULANDıĞı YER: SQL API

.net için Azure Cosmos DB SQL apı istemci kitaplığı ile çalışmaya başlayın. .net paketini yüklemek, bir uygulama derlemek ve Azure Cosmos DB depolanan veriler üzerinde temel crud işlemleri için örnek kodu denemek üzere bu belgedeki adımları izleyin.

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şturma
Kapsayıcıya örnek veri ekleme
Verileri sorgulama
Veritabanını silme

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

Önkoşullar

azure aboneliği- ücretsiz olarak bir tane oluşturun veya azure aboneliği olmadan ücretsiz Azure Cosmos DB deneyebilir , ücretsiz ve taahhütlere sahip olabilirsiniz.
.NET Core 2,1 SDK veya üzeri.

Ayarlanıyor

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 projeyi ayarlama işlemi adım adım açıklanmaktadır. Bu makalede açıklanan örnek kod, bu FamilyDatabase veritabanı içindeki bir veritabanı ve aile üyelerini (her aile üyesi bir öğedir) oluşturur. Her aile üyesinin gibi özellikleri vardır 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 DB hesabı oluşturmanız gerekir. sizin için bir Azure Cosmos DB 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. Bu hizmet, Bash veya PowerShell ile çalışma şeklinize en uygun kabuk deneyimini seçme esnekliği getirir. Bu hızlı başlangıçta Bash modu ' nu seçin. Azure Cloud Shell Ayrıca bir depolama hesabı gerektirir, istendiğinde bir tane oluşturabilirsiniz.

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. Sonra Azure Cloud Shell ve çalıştırmak için aşağıdaki kodu yapıştırın. Azure Cosmos hesap adı genel olarak benzersiz olmalıdır, 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, 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 çıkışını görebilirsiniz. komut başarıyla tamamlandıktan sonra, 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.

Yeni bir .NET uygulaması oluşturun

Tercih ettiğiniz düzenleyicide veya IDE 'de yeni 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. Adında yeni bir uygulama oluşturmak için aşağıdaki DotNet New komutunu çalıştırın todo . --LangVersion parametresi, oluşturulan proje dosyasındaki LangVersion özelliğini ayarlar.

dotnet new console --langVersion 7.1 -n todo

Dizininizi yeni oluşturulan uygulama klasörüyle değiştirin. Uygulamayı ile oluşturabilirsiniz:

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\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ükler

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

dotnet add package Microsoft.Azure.Cosmos

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çirmeniz gerekir. aşağıdaki adımları izleyerek Azure Cosmos hesabı kimlik bilgilerinizi alın:

Azure Portal oturum açın.
Azure Cosmos hesabınıza gidin.
Anahtarlar bölmesini açın ve hesabınızın URI ve birincil anahtarını kopyalayın. Bir sonraki adımda bir ortam değişkenine URI ve anahtar değerleri ekleyeceksiniz.

Ortam değişkenlerini ayarlama

Hesabınızın URI 'Sini ve birincil anahtarını kopyaladıktan sonra, uygulamayı çalıştıran yerel makinede yeni bir ortam değişkenine kaydedin. Ortam değişkenini ayarlamak için bir konsol penceresi açın ve aşağıdaki komutu çalıştırın. Ve değerlerini değiştirdiğinizden emin <Your_Azure_Cosmos_account_URI> olun <Your_Azure_Cosmos_account_PRIMARY_KEY> .

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şturmaya başlamadan ö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

farklı varlıkların hiyerarşisi hakkında daha fazla bilgi edinmek için, Azure Cosmos DB makalesinde veritabanları, kapsayıcılar ve öğelerle çalışma 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 bir veritabanı kaynağını zaman uyumsuz bir işlem olarak alır (varsa).
Createcontainerıfnotexistsasync--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.
getıtemqueryıterator -bu yöntem, parametreli değerler içeren bir SQL ifadesini kullanarak Azure Cosmos veritabanındaki bir kapsayıcı altındaki öğeler için bir sorgu oluşturur.
deleteasync -belirtilen veritabanını Azure Cosmos hesabınızdan siler. DeleteAsync Yöntem yalnızca veritabanını siler. Örneği elden atılırken Cosmosclient ayrı olarak gerçekleşmesi gerekir (DeleteDatabaseAndCleanupAsync yönteminde olduğu gibi).

Kod örnekleri

bu makalede açıklanan örnek kod, Azure Cosmos DB bir aile veritabanı oluşturur. Aile veritabanı ad, adres, konum, ilişkili üst öğeler, alt öğeler ve Evcil hayvan gibi aile ayrıntılarını içerir. verileri Azure Cosmos hesabınıza 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 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; }
    }
}

İstemci nesnesini tanımlamak & using yönergelerini ekleyin

Proje dizininden Program.cs dosyayı Düzenleyicinizde açın ve uygulamanızın en üstüne aşağıdaki kullanım yönergelerini 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 ayarlamış olduğunuz ortam değişkenlerini okumak için kod ekleyin. , CosmosClient Database ve nesnelerini Container tanımlayın. Ardından, Azure hesap kaynaklarını yönetmek için yöntemini 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

sınıfının CreateDatabaseAsync içinde yöntemini program.cs tanımlayın. Bu FamilyDatabase yöntem, henüz 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

sınıfının CreateContainerAsync içinde yöntemini program.cs tanımlayın. Bu FamilyContainer yöntem, henüz 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öntemini ekleyerek AddItemsToContainerAsync bir aile öğesi oluşturun. Öğe oluşturmak için CreateItemAsync veya UpsertItemAsync 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 " And öğesinin" ailesinin ayrıntılarını almak için bir sorgu çalıştırabilirsiniz. Aşağıdaki kod, doğrudan sorguyu kullanarak sorgunun nasıl SQL gösterir. "SQL" ailesi ayrıntılarını almak için aşağıdaki sorguyu kullanın: SELECT * FROM c WHERE c.LastName = 'Andersen' . sınıfının QueryItemsAsync içinde yöntemini program.cs tanımlayın ve bu yönteme aşağıdaki kodu 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 aşağıdaki kodla yöntemini DeleteDatabaseAndCleanupAsync ekleyerek veritabanını 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 yönteminde ile GetStartedDemoAsync yürütün. Yöntem DeleteDatabaseAndCleanupAsync yürütülürse kaynak görmeyebilirsiniz çünkü yöntemi bu kodda açıklama ek olarak ek açıklama ekledi. Azure Cosmos DB kaynaklarınızı Azure portal.

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ırma

Ardından uygulamayı derlemek ve çalıştırmak için Azure veritabanı Cosmos oluşturun. Yeni bir komut istemi penceresi açmayın, ortam değişkenlerini ayarlamak için kullanılan ö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 çıkış oluşturulur. Ayrıca, Azure portal ve kaynakların oluşturularak doğrulanabilir:

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.

Veri kaynağında oturum açın ve Azure Azure portal hesapta gerekli öğeleri görerek verilerin Cosmos doğruabilirsiniz.

Kaynakları temizleme

Artık gerekli değilken Azure CLI veya Azure PowerShell 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 hesabı oluşturma, .NET Core uygulaması kullanarak veritabanı ve kapsayıcı oluşturma hakkında bilgi edindiniz. Artık aşağıdaki makaledeki yönergelerle Azure Cosmos hesabınıza ek veriler aktarabilirsiniz.

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

Mevcut veritabanı kümenizin sanal çekirdek ve sunucu sayısıyla ilgili tüm bilginiz varsa, sanal çekirdek veya vCPUS kullanarak istek birimlerini tahmin hakkında bilgi edinebilirsiniz
Geçerli veritabanı iş yükünüz için tipik istek oranlarını biliyorsanız Azure Cosmos DB kapasite planlayıcısı kullanarak istek birimlerini tahmin hakkında bilgi edinin

Azure Cosmos DB hesabınıza veri aktarma