Vytvoření položky ve službě Azure Cosmos DB pro tabulku pomocí .NET

Článek
08/15/2024

PLATÍ PRO: Stůl

Položky ve službě Azure Cosmos DB představují konkrétní entitu uloženou v tabulce. V rozhraní API pro tabulku se položka skládá ze sady párů klíč-hodnota jednoznačně identifikovaných složenou z klíčů řádků a oddílů.

Vytvoření jedinečného identifikátoru pro položku

Jedinečný identifikátor, který se programově označuje jako **** je jedinečný řetězec, který identifikuje položku v tabulce. Každá položka obsahuje také hodnotu klíče oddílu, která slouží k určení logického oddílu položky. Při vytváření nové položky v tabulce se vyžadují oba klíče.

V rámci oboru tabulky nemůžou dvě položky sdílet stejný klíč řádku i klíč oddílu.

Vytvoření položky

Třída TableEntity je obecná implementace slovníku, která je jedinečně navržená tak, aby usnadnila vytvoření nové položky z libovolného slovníku párů klíč-hodnota.

K modelování položek, které chcete vytvořit v tabulce, použijte jednu z následujících strategií:

Vytvoření instance TableEntity třídy
ITableEntity Implementace rozhraní

Použití předdefinované třídy

Konstruktor (string rowKey, string partitionKey) třídy TableEntity je rychlý způsob, jak vytvořit položku pouze s požadovanými vlastnostmi. Metodu Add pak můžete použít k přidání párů klíč-hodnota navíc k položce.

Můžete například vytvořit novou instanci třídy TableEntity tak, že nejprve zadáte klíč řádku a oddílu v konstruktoru a pak do slovníku přidáte nové páry klíč-hodnota:

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

Konstruktor (IDictionary<string, object>) třídy TableEntity převede existující slovník na položku připravenou k přidání do tabulky.

Například můžete předat slovník nové instanci TableEntity třídy:

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

Metoda TableClient.AddEntityAsync<> přebírá parametr typu TableEntity a pak vytvoří položku na straně serveru v tabulce.

Implementace rozhraní

Poznámka:

Příklady v této části předpokládají, že jste již definovali typ jazyka C#, který představuje vaše data s názvem 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!;
}

Metoda TableClient.AddEntityAsync<> přebírá parametr libovolného typu, který implementuje ITableEntity rozhraní. Rozhraní již obsahuje požadované RowKey vlastnosti a PartitionKey vlastnosti.

Můžete například vytvořit nový objekt, který implementuje alespoň všechny požadované vlastnosti v rozhraní ITableEntity :

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

Tento objekt pak můžete předat metodě AddEntityAsync<> , která vytvoří položku na straně serveru:

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

Další kroky

Když jste teď vytvořili různé položky, přečtěte si položku pomocí další příručky.

Čtení položky

Sdílet prostřednictvím