Начало работы с Azure Cosmos DB для NoSQL с помощью .NET

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

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

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

Необходимые компоненты

Настройка проекта

Создайте консольное приложение .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 :

Подключение с помощью конечной точки и ключа

Наиболее распространенный конструктор для CosmosClient имеет два параметра:

Параметр Пример значения Description
accountEndpoint Переменная среды COSMOS_ENDPOINT. API для конечной точки NoSQL, используемой для всех запросов
authKeyOrResourceToken Переменная среды COSMOS_KEY. Ключ учетной записи или маркер ресурса для использования при проверке подлинности

Получение конечной точки и ключа учетной записи

  1. Создайте переменную оболочки для resourceGroupName.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-dotnet-howto-rg"

  2. Используйте команду 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
)

  3. URI конечной точки NoSQL для учетной записи с помощью az cosmosdb show команды.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. Найдите PRIMARY KEY в списке ключей для учетной записи с помощью команды az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  5. Запишите значения 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. строка Подключение ion к учетной записи API для NoSQL

Получение строки подключения к учетной записи

  1. Используйте команду 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
)

  2. Найдите 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 в контейнере.

На следующей схеме показана связь между этими ресурсами.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

Каждый тип ресурса представлен одним или несколькими связанными классами .NET. Ниже приведен список наиболее распространенных классов.

Класс Description
CosmosClient Этот класс является логическим представлением службы Azure Cosmos DB на стороне клиента. Этот клиентский объект позволяет настраивать и выполнять запросы к службе.
Database Этот класс является ссылкой на базу данных, которая может еще не существовать в службе. База данных проверяется на стороне сервера при попытке доступа к ней или выполнении операции с ней.
Container Этот класс представляет собой ссылку на контейнер, который тоже может еще не существовать в службе. Контейнер проверяется на стороне сервера при попытке работы с ним.

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

Руководство Description
Создание базы данных Создание баз данных
Создание контейнера Создание контейнеров
Чтение элемента Точечное чтение определенного элемента
Запрос элементов Запрос нескольких элементов

См. также

Следующие шаги

Теперь, когда вы подключились к учетной записи API для NoSQL, используйте следующее руководство для создания баз данных и управления ими.

Создание базы данных в Azure Cosmos DB для NoSQL с помощью .NET