Краткое руководство. 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 (azd), чтобы создать учетную запись Azure Cosmos DB для таблицы и развернуть контейнерное пример приложения. Пример приложения использует клиентская библиотека для управления, создания, чтения и запроса примеров данных.

Open in GitHub Codespaces

Open in Dev Container

Внимание

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

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

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

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

    azd init
    
  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-адрес консоли для перехода к веб-приложению в браузере. Просмотрите выходные данные запущенного приложения.

    Screenshot of the running web application.

Установка клиентской библиотеки

Клиентская библиотека доступна через 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.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 для ресурсов таблиц.