.NET を使って Azure Cosmos DB for Table の項目を作成する

[アーティクル]
08/15/2024

適用対象: Table

Azure Cosmos DB 内の項目は、テーブル内に格納されている特定のエンティティを表します。 Table 用 API では、項目は、行キーとパーティションキーの複合によって一意に識別されるキーと値のペアのセットで構成されます。

項目の一意識別子を作成する

プログラムには **** と認識される一意識別子は、テーブル内の項目を識別する固有の文字列です。各項目には、項目の論理パーティションを決定するために使用されるパーティションキーの値も含まれています。テーブル内に新しい項目を作成するときは、両方のキーが必要です。

テーブルのスコープ内で、2 つの項目が同じ行キーとパーティションキーの両方を共有することはできません。

項目を作成する

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 型のパラメーターを受け取り、サーバー側項目をテーブルに作成します。

インターフェイスの実装

注意

このセクションの例は、Product という名前のデータを表すために C# 型が既に定義されていることを前提としています。

// 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);

次のステップ

さまざまな項目を作成したので、次のガイドを使用して項目を読み取ります。

項目を読み取る

次の方法で共有