Créer un élément dans Azure Cosmos DB for Table à l’aide de .NET

Article
08/15/2024

S’APPLIQUE À : Table

Dans Azure Cosmos DB, les éléments représentent une entité spécifique stockée dans une table. Dans l’API pour Table, un élément se compose d’un ensemble de paires clé-valeur identifiées de manière unique par la combinaison des clés de ligne et de partition.

Créer un identificateur unique pour un élément

L’identificateur unique (**** en programmation) est une chaîne distincte qui identifie un élément dans une table. Chaque élément inclut également une valeur de clé de partition utilisée pour déterminer la partition logique de l’élément. Les deux clés sont nécessaires lorsque vous créez un élément dans une table.

Dans l’étendue d’une table, deux éléments ne peuvent pas partager la même clé de ligne et la même clé de partition.

Créer un élément

La classe TableEntity est une implémentation générique d’un dictionnaire qui est conçu de manière unique pour faciliter la création d’un élément à partir d’un dictionnaire arbitraire de paires clé-valeur.

Utilisez l’une des stratégies suivantes pour modéliser les éléments que vous souhaitez créer dans une table :

Créer une instance de la classe TableEntity
Implémenter l’interface ITableEntity

Utiliser une classe intégrée

Le constructeur (string rowKey, string partitionKey) de la classe TableEntity est un moyen rapide de créer un élément à l’aide uniquement des propriétés nécessaires. Vous pouvez ensuite utiliser la méthode Add pour ajouter des paires clé-valeur supplémentaires à l’élément.

Par exemple, vous pouvez créer une nouvelle instance de la classe TableEntity en spécifiant d’abord les clés de ligne et de partition dans le constructeur, puis en ajoutant de nouvelles paires clé-valeur au dictionnaire :

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

Le constructeur (IDictionary<string, object>) de la classe TableEntity convertit un dictionnaire existant en un élément prêt à être ajouté à une table.

Par exemple, vous pouvez passer un dictionnaire à une nouvelle instance de la classe 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);

La méthode TableClient.AddEntityAsync<> prend un paramètre de type TableEntity, puis crée un élément côté serveur dans la table.

Implémenter une interface

Notes

Les exemples de cette section partent du principe que vous avez déjà défini un type C# pour représenter vos données nommé 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!;
}

La méthode TableClient.AddEntityAsync<> prend un paramètre de tout type qui implémente l’interface ITableEntity. L’interface comprend déjà les propriétés nécessaires RowKey et PartitionKey.

Par exemple, vous pouvez créer un objet qui implémente au moins toutes les propriétés nécessaires dans l’interface ITableEntity :

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

Vous pouvez ensuite passer cet objet à la méthode AddEntityAsync<> en créant un élément côté serveur :

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

Étapes suivantes

Maintenant que vous avez créé différents éléments, utilisez le guide suivant pour lire un élément.

Lire un élément

Partager via