Быстрый старт: использование Azure Cosmos DB для NoSQL с SDK Azure для .NET

В этом кратком руководстве описано, как развернуть базовое приложение Azure Cosmos DB для NoSQL с помощью пакета SDK Azure для .NET. Azure Cosmos DB для NoSQL — это хранилище данных без схемы, позволяющее приложениям хранить неструктурированные данные в облаке. Запрос данных в контейнерах и выполнение общих операций с отдельными элементами с помощью пакета SDK Azure для .NET.

Справочная документация API | Исходный код библиотеки | Пакет (NuGet) | Azure Developer CLI

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

• Azure Developer CLI
• Docker Desktop
• .NET 9.0

Если у вас нет учетной записи Azure, создайте бесплатную учетную запись, прежде чем начинать работу.

Инициализация проекта

Используйте интерфейс командной строки разработчика Azure (azd) для создания учетной записи Azure Cosmos DB для NoSQL и развертывания контейнерного примера приложения. Пример приложения использует клиентская библиотека для управления, создания, чтения и запроса примеров данных.

1. Откройте терминал в пустом каталоге.

2. Если вы еще не прошли проверку подлинности, выполните проверку подлинности в интерфейсе командной строки разработчика Azure с помощью azd auth login. Выполните действия, указанные средством для проверки подлинности в CLI с помощью предпочитаемых учетных данных Azure.

   azd auth login
   

3. Используется azd init для инициализации проекта.

   azd init --template cosmos-db-nosql-dotnet-quickstart
   

4. Во время инициализации настройте уникальное имя среды.

5. Разверните учетную запись Azure Cosmos DB с помощью azd up. Шаблоны Bicep также развертывают образец веб-приложения.

   azd up
   

6. В процессе подготовки выберите подписку, требуемое расположение и целевую группу ресурсов. Ожидайте завершения процесса подготовки. Процесс может занять около пяти минут.

7. После завершения подготовки ресурсов Azure в выходные данные будет включен URL-адрес работающего веб-приложения.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Используйте URL-адрес консоли для перехода к веб-приложению в браузере. Просмотрите выходные данные запущенного приложения.

Установка клиентской библиотеки

Клиентская библиотека доступна через NuGet в качестве Microsoft.Azure.Cosmos пакета.

1. Откройте терминал и перейдите в папку /src/web .

   cd ./src/web
   

2. Если пакет еще не установлен, Microsoft.Azure.Cosmos можно установить с помощью dotnet add package.

   dotnet add package Microsoft.Azure.Cosmos --version 3.*
   

3. Кроме того, установите Azure.Identity пакет, если он еще не установлен.

   dotnet add package Azure.Identity --version 1.12.*
   

4. Откройте и просмотрите файл src/web/Cosmos.Samples.NoSQL.Quickstart.Web.csproj , чтобы проверить наличие Microsoft.Azure.Cosmos и Azure.Identity записи.

Импорт библиотек

Импортируйте пространства имен Azure.Identity и Microsoft.Azure.Cosmos в код приложения.

using Azure.Identity;

using Microsoft.Azure.Cosmos;

Объектная модель

Примеры кода

• аутентификация клиента;
• Получение базы данных
• Возьмите контейнер
• Создание элемента
• Получить элемент
• Запрос данных

Пример кода в шаблоне использует базу данных с именем cosmicworks и контейнером products. Контейнер products содержит такие сведения, как имя, категория, количество, уникальный идентификатор и флаг продажи для каждого продукта. Контейнер использует /category свойство в качестве ключа логического раздела.

аутентификация клиента;

В этом примере создается новый экземпляр CosmosClient класса и выполняется проверка подлинности с помощью экземпляра DefaultAzureCredential .

DefaultAzureCredential credential = new();

CosmosClient client = new(
    accountEndpoint: "<azure-cosmos-db-nosql-account-endpoint>",
    tokenCredential: new DefaultAzureCredential()
);

Получение базы данных

Используется client.GetDatabase для извлечения существующей базы данных с именем cosmicworks.

Database database = client.GetDatabase("cosmicworks");

Получите контейнер

Получение существующего products контейнера с помощью database.GetContainer.

Container container = database.GetContainer("products");

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

Создайте тип записи C# со всеми элементами, которые необходимо сериализовать в JSON. В этом примере тип имеет уникальный идентификатор и поля для категории, имени, количества, цены и продажи.

public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);

Создайте элемент в контейнере с помощью container.UpsertItem. Этот метод добавляет или обновляет элемент, заменяя элемент на новый, если он уже существует.

Product item = new(
    id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    category: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    price: 850.00m,
    clearance: false
);

ItemResponse<Product> response = await container.UpsertItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Прочитайте предмет

Выполните операцию точечного чтения с помощью полей уникального идентификатора (id) и ключа раздела. Используйте container.ReadItem для эффективного извлечения определенного элемента.

ItemResponse<Product> response = await container.ReadItemAsync<Product>(
    id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Элементы запроса

Выполнение запроса по нескольким элементам в контейнере с помощью container.GetItemQueryIterator. Найдите все элементы в указанной категории с помощью этого параметризованного запроса:

SELECT * FROM products p WHERE p.category = @category

string query = "SELECT * FROM products p WHERE p.category = @category"

var query = new QueryDefinition(query)
  .WithParameter("@category", "gear-surf-surfboards");

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

Выполните обработку результатов запроса, организованных по страницам, циклически проходя через каждую страницу результатов с помощью feed.ReadNextAsync. Используйте feed.HasMoreResults для проверки наличия оставшихся результатов в начале каждого цикла.

List<Product> items = new();
while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        items.Add(item);
    }
}

Изучение данных

Используйте расширение Visual Studio Code для Azure Cosmos DB для изучения данных NoSQL. Вы можете выполнять основные операции с базой данных, включая, но не ограничиваясь следующими:

• Выполнение запросов с использованием блокнота или редактора запросов
• Изменение, обновление, создание и удаление элементов
• Импорт массовых данных из других источников
• Управление базами данных и контейнерами

Для получения дополнительной информации см. как использовать расширение Visual Studio Code для изучения NoSQL данных в Azure Cosmos DB.

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

Если вам больше не нужен пример приложения или ресурсов, удалите соответствующее развертывание и все ресурсы.

azd down

Связанный контент

• Краткое руководство по Node.js
• Краткое руководство по Python
• Краткое руководство для Java
• Быстрый старт
• Краткое руководство по Rust