Краткое руководство. Библиотека Azure Cosmos DB для NoSQL для .NET

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

• .NET
• JavaScript/Node.js
• Java
• Python
• Go

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

Пакет исходного кода библиотеки исходного кода | библиотеки | API (NuGet) | Azure Developer CLI

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Учетная запись GitHub

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Интерфейс командной строки разработчика Azure
• Docker Desktop

Установка

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

Внимание

Учетные записи GitHub включают право на хранение и основные часы без затрат. Дополнительные сведения см . в разделе о хранилище и основных часах для учетных записей GitHub.

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

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

   azd auth login
   

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

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

   Примечание.

   В этом кратком руководстве используется репозиторий шаблона GitHub для azure-samples/cosmos-db-nosql-dotnet-quickstart . Azure Developer CLI автоматически клонируется этот проект на компьютер, если он еще не существует.

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

   Совет

   Имя среды также будет использоваться в качестве имени целевой группы ресурсов. В этом кратком руководстве рекомендуется использовать msdocs-cosmos-db.

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
   

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

   dotnet add package Azure.Identity
   

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

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

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

Примеры кода

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

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

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

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

Внимание

Вы также можете авторизовать запросы к службам Azure с помощью паролей, строка подключения или других учетных данных напрямую. Однако этот подход следует использовать с осторожностью. Разработчики должны быть старательными, чтобы никогда не предоставлять эти секреты в небезопасном расположении. Любой, кто получает доступ к паролю или секретному ключу, может пройти проверку подлинности в службе базы данных. DefaultAzureCredential предлагает улучшенные преимущества управления и безопасности по сравнению с ключом учетной записи, чтобы разрешить проверку подлинности без пароля без риска хранения ключей.

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

CosmosClient client = new(
    accountEndpoint: builder.Configuration["AZURE_COSMOS_DB_NOSQL_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. Этот метод "upserts" элемент фактически заменяет элемент, если он уже существует.

Product item = new(
    id: "68719518391",
    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: "68719518391",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

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

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

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

var query = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.category = @category"
)
    .WithParameter("@category", "gear-surf-surfboards");

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

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

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

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

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

azd down

В GitHub Codespaces удалите работающее пространство кода, чтобы максимально увеличить объем хранилища и основных прав.

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

• Краткое руководство по JavaScript/Node.js
• Краткое руководство для Java
• Краткое руководство по Python
• Краткое руководство по переходу

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

Руководство. Разработка консольного приложения .NET