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

• .NET
• Node.js
• Java
• Python
• Вперед
• Rust

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

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

Предпосылки

• Azure Developer CLI (Интерфейс командной строки для разработчиков Azure)
• 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;

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

Имя	Description
CosmosClient	Этот класс является основным клиентским классом и используется для управления метаданными или базами данных на уровне учетной записи.
Database	Этот класс представляет базу данных в учетной записи.
Container	Этот класс в первую очередь используется для выполнения операций чтения, обновления и удаления как для контейнера, так и для элементов, находящихся внутри него.
PartitionKey	Этот класс представляет логический ключ раздела. Этот класс необходим для многих распространенных операций и запросов.

Примеры кода

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

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

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

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

DefaultAzureCredential credential = new();

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

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

Используйте 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 queryDefinition = new QueryDefinition(query)
  .WithParameter("@category", "gear-surf-surfboards");

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

Выполните обработку результатов запроса, организованных по страницам, циклически проходя через каждую страницу результатов с помощью 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 для работы с Azure Cosmos DB для данных NoSQL.

Очистите ресурсы

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

azd down

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

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