Начало работы с Azure Cosmos DB для NoSQL с помощью .NET
ОБЛАСТЬ ПРИМЕНЕНИЯ: 
NoSQL
В этой статье показано, как подключиться к Azure Cosmos DB для NoSQL с помощью пакета SDK для .NET. После подключения можно выполнять операции с базами данных, контейнерами и элементами.
Пакет (NuGet) | Примеры | Справочная документация по API | Исходный код библиотеки | Оставить отзыв
Необходимые компоненты
- Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
- Учетная запись Azure Cosmos DB для NoSQL. Создайте учетную запись API для NoSQL.
- .NET 6.0 или более поздней версии
- Интерфейс командной строки (CLI) Azure или Azure PowerShell
Настройка проекта
Создайте новое приложение .NET, используя команду dotnet new с шаблоном console.
dotnet new console
Импортируйте пакет NuGet Microsoft.Azure.Cosmos с помощью команды dotnet add package.
dotnet add package Microsoft.Azure.Cosmos
Создайте проект с помощью команды dotnet build.
dotnet build
Подключение к Azure Cosmos DB для NoSQL
Чтобы подключиться к API для NoSQL Azure Cosmos DB, создайте экземпляр CosmosClient класса. Этот класс является начальной точкой для выполнения всех операций с базами данных.
Чтобы подключиться к учетной записи API для NoSQL с помощью Microsoft Entra, используйте субъект безопасности. Точный тип субъекта будет зависеть от того, где размещается код приложения. Приведенная ниже таблица служит кратким справочным руководством.
| Место выполнения приложения | Субъект безопасности |
|---|---|
| Локальный компьютер (разработка и тестирование) | Удостоверение пользователя или субъект-служба |
| Azure | Управляемое удостоверение |
| Серверы или клиенты вне Azure | Субъект-служба |
Импорт Azure.Identity
Пакет NuGet Azure.Identity содержит основные функции проверки подлинности, общие для всех библиотек пакета SDK Azure.
Импортируйте пакет NuGet Azure.Identity с помощью команды dotnet add package.
dotnet add package Azure.Identity
Повторно создайте проект с помощью команды dotnet build.
dotnet build
В редакторе кода добавьте директивы using для пространств имен Azure.Core и Azure.Identity.
using Azure.Core;
using Azure.Identity;
Создание CosmosClient с реализацией учетных данных по умолчанию
Если вы тестируете на локальном компьютере или приложение будет выполняться в службах Azure с прямой поддержкой управляемых удостоверений, получите маркер OAuth, создав экземпляр DefaultAzureCredential.
В этом примере мы сохранили экземпляр в переменной типа TokenCredential, так как это более универсальный тип, который многократно используется в пакетах SDK.
// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();
Создайте новый экземпляр класса CosmosClient с переменной среды COSMOS_ENDPOINT и объектом TokenCredential в качестве параметров.
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
tokenCredential: credential
);
Сборка приложения
При создании приложения код будет в основном взаимодействовать с четырьмя типами ресурсов:
Учетная запись API для NoSQL, которая является уникальным пространством имен верхнего уровня для данных Azure Cosmos DB.
Базы данных, которые упорядочивают контейнеры в учетной записи.
Контейнеры, содержащие набор отдельных элементов в базе данных.
Элементы, представляющие документ JSON в контейнере.
На следующей схеме показана связь между этими ресурсами.
Иерархическая схема с учетной записью Azure Cosmos DB в верхней части. У учетной записи есть два дочерних узла базы данных. Один из узлов базы данных содержит два дочерних узла контейнера. Другой узел базы данных содержит один дочерний узел контейнера. У этого одного узла контейнера есть три дочерних узла.
Каждый тип ресурса представлен одним или несколькими связанными классами .NET. Ниже приведен список наиболее распространенных классов.
| Класс | Description |
|---|---|
CosmosClient |
Этот класс является логическим представлением службы Azure Cosmos DB на стороне клиента. Этот клиентский объект позволяет настраивать и выполнять запросы к службе. |
Database |
Этот класс является ссылкой на базу данных, которая может еще не существовать в службе. База данных проверяется на стороне сервера при попытке доступа к ней или выполнении операции с ней. |
Container |
Этот класс представляет собой ссылку на контейнер, который тоже может еще не существовать в службе. Контейнер проверяется на стороне сервера при попытке работы с ним. |
Сведения об использовании каждого из этих классов для создания приложения приведены в следующих руководствах.
| Руководство | Description |
|---|---|
| Создание базы данных | Создание баз данных |
| Создание контейнера | Создание контейнеров |
| Чтение элемента | Точечное чтение определенного элемента |
| Запрос элементов | Запрос нескольких элементов |