共用方式為

使用 .NET 在 Azure Cosmos DB for Table 中建立項目

  • 發行項

適用於： 桌子

Azure Cosmos DB 中的項目代表儲存在資料表內的特定實體。 在 API for Table 中，項目是由一組索引鍵值組所組成，其是由資料列和分割區索引鍵的組合所唯一1識別。

建立項目的唯一識別碼

唯一識別碼 (程式設計上稱為 ****) 是用於識別資料表內項目的不同字串。 每個項目也會包含分割區索引鍵值，用來判斷項目的邏輯分割區。 在資料表內建立新項目時會需要這兩個索引鍵。

在同一資料表內，兩個項目無法共用相同的資料列索引鍵和分割區索引鍵。

建立項目

TableEntity 類別是字典的泛型實作，專門用於讓您輕鬆地根據索引鍵/值組的任意字典建立新項目。

使用下列其中一個策略來針對您想要在資料表中建立的項目建立模型：

使用內建類別

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# 類型以代表名稱為 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);

下一步

既然您已建立各種項目，請使用下一個指南來讀取項目。

讀取項目