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

  • Статья
  • Чтение занимает 8 мин

ОБЛАСТЬ ПРИМЕНЕНИЯ: API таблиц

В этом кратком руководстве показано, как приступить к работе с API таблицами Azure Cosmos DB из приложения .NET. API таблиц Cosmos DB — это хранилище данных без схемы, позволяющее приложениям хранить структурированные данные NoSQL в облаке. Вы узнаете, как создавать таблицы и записи, а также выполнять основные задачи в ресурсе Cosmos DB с помощью пакета Azure.Data.Tables (NuGet).

Примечание

Примеры фрагментов кода доступны на GitHub в виде проекта .NET.

Справочная документация по API таблиц | Пакет Azure.Data.Tables (NuGet)

Предварительные требования

Проверка предварительных условий

  • В терминале или командном окне запустите dotnet --list-sdks, чтобы проверить, является ли .NET 6.x одной из доступных версий.
  • Запустите az --version (Azure CLI) или Get-Module -ListAvailable AzureRM (Azure PowerShell), чтобы убедиться, что соответствующие средства командной строки Azure установлены.

Настройка

В этом разделе описано, как создать учетную запись Azure Cosmos и настроить проект, использующий пакеты NuGet API таблиц.

создание учетной записи Azure Cosmos DB;

В этом кратком руководстве будет создана одна учетная запись Azure Cosmos DB с помощью API таблиц.

  1. Создайте переменные оболочки для accountName, resourceGroupName и location.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-quickstart-rg"
location="westus"

# Variable for account name with a randomnly generated suffix
let suffix=$RANDOM*$RANDOM
accountName="msdocs-$suffix"

  2. Если вы еще этого не сделали, войдите в Azure CLI с помощью команды az login.

  3. Используйте команду az group create, чтобы создать новую группу ресурсов в подписке.

    az group create \
    --name $resourceGroupName \
    --location $location

  4. Используйте команду az cosmosdb create, чтобы создать новую учетную запись API таблиц Azure Cosmos DB с параметрами по умолчанию.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location
    --capabilities EnableTable

Получение строки подключения API таблицы

  1. Найдите строку подключения API таблиц в списке строк подключения для учетной записи с помощью команды az cosmosdb list-connection-strings.

    az cosmosdb list-connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName

  2. Скопируйте значения PRIMARY KEY (первичный ключ). Эти учетные данные понадобятся позже.

Создание приложения .NET

Создайте приложение .NET в пустой папке с помощью предпочтительного терминала. Используйте dotnet new console, чтобы создать консольное приложение.

dotnet new console -output <app-name>

Установка пакета NuGet

Добавьте пакет NuGet Azure.Data.Tables в новый проект .NET. Используйте команду dotnet add package, указывающую имя пакета NuGet.

dotnet add package Azure.Data.Tables

Настройка переменных среды

Чтобы использовать значения СТРОКА ПОДКЛЮЧЕНИЯ в коде, задайте это значение на локальном компьютере, на котором выполняется приложение. Чтобы задать переменную среды, используйте предпочтительный терминал для выполнения следующих команд:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

Примеры кода

Пример кода, описанный в этой статье, создает таблицу с именем adventureworks. Каждая запись таблицы содержит сведения о продукте, такие как название, категория, количество и индикатор продажи. Каждый продукт также содержит уникальный идентификатор.

Вы будете использовать следующие классы API таблиц для взаимодействия с этими ресурсами:

  • TableServiceClient — этот класс предоставляет методы для выполнения операций на уровне обслуживания с API таблицами 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. Затем в примере создается элемент, после чего тот же элемент считывается обратно. Наконец, в этом примере создается второй элемент, а затем выполняется запрос, который должен возвращать несколько элементов. При каждом шаге в примере в консоль выводятся метаданные, связанные с выполненными шагами.

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

dotnet run

Выходные данные приложения должны выглядеть следующим образом:

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

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

Если вам больше не нужна учетная запись API таблиц Azure Cosmos DB, вы можете удалить соответствующую группу ресурсов.

Используйте команду az group delete, чтобы удалить группу ресурсов.

az group delete --name $resourceGroupName

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

Из этого краткого руководства вы узнали, как создать учетную запись API таблиц Azure Cosmos DB, создать таблицу и управлять записями с помощью пакета SDK для .NET. Теперь вы можете глубже изучить пакет SDK, чтобы узнать, как выполнять более сложные запросы данных и задачи управления в ресурсах API таблиц Azure Cosmos DB.

Начало работы с API таблиц Azure Cosmos DB и .NET