Начало работы с 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
Создайте новое приложение .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 с помощью класса CosmosClient :
- Подключение с помощью API для конечной точки NoSQL и ключа чтения и записи
- Подключение с помощью API для NoSQL строка подключения
- Подключение с помощью идентификатора Microsoft Entra
Подключение с помощью конечной точки и ключа
Наиболее распространенный конструктор для CosmosClient имеет два параметра:
Параметр | Пример значения | Description |
---|---|---|
accountEndpoint |
Переменная среды COSMOS_ENDPOINT . |
API для конечной точки NoSQL, используемой для всех запросов |
authKeyOrResourceToken |
Переменная среды COSMOS_KEY . |
Ключ учетной записи или маркер ресурса для использования при проверке подлинности |
Получение конечной точки и ключа учетной записи
Создайте переменную оболочки для resourceGroupName.
# Variable for resource group name resourceGroupName="msdocs-cosmos-dotnet-howto-rg"
Используйте команду
az cosmosdb list
, чтобы получить имя первой учетной записи Azure Cosmos DB в группе ресурсов и сохранить его в переменной оболочки accountName.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
URI конечной точки NoSQL для учетной записи с помощью
az cosmosdb show
команды.az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "documentEndpoint"
Найдите PRIMARY KEY в списке ключей для учетной записи с помощью команды
az-cosmosdb-keys-list
.az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"
Запишите значения URI и PRIMARY KEY. Эти учетные данные понадобятся позже.
Чтобы использовать значения URI и PRIMARY KEY в коде .NET, сохраните их в новых переменных среды на локальном компьютере, на котором выполняется приложение.
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
Создание CosmosClient с конечной точкой и ключом учетной записи
Создайте новый экземпляр класса CosmosClient с переменными среды COSMOS_ENDPOINT
и COSMOS_KEY
в качестве параметров.
// New instance of CosmosClient class using an endpoint and key string
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);
Подключение с использованием строки подключения
Другой конструктор для CosmosClient содержит только один параметр:
Параметр | Пример значения | Description |
---|---|---|
accountEndpoint |
Переменная среды COSMOS_ENDPOINT . |
API для конечной точки NoSQL, используемой для всех запросов |
connectionString |
Переменная среды COSMOS_CONNECTION_STRING . |
Строка подключения к учетной записи API для NoSQL |
Получение строки подключения к учетной записи
Используйте команду
az cosmosdb list
, чтобы получить имя первой учетной записи Azure Cosmos DB в группе ресурсов и сохранить его в переменной оболочки accountName.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
Найдите PRIMARY CONNECTION STRING в списке строк подключения для учетной записи с помощью команды
az-cosmosdb-keys-list
.az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "connection-strings" \ --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
Чтобы использовать значение поля ОСНОВНАЯ СТРОКА ПОДКЛЮЧЕНИЯ в коде .NET, сохраните его в новой переменной среды на локальном компьютере, на котором выполняется приложение.
$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"
Создание CosmosClient с помощью строки подключения
Создайте новый экземпляр класса CosmosClient с переменной среды COSMOS_CONNECTION_STRING
в качестве единственного параметра.
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);
Подключение с помощью платформа удостоверений Майкрософт
Чтобы подключиться к учетной записи 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
);
Создание CosmosClient с пользовательской реализацией учетных данных
Если вы планируете развернуть приложение вне Azure, можно получить маркер OAuth с помощью других классов в клиентской библиотеке Azure Identity для .NET. Эти другие классы также являются производными от класса TokenCredential
.
В данном примере мы создадим экземпляр ClientSecretCredential
с помощью идентификаторов клиента и арендатора, а также секрета клиента.
// Custom credential class for servers and clients outside of Azure
TokenCredential credential = new ClientSecretCredential(
tenantId: Environment.GetEnvironmentVariable("AAD_TENANT_ID")!,
clientId: Environment.GetEnvironmentVariable("AAD_CLIENT_ID")!,
clientSecret: Environment.GetEnvironmentVariable("AAD_CLIENT_SECRET")!,
options: new TokenCredentialOptions()
);
При регистрации приложения в Microsoft Entra ID можно получить идентификатор клиента, идентификатор клиента и секрет клиента. Дополнительные сведения о регистрации приложений Microsoft Entra см. в разделе "Регистрация приложения с помощью платформа удостоверений Майкрософт".
Создайте новый экземпляр класса 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 |
---|---|
Создание базы данных | Создание баз данных |
Создание контейнера | Создание контейнеров |
Чтение элемента | Точечное чтение определенного элемента |
Запрос элементов | Запрос нескольких элементов |
См. также
Следующие шаги
Теперь, когда вы подключились к учетной записи API для NoSQL, используйте следующее руководство для создания баз данных и управления ими.