Een item lezen in Azure Cosmos DB for NoSQL met behulp van .NET

Artikel
06/01/2023

VAN TOEPASSING OP: NoSQL

Items in Azure Cosmos DB vertegenwoordigen een specifieke entiteit die is opgeslagen in een container. In de API voor NoSQL bestaat een item uit gegevens in JSON-indeling met een unieke id.

Items met unieke id's lezen

Elk item in Azure Cosmos DB for NoSQL heeft een unieke id die is opgegeven door de id eigenschap . Binnen het bereik van een container kunnen twee items niet dezelfde unieke id delen. Azure Cosmos DB vereist echter zowel de unieke id als de partitiesleutelwaarde van een item om een snelle point read van dat item uit te voeren. Als alleen de unieke id beschikbaar is, moet u een minder efficiënte query uitvoeren om het item op te zoeken in meerdere logische partities. Zie Aanvraagkosten optimaliseren voor het lezen van gegevens voor meer informatie over puntleesbewerkingen en query's.

Een item lezen

Notitie

In de voorbeelden in dit artikel wordt ervan uitgegaan dat u al een C#-type hebt gedefinieerd voor uw gegevens met de naam Product:

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

Als u een puntlezing van een item wilt uitvoeren, roept u een van de volgende methoden aan:

ReadItemAsync<>
ReadItemStreamAsync<>
ReadManyItemsAsync<>

Een item asynchroon lezen

In het volgende voorbeeldpunt wordt één item asynchroon gelezen en wordt een gedeserialiseerd item geretourneerd met behulp van het opgegeven algemene type:

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

De Database.ReadItemAsync<> methode leest een item en retourneert een object van het type ItemResponse<>. Het type ItemResponse<> neemt over van het Response<> type, dat een impliciete conversieoperator bevat om het object te converteren naar het algemene type. Zie Door de gebruiker gedefinieerde conversieoperators voor meer informatie over impliciete operators.

U kunt ook het algemene type ItemResponse<> retourneren en de resource expliciet ophalen. Het algemenere Type ItemResponse<> bevat ook nuttige metagegevens over de onderliggende API-bewerking. In dit voorbeeld worden metagegevens over de kosten van de aanvraageenheid voor deze bewerking verzameld met behulp van de eigenschap RequestCharge .

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

Een item asynchroon als een stream lezen

In dit voorbeeld wordt een item rechtstreeks als een gegevensstroom gelezen:

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

De Container.ReadItemStreamAsync methode retourneert het item als een Stream zonder de inhoud te deserialiseren.

Als u niet van plan bent om de items rechtstreeks te deserialiseren, kunt u de stream-API's gebruiken om de prestaties te verbeteren door het item als een stream rechtstreeks aan het volgende onderdeel van uw toepassing te geven. Zie TIPS voor SDK-prestaties voor meer tips over het optimaliseren van de SDK voor scenario's met hoge prestaties.

Meerdere items asynchroon lezen

In dit voorbeeld wordt een lijst met tuples met unieke id en partitiesleutelparen gebruikt om meerdere items op te zoeken en op te halen:

// 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<> retourneert een lijst met items op basis van de unieke id's en partitiesleutels die u opgeeft. Deze bewerking is bedoeld om een betere latentie uit te voeren dan een query met IN instructies om een groot aantal onafhankelijke items op te halen.

Volgende stappen

Nu u verschillende items hebt gelezen, gebruikt u de volgende handleiding om query's uit te voeren op items.

Query-items

Share via