Erstellen eines Elements in Azure Cosmos DB for Table mithilfe von .NET

Artikel
08/15/2024

GILT FÜR: Tabelle

Elemente in Azure Cosmos DB repräsentieren eine bestimmte Entität, die in einer Tabelle gespeichert ist. In der API für Table besteht ein Element aus einem Satz von Schlüssel-Wert-Paaren, die durch die Zusammensetzung der Zeilen- und Partitionsschlüssel eindeutig identifiziert werden.

Erstellen eines eindeutigen Bezeichners für ein Element

Der eindeutige Bezeichner, programmgesteuert als **** bezeichnet, ist eine eindeutige Zeichenfolge, die ein Element innerhalb einer Tabelle identifiziert. Jedes Element enthält auch einen Partitionsschlüsselwert, der zur Bestimmung der logischen Partition des Elements dient. Beide Schlüssel sind beim Erstellen eines neuen Elements in einer Tabelle erforderlich.

Innerhalb eines Tabellenbereichs können zwei Elemente nicht denselben Zeilenschlüssel und Partitionsschlüssel haben.

Erstellen eines Elements

Bei der TableEntity-Klasse handelt es sich um eine generische Implementierung eines Wörterbuchs, mit der Sie ganz einfach in einem beliebigen Wörterbuch mithilfe von Schlüssel-Wert-Paaren ein neues Element erstellen können.

Setzen Sie eine der folgenden Strategien zur Modellierung von Elementen um, die Sie in einer Tabelle erstellen möchten:

Erstellen einer Instanz der TableEntity-Klasse
Implementieren der ITableEntity-Schnittstelle

Verwenden einer integrierten Klasse

Der (string rowKey, string partitionKey)-Konstruktor der TableEntity-Klasse ermöglicht das schnelle Erstellen eines Elements mit nur den erforderlichen Eigenschaften. Sie können dann mit der Add-Methode dem Element zusätzliche Schlüssel-Wert-Paare hinzufügen.

Sie können beispielsweise eine neue Instanz der TableEntity-Klasse erstellen, indem Sie zunächst die Schlüssel row und partition im Konstruktor angeben und dann neue Schlüssel-Wert-Paare zum Wörterbuch hinzufügen:

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

Der (IDictionary<string, object>)-Konstruktor der TableEntity-Klasse konvertiert ein vorhandenes Wörterbuch in ein Element, das einer Tabelle hinzugefügt werden kann.

Sie können z. B. ein Wörterbuch an eine neue Instanz der TableEntity-Klasse übergeben:

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

Die TableClient.AddEntityAsync<>-Methode verwendet einen Parameter des Typs TableEntity und erstellt dann ein serverseitiges Element in der Tabelle.

Implementieren einer Schnittstelle

Hinweis

In den Beispielen dieses Abschnitts wird davon ausgegangen, dass Sie bereits einen C#-Typ namens Product definiert haben, der Ihre Daten darstellt:

// 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!;
}

Die TableClient.AddEntityAsync<>-Methode verwendet einen Parameter eines beliebigen Typs, der die ITableEntity-Schnittstelle implementiert. Die Schnittstelle enthält bereits die erforderlichen Eigenschaften RowKey und PartitionKey.

Sie können beispielsweise ein neues Objekt erstellen, das mindestens alle erforderlichen Eigenschaften der ITableEntity-Schnittstelle implementiert:

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

Sie können dieses Objekt dann an die AddEntityAsync<>-Methode übergeben, die ein serverseitiges Element erstellt:

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

Nächste Schritte

Nachdem Sie nun verschiedene Elemente erstellt haben, erfahren Sie im nächsten Leitfaden, wie Sie ein Element lesen:

Lesen eines Elements

Teilen über