Краткое руководство. Azure Cosmos DB для таблицы для .NET
Область применения: Таблица
В этом кратком руководстве показано, как приступить к работе с Azure Cosmos DB для таблицы из приложения .NET. Azure Cosmos DB для таблицы — это хранилище данных без схемы, позволяющее приложениям хранить структурированные данные таблицы в облаке. Вы узнаете, как создавать таблицы, строки и выполнять основные задачи в ресурсе Azure Cosmos DB с помощью пакета Azure.Data.Tables (NuGet).
Примечание.
Примеры фрагментов кода доступны на GitHub в виде проекта .NET.
Справочник по API для таблиц в пакете | Azure.Data.Tables (NuGet)
Необходимые компоненты
- Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
- Учетная запись GitHub
- Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
- Интерфейс командной строки разработчика Azure
- Docker Desktop
Установка
Разверните контейнер разработки этого проекта в вашей среде. Затем используйте интерфейс командной строки разработчика Azure (azd), чтобы создать учетную запись Azure Cosmos DB для таблицы и развернуть контейнерное пример приложения. Пример приложения использует клиентская библиотека для управления, создания, чтения и запроса примеров данных.
Внимание
Учетные записи GitHub включают право на хранение и основные часы без затрат. Дополнительные сведения см . в разделе о хранилище и основных часах для учетных записей GitHub.
Откройте терминал в корневом каталоге проекта.
Проверка подлинности в интерфейсе командной строки разработчика Azure с помощью
azd auth login
. Выполните действия, указанные средством для проверки подлинности в CLI с помощью предпочитаемых учетных данных Azure.azd auth login
Используется
azd init
для инициализации проекта.azd init
Во время инициализации настройте уникальное имя среды.
Совет
Имя среды также будет использоваться в качестве имени целевой группы ресурсов. В этом кратком руководстве рекомендуется использовать
msdocs-cosmos-db
.Разверните учетную запись Azure Cosmos DB с помощью
azd up
. Шаблоны Bicep также развертывают пример веб-приложения.azd up
В процессе подготовки выберите подписку и нужное расположение. Дождитесь завершения процесса подготовки. Процесс может занять около пяти минут.
После завершения подготовки ресурсов 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.
Используйте URL-адрес консоли для перехода к веб-приложению в браузере. Просмотрите выходные данные запущенного приложения.
Установка клиентской библиотеки
Клиентская библиотека доступна через NuGet в качестве Microsoft.Azure.Cosmos
пакета.
Откройте терминал и перейдите в папку
/src/web
.cd ./src/web
Если пакет еще не установлен, установите
Azure.Data.Tables
его с помощьюdotnet add package
.dotnet add package Azure.Data.Tables
Кроме того, установите
Azure.Identity
пакет, если он еще не установлен.dotnet add package Azure.Identity
Откройте и просмотрите файл src/web/Cosmos.Samples.Table.Quickstart.Web.csproj , чтобы проверить наличие
Microsoft.Azure.Cosmos
иAzure.Identity
записи.
Примеры кода
Пример кода, описанный в этой статье, создает таблицу с именем adventureworks
. Каждая запись таблицы содержит сведения о продукте, такие как название, категория, количество и индикатор продажи. Каждый продукт также содержит уникальный идентификатор.
Для взаимодействия с этими ресурсами вы будете использовать следующий API для классов таблиц:
TableServiceClient
— Этот класс предоставляет методы для выполнения операций уровня обслуживания с Azure Cosmos DB для таблицы.TableClient
— этот класс позволяет взаимодействовать с таблицами, размещенными в API таблицах Azure Cosmos DB.TableEntity
— этот класс представляет собой ссылку на запись в таблице, позволяющую управлять свойствами и данными столбцов.
аутентификация клиента;
Откройте файл Program.cs из каталога проекта. В редакторе добавьте директиву using для Azure.Data.Tables
.
using Azure.Data.Tables;
Определите новый экземпляр класса TableServiceClient
с помощью конструктора и Environment.GetEnvironmentVariable
, чтобы прочитать строку подключения, которую вы настроили ранее.
// New instance of the TableClient class
TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));
Создание таблицы
Извлеките экземпляр TableClient
с помощью класса TableServiceClient
. Используйте метод TableClient.CreateIfNotExistsAsync
для TableClient
, чтобы создать новую таблицу, если ее пока не существует. Этот метод вернет ссылку на существующую или только что созданную таблицу.
// New instance of TableClient class referencing the server-side table
TableClient tableClient = tableServiceClient.GetTableClient(
tableName: "adventureworks"
);
await tableClient.CreateIfNotExistsAsync();
Создание элемента
Самый простой способ создать новый элемент в таблице — создать класс, реализующий интерфейс ITableEntity
. Затем вы можете добавить свои собственные свойства в класс, чтобы заполнить столбцы данных в этой записи таблицы.
// C# record type for items in the table
public record Product : ITableEntity
{
public string RowKey { get; set; } = default!;
public string PartitionKey { get; set; } = default!;
public string Name { get; init; } = default!;
public int Quantity { get; init; }
public bool Sale { get; init; }
public ETag ETag { get; set; } = default!;
public DateTimeOffset? Timestamp { get; set; } = default!;
}
Создайте элемент в коллекции, используя класс Product
, вызвав TableClient.AddEntityAsync<T>
.
// Create new item using composite key constructor
var prod1 = new Product()
{
RowKey = "68719518388",
PartitionKey = "gear-surf-surfboards",
Name = "Ocean Surfboard",
Quantity = 8,
Sale = true
};
// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(prod1);
Получение элемента
Вы можете извлечь конкретный элемент из таблицы с помощью метода TableEntity.GetEntityAsync<T>
. Укажите partitionKey
и rowKey
в качестве параметров, чтобы определить правильную запись для выполнения быстрого считывания точки этого элемента.
// Read a single item from container
var product = await tableClient.GetEntityAsync<Product>(
rowKey: "68719518388",
partitionKey: "gear-surf-surfboards"
);
Console.WriteLine("Single product:");
Console.WriteLine(product.Value.Name);
Элементы запроса
После вставки элемента вы также можете выполнить запрос, чтобы получить все элементы, соответствующие определенному фильтру, с помощью метода TableClient.Query<T>
. В этом примере продукты фильтруются по категориям с помощью синтаксиса Linq, что является преимуществом использования типизированных моделей ITableEntity
, таких как класс Product
.
Примечание.
Вы также можете запрашивать элементы, используя синтаксис OData. Вы можете увидеть пример этого подхода в руководстве по запросу данных.
// Read multiple items from container
var prod2 = new Product()
{
RowKey = "68719518390",
PartitionKey = "gear-surf-surfboards",
Name = "Sand Surfboard",
Quantity = 5,
Sale = false
};
await tableClient.AddEntityAsync<Product>(prod2);
var products = tableClient.Query<Product>(x => x.PartitionKey == "gear-surf-surfboards");
Console.WriteLine("Multiple products:");
foreach (var item in products)
{
Console.WriteLine(item.Name);
}
Выполнение кода
Это приложение создает таблицу API таблиц Azure Cosmos DB. Затем в примере создается элемент, после чего тот же элемент считывается обратно. Наконец, в этом примере создается второй элемент, а затем выполняется запрос, который должен возвращать несколько элементов. При каждом шаге в примере в консоль выводятся метаданные, связанные с выполненными шагами.
Чтобы запустить приложение, перейдите в каталог приложения и запустите его с помощью терминала.
dotnet run
Выходные данные приложения должны выглядеть следующим образом:
Single product name:
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard
Очистка ресурсов
Если вам больше не нужна учетная запись Azure Cosmos DB для таблицы, можно удалить соответствующую группу ресурсов.
Используйте команду az group delete
, чтобы удалить группу ресурсов.
az group delete --name $resourceGroupName
Следующие шаги
Из этого краткого руководства вы узнали, как создать учетную запись Azure Cosmos DB для таблицы, создать таблицу и управлять записями с помощью пакета SDK для .NET. Теперь вы можете более подробно ознакомиться с пакетом SDK, чтобы узнать, как выполнять более сложные запросы данных и задачи управления в Azure Cosmos DB для ресурсов таблиц.