使用 .NET 在 Azure Cosmos DB for Table 中创建项

适用对象： 表

Azure Cosmos DB 中的项表示存储在表中的特定实体。 在 API for Table 中，项由一组键值对组成，这些键值对由行键和分区键的组合唯一标识。

为项创建唯一标识符

唯一标识符（在编程上称为 ****）是一个非重复的字符串，用于标识表中的项。 每个项还包括一个分区键值，该值用于确定项的逻辑分区。 在表中创建新项时，需要这两个键。

在一个表的范围内，两个项不能共享相同的行键和分区键。

创建项

TableEntity 类是字典的通用实现，其独特的设计使你可以轻松地从任意键值对字典创建新项。

使用以下策略之一，对要在表中创建的项建模：

• 创建 TableEntity 类的实例
• 实现 ITableEntity 接口

使用内置类

TableEntity 类的 (string rowKey, string partitionKey) 构造函数是一种快速创建仅具有所需属性的项的方法。 然后，你可以使用 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);

TableEntity 类的 (IDictionary<string, object>) 构造函数将现有字典转换为可供添加到表中的项。

例如，可以将字典传递给 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# 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);

后续步骤

现在你已创建各种项，请使用下一个指南读取项。