Lesen 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.

Lesen von Elementen mit eindeutigen Bezeichnern

Jedes Element in Azure Cosmos DB for NoSQL verfügt über einen eindeutigen Bezeichner, der durch die Eigenschaft id angegeben wird. Im Bereich eines Containers können zwei Elemente nicht den gleichen eindeutigen Bezeichner besitzen. Azure Cosmos DB benötigt allerdings sowohl den eindeutigen Bezeichner als auch den Partitionsschlüsselwert eines Elements, um einen schnellen Punktlesevorgang für das Element durchführen zu können. Wenn nur der eindeutige Bezeichner verfügbar ist, müssen Sie eine weniger effiziente Abfrage ausführen, um das Element über mehrere logische Partitionen hinweg nachzuschlagen. Weitere Informationen zu Punktlesevorgängen und Abfragen finden Sie im Artikel „Optimieren der Anforderungskosten in Azure Cosmos DB“ unter Lesen von Daten: Punktlesevorgänge und Abfragen.

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

Rufen Sie zum Ausführen eines Punktlesevorgangs für ein Element eine der folgenden Methoden auf:

ReadItemAsync<>
ReadItemStreamAsync<>
ReadManyItemsAsync<>

Asynchrones Lesen eines Elements

Im folgenden Beispiel wird ein asynchroner Punktlesevorgang für ein einzelnes Element durchgeführt und ein deserialisiertes Element mit dem angegebenen generischen Typ zurückgegeben:

// Read existing item from container
Product readItem = await container.ReadItemAsync<Product>(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Die Methode Database.ReadItemAsync<> liest ein Element und gibt ein Objekt des Typs ItemResponse<> zurück. Der Typ ItemResponse<> erbt vom Typ Response<>, der einen impliziten Konvertierungsoperator enthält, um das Objekt in den generischen Typ zu konvertieren. Weitere Informationen zu impliziten Operatoren finden Sie unter Benutzerdefinierte Konvertierungsoperatoren (C#-Referenz).

Alternativ können Sie den generischen Typ ItemResponse<> zurückgeben und die Ressource explizit abrufen. Der allgemeinere Typ ItemResponse<> enthält auch nützliche Metadaten zum zugrunde liegenden API-Vorgang. In diesem Beispiel werden mithilfe der Eigenschaft RequestCharge Metadaten zu den berechneten Anforderungseinheiten für diesen Vorgang gesammelt.

// Read existing item from container
ItemResponse<Product> readResponse = await container.ReadItemAsync<Product>(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

// Get response metadata
double requestUnits = readResponse.RequestCharge;
HttpStatusCode statusCode = readResponse.StatusCode;

// Explicitly get item
Product readItemExplicit = readResponse.Resource;

Asynchrones Lesen eines Elements als Datenstrom

In diesem Beispiel wird ein Element direkt als Datenstrom gelesen:

// Read existing item from container
using ResponseMessage readItemStreamResponse = await container.ReadItemStreamAsync(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

// Get stream from response
using StreamReader readItemStreamReader = new(readItemStreamResponse.Content);

// (optional) Get stream content
string content = await readItemStreamReader.ReadToEndAsync();

Die Methode Container.ReadItemStreamAsync gibt das Element als Stream zurück, ohne den Inhalt zu deserialisieren.

Wenn Sie nicht vorhaben, die Elemente direkt zu deserialisieren, kann die Verwendung der Stream-APIs zur Verbesserung der Leistung beitragen, da das Element als Datenstrom direkt an die nächste Komponente Ihrer Anwendung übergeben wird. Weitere Tipps zum Optimieren des SDK für Hochleistungsszenarien finden Sie in den SDK-Leistungstipps.

Asynchrones Lesen mehrerer Elemente

In diesem Beispiel wird eine Liste von Tupeln mit Paaren aus eindeutigem Bezeichner und Partitionsschlüssel verwendet, um mehrere Elemente nachzuschlagen und abzurufen:

// Create partition key object
PartitionKey partitionKey = new("gear-surf-surfboards");

// Create list of tuples for each item
List<(string, PartitionKey)> itemsToFind = new()
{
    ("68719518388", partitionKey),
    ("68719518381", partitionKey)
};

// Read multiple items
FeedResponse<Product> feedResponse = await container.ReadManyItemsAsync<Product>(
    items: itemsToFind
);

foreach (Product item in feedResponse)
{
    Console.WriteLine($"Found item:\t{item.name}");
}

Container.ReadManyItemsAsync<> gibt eine Liste von Elementen zurück, die auf den von Ihnen bereitgestellten eindeutigen Bezeichnern und Partitionsschlüsseln basiert. Dieser Vorgang soll eine bessere Latenz als eine Abfrage mit IN -Anweisungen beim Abrufen einer großen Anzahl unabhängiger Elemente erzielen.

Nächste Schritte

Nachdem Sie nun verschiedene Elemente gelesen haben, erfahren Sie im nächsten Leitfaden, wie Sie Elemente abfragen:

Abfrageelemente

Freigeben über