Краткое руководство. Создание консольного приложения c использованием пакета SDK для .NET версии 4 (предварительная версия) для управления ресурсами учетной записи API SQL для Azure Cosmos DB

ПРИМЕНИМО К: API SQL

Azure Cosmos DB. Руководство по началу работы с клиентской библиотекой API SQL для .NET. Выполните инструкции из этой статьи, чтобы установить пакет .NET версии 4 (Azure.Cosmos) и создать приложение. Затем ознакомьтесь с примером кода для базовых операций CRUD (создания, чтения, обновления и удаления) с данными, которые хранятся в Azure Cosmos DB.

Важно!

Сейчас предоставляется общедоступная предварительная версия пакета SDK для.NET версии 4 для Azure Cosmos DB. Эта предварительная версия предоставляется без соглашения об уровне обслуживания. Ее не следует использовать для производственных рабочих нагрузок. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены.

Дополнительные сведения см. в статье Дополнительные условия использования предварительных выпусков Microsoft Azure.

Azure Cosmos DB — это быстрая база данных NoSQL от Майкрософт с открытыми API для использования в любом масштабе. С помощью Azure Cosmos DB вы можете быстро создавать базы данных с парами "ключ — значение", документами, графами и обращаться к ним. Клиентскую библиотеку API SQL для Azure Cosmos DB для .NET можно использовать для выполнения таких задач:

  • создание контейнера и базы данных Azure Cosmos;
  • добавление примера данных в контейнер;
  • запрос по данным;
  • База данных удаляется.

Исходный код библиотеки | Пакет (NuGet)

Предварительные требования

Настройка

В этом разделе описывается создание учетной записи Azure Cosmos и настройка проекта, в котором для управления ресурсами используется клиентская библиотека API SQL для Azure Cosmos DB для. NET.

С помощью описанного в этой статье примера кода создается база данных FamilyDatabase и записи для членов семьи в этой базе данных. Каждая запись для члена семьи является элементом и имеет свойства Id, FamilyName, FirstName, LastName, Parents, Children и Address. Свойство LastName используется в качестве ключа секции для контейнера.

Создание учетной записи Azure Cosmos

Если для создания учетной записи Azure Cosmos вы используете бесплатную пробную версию Azure Cosmos DB, нужно создать учетную запись Azure Cosmos DB с типом API SQL. Тестовая учетная запись Azure Cosmos уже создана. Нет необходимости явно создавать учетную запись, поэтому вы можете пропустить этот раздел и перейти к следующему.

Если у вас есть собственная подписка Azure или вы создали бесплатную подписку, вам следует явно создать учетную запись Azure Cosmos. Следующий код создаст учетную запись Azure Cosmos с согласованностью сеанса. Учетная запись реплицируется в South Central US и в North Central US.

Для создания учетной записи Cosmos Azure можно использовать Azure Cloud Shell. Azure Cloud Shell — это интерактивная, аутентифицированная, доступная в браузере оболочка для управления ресурсами Azure. Она предоставляет гибкие возможности при выборе оболочки, соответствующей вашим методам работы, будь то Bash или PowerShell.

Для этого краткого руководства используйте Bash. Также для Azure Cloud Shell требуется учетная запись хранения. Вы можете создать ее, когда появится соответствующий запрос.

  1. Нажмите кнопку Попробовать рядом со следующим кодом, выберите режим Bash, а затем — Создать учетную запись хранения и войдите в Cloud Shell.

  2. Скопируйте и вставьте указанный ниже код в Azure Cloud Shell, а затем запустите его. Имя учетной записи Azure Cosmos должно быть глобально уникальным. Не забудьте перед запуском команды обновить значение mysqlapicosmosdb.

    
    # 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
    
    

Создание учетной записи Cosmos Azure занимает некоторое время. После успешного выполнения операции вы можете просмотреть выходные данные подтверждения. Войдите на портал Azure и убедитесь, что теперь существует учетная запись Azure Cosmos с указанным именем. Окно Azure Cloud Shell можно закрыть после создания ресурса.

Создание приложения NET

Создайте консольное приложение .NET в любом редакторе или интегрированной среде разработки. Откройте командную строку Windows или окно терминала с локального компьютера. Все команды в последующих разделах следует выполнять в этой командной строке или окне терминала.

Выполните приведенную ниже команду dotnet new, чтобы создать приложение с именем todo. Параметр --langVersion задает свойство LangVersion в созданном файле проекта.

dotnet new console --langVersion:8 -n todo

Чтобы перейти в только что созданную папку приложения и выполнить в ней сборку приложения, выполните следующие команды:

cd todo
dotnet build

Ожидаемые выходные данные сборки будут выглядеть примерно следующим образом:

  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

В том же каталоге приложения установите клиентскую библиотеку Azure Cosmos DB для .NET Core с помощью команды dotnet add package.

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

Копирование учетных данных Azure Cosmos с портала Azure

Чтобы использовать пример приложения, нужно выполнить проверку подлинности доступа к вашей учетной записи хранения Azure Cosmos. Для проверки подлинности передайте в приложение учетные данные учетной записи Azure Cosmos. Чтобы просмотреть учетные данные учетной записи Azure Cosmos, сделайте следующее:

  1. Войдите на портал Azure.

  2. Перейдите к учетной записи Azure Cosmos.

  3. Откройте панель Ключи и скопируйте значения URI и первичного ключа для учетной записи. Вы добавите эти значения в переменную среды в следующей процедуре.

Информация об объектной модели

Прежде чем продолжать создание приложения, рассмотрим иерархию ресурсов в Azure Cosmos DB и объектную модель, используемую для создания этих ресурсов и доступа к ним. Azure Cosmos DB создает ресурсы в следующем порядке:

  • Учетная запись Azure Cosmos
  • Базы данных
  • Контейнеры
  • Items

Дополнительные сведения об иерархии сущностей см. в статье Модель ресурсов Azure Cosmos DB. Для взаимодействия с этими ресурсами вы будете использовать следующие классы .NET:

  • CosmosClient. Этот класс является логическим представлением службы Azure Cosmos DB на стороне клиента. Этот клиентский объект позволяет настраивать и выполнять запросы к службе.
  • CreateDatabaseIfNotExistsAsync. Этот метод создает ресурс базы данных (если он не существует) или получает его (если ресурс уже существует) в режиме асинхронной операции.
  • CreateContainerIfNotExistsAsync. Этот метод создает контейнер (если он не существует) или получает его (если контейнер уже существует) в режиме асинхронной операции. Вы можете проверить код состояния из ответа, чтобы определить, был ли контейнер вновь создан (201) или возвращен имеющийся контейнер (200).
  • CreateItemAsync. Этот метод создает элемент в контейнере.
  • UpsertItemAsync. Этот метод создает элемент в контейнере, если элемент еще не существует, или заменяет элемент, если он уже существует.
  • GetItemQueryIterator. Этот метод создает запрос поиска элементов в контейнере базы данных Azure Cosmos с использованием инструкции SQL с параметризованными значениями.
  • DeleteAsync. Этот метод удаляет указанную базу данных из учетной записи Azure Cosmos.

Настройка примеров кода

Пример кода, описанный в этой статье, создает семейную базу данных в Azure Cosmos DB. База данных FamilyDatabase содержит сведения о членах семьи: имя, адрес, местоположение, родители, дети и домашние животные.

Перед заполнением данных в своей учетной записи Azure Cosmos определите свойства для элемента семьи. Создайте класс с именем Family.cs на корневом уровне вашего примера приложения и добавьте в него следующий код:

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 и определение объекта клиента

В каталоге проекта откройте файл Program.cs в редакторе и добавьте следующие директивы using в верхней части кода приложения:

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

В класс Program добавьте следующие глобальные переменные: Эти переменные определяют конечные точки, ключи авторизации, имя базы данных и контейнер, которые будут созданы. Не забудьте заменить значения конечных точек и ключей авторизации реальными данными для вашей среды.

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";

Наконец, замените метод Main:

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);
}

Создание базы данных

Определите метод CreateDatabaseAsync в классе program.cs. Этот метод создает базу данных FamilyDatabase, если она еще не существует.

/// <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);
}

Создание контейнера

Определите метод CreateContainerAsync в классе Program. Этот метод создает контейнер FamilyContainer, если он еще не существует.

/// <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);
}

Создание элемента

Создайте элемент семейства, добавив в метод AddItemsToContainerAsync следующий код. Для создания элемента можно использовать метод CreateItemAsync или UpsertItemAsync.

/// <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);
}

Запрос элементов

После вставки элемента вы можете выполнить запрос для получения подробной информации о семье Андерсен. В следующем коде показано, как напрямую выполнить SQL-запрос. SQL-запрос для получения сведений о семье Андерсен выглядит так: SELECT * FROM c WHERE c.LastName = 'Andersen'. Определите метод QueryItemsAsync в классе Program и добавьте в него следующий код:

/// <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);
    }
}

Замена элемента

Прочитайте элемент семьи и обновите его, добавив в метод ReplaceFamilyItemAsync следующий код:

/// <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);
}

Удаление элемента

Удалите элемент семьи, добавив в метод 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);
}

Удаление базы данных

Вы можете удалить базу данных, добавив в метод DeleteDatabaseAndCleanupAsync следующий код:

/// <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);
}

Завершив добавление всех необходимых методов, сохраните файл Program.cs.

Выполнение кода

Запустите приложение, чтобы создать ресурсы Azure Cosmos DB.

dotnet run

При запуске приложения возвращаются следующие выходные данные:

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 и просмотрев необходимые элементы в своей учетной записи Azure Cosmos.

Очистка ресурсов

Когда учетная запись Azure Cosmos и соответствующая группа ресурсов будут уже не нужны, вы можете удалить их через интерфейс командной строки Azure или Azure PowerShell. Следующая команда показывает, как удалить группу ресурсов с помощью интерфейса командной строки Azure:

az group delete -g "myResourceGroup"

Дальнейшие действия

Из этого краткого руководства вы узнали, как создать учетную запись Azure Cosmos, базу данных и контейнер с помощью приложения .NET Core. Теперь вы можете импортировать новые данные в учетную запись Azure Cosmos, используя инструкции из следующей статьи:

Если вы планируете ресурсы для миграции в Azure Cosmos DB, можете использовать для этого сведения о своем кластере базы данных.