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

Artikel
08/15/2024

GILT FÜR: NoSQL

Elemente in Azure Cosmos DB stellen eine bestimmte Entität dar, die in einem Container gespeichert ist. In der API für NoSQL besteht ein Element aus Daten im JSON-Format mit einem eindeutigen Bezeichner.

Erstellen eines eindeutigen Bezeichners für ein Element

Der eindeutige Bezeichner ist eine individuelle Zeichenfolge, die ein Element in einem Container identifiziert. Beim Erstellen eines neuen JSON-Dokuments wird nur die Eigenschaft id benötigt. Das folgende JSON-Dokument ist beispielsweise ein gültiges Element in Azure Cosmos DB:

{
  "id": "unique-string-2309509"
}

Im Bereich eines Containers können zwei Elemente nicht den gleichen eindeutigen Bezeichner besitzen.

Wichtig

Bei der Eigenschaft id wird die Groß-/Kleinschreibung beachtet. Eigenschaften mit dem Namen ID, Id, iD oder _id werden als beliebige JSON-Eigenschaft behandelt.

Nach der Erstellung weist der URI für ein Element das folgende Format auf:

https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>/docs/<item-resource-identifier>

Verwenden Sie anstelle des Felds id den systemseitig generierten Ressourcenbezeichner, wenn Sie über einen URI auf das Element verweisen. Weitere Informationen zu systemseitig generierten Elementeigenschaften in Azure Cosmos DB for NoSQL finden Sie unter Eigenschaften eines Elements.

Erstellen eines Elements

Hinweis

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

// C# record type for items in the container
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    bool sale
);

Außerdem wird in den Beispielen davon ausgegangen, dass Sie bereits ein neues Objekt vom Typ Product mit dem Namen newItem erstellt haben:

// Create new item and add to container
Product item = new(
    id: "68719518388",
    category: "gear-surf-surfboards",
    name: "Sunnox Surfboard",
    quantity: 8,
    sale: true
);

Rufen Sie zum Erstellen eines Elements eine der folgenden Methoden auf:

CreateItemAsync<>
ReplaceItemAsync<>
UpsertItemAsync<>

Asynchrones Erstellen eines Elements

Im folgenden Beispiel wird ein neues Element asynchron erstellt:

Product createdItem = await container.CreateItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Im Falle eines Konflikts mit dem eindeutigen Bezeichner eines bereits vorhandenen Elements wird von der Methode Container.CreateItemAsync<> eine Ausnahme ausgelöst. Weitere Informationen zu potenziellen Ausnahmen finden Sie in den Ausnahmen für CreateItemAsync<>.

Asynchrones Ersetzen eines Elements

Im folgenden Beispiel wird ein bereits vorhandenes Element asynchron ersetzt:

Product replacedItem = await container.ReplaceItemAsync<Product>(
    item: item,
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Bei der Methode Container.ReplaceItemAsync<> muss die für den Parameter id angegebene Zeichenfolge dem eindeutigen Bezeichner des Parameters item entsprechen.

Asynchrones Erstellen oder Ersetzen eines Elements

Im folgenden Beispiel wird ein neues Element erstellt oder ein vorhandenes Element ersetzt, wenn bereits ein Element mit dem gleichen eindeutigen Bezeichner vorhanden ist:

Product upsertedItem = await container.UpsertItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Die Methode Container.UpsertItemAsync<> verwendet den eindeutigen Bezeichner des Parameters item, um zu bestimmen, ob ein Konflikt mit einem bereits vorhandenen Element vorliegt, und um das Element entsprechend zu ersetzen.

Nächste Schritte

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

Lesen eines Elements

Freigeben über