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

Статья
08/15/2024

Область применения: Таблица

Каждый элемент в Azure Cosmos DB представляет определенную сущность, хранящуюся в таблице. В API для таблицы элемент состоит из набора пар "ключ-значение", однозначно определяемых составом строк и ключей секций.

Создание уникального идентификатора для элемента

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

В области одной таблицы два элемента не могут иметь одинаковые значения ключа строки и ключа секции.

Создание элемента

Класс TableEntity является универсальной реализацией словаря, который создан специально для того, чтобы упростить создание нового элемента из произвольного словаря с парами "ключ — значение".

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

Создайте экземпляр класса TableEntity
Реализация интерфейса ITableEntity

Использование встроенного класса

Конструктор (string rowKey, string partitionKey) для класса TableEntity позволяет быстро создать элемент с ограниченным набором обязательных свойств. После создания элемента примените метод Add для добавления в него дополнительных пар "ключ — значение".

Например, можно создать новый экземпляр класса TableEntity, сначала указав в конструкторе ключи строки и секции, а затем добавив в словарь новые пары "ключ — значение":

// Create new item using composite key constructor
TableEntity item1 = new(
    rowKey: "68719518388",
    partitionKey: "gear-surf-surfboards"
);

// Add properties to item
item1.Add("Name", "Sunnox Surfboard");
item1.Add("Quantity", 8);
item1.Add("Sale", true);

// Add new item to server-side table
await tableClient.AddEntityAsync<TableEntity>(item1);

Конструктор (IDictionary<string, object>) класса TableEntity преобразует существующий словарь в элемент, готовый к добавлению в таблицу.

Например, можно передать словарь в новый экземпляр класса TableEntity:

// Create dictionary
Dictionary<string, object> properties = new()
{
    { "RowKey", "68719518388" },
    { "PartitionKey", "gear-surf-surfboards" },
    { "Name", "Sunnox Surfboard" },
    { "Quantity", 8 },
    { "Sale", true }
};

// Create new item using dictionary constructor
TableEntity item2 = new(
    values: properties
);

// Add new item to server-side table
await tableClient.AddEntityAsync<TableEntity>(item2);

Метод TableClient.AddEntityAsync<> принимает параметр типа TableEntity и создает в таблице серверный элемент.

Реализация интерфейса

Примечание.

В примерах в этом разделе предполагается, что вы уже определили тип C# для представления ваших данных с именем Product.

// 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!;
}

Метод TableClient.AddEntityAsync<> принимает параметр любого типа, в котором реализован интерфейс ITableEntity. Этот интерфейс уже содержит обязательные свойства RowKey и PartitionKey.

Например, вы можете создать новый объект, который реализует по меньшей мере все обязательные свойства в интерфейсе ITableEntity:

// Create new item
Product item = new()
{
    RowKey = "68719518388",
    PartitionKey = "gear-surf-surfboards",
    Name = "Sunnox Surfboard",
    Quantity = 8,
    Sale = true
};

Затем этот объект можно передать в метод AddEntityAsync <>, который создает серверный элемент:

// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(item);

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

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

Чтение элемента

Поделиться через