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

Artikel
08/15/2024

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 JSON-geformatteerde gegevens 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. Voor Azure Cosmos DB is echter zowel de unieke id als de waarde van de partitiesleutel van een item vereist om een snel leespunt 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 de aanvraagkosten voor het lezen van gegevens optimaliseren voor meer informatie over puntlees- en query's.

Een item lezen

Notitie

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

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

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

ReadItemAsync<>
ReadItemStreamAsync<>
ReadManyItemsAsync<>

Een item asynchroon lezen

Het volgende voorbeeldpunt leest asynchroon één item en retourneert een gedeserialiseerd item 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 meer algemene ItemResponse-type<> bevat ook nuttige metagegevens over de onderliggende API-bewerking. In dit voorbeeld worden metagegevens over de kosten voor 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 lezen als een stream

In dit voorbeeld wordt een item rechtstreeks als 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 item Stream zonder deserialiseren van de inhoud.

Als u niet van plan bent om de items rechtstreeks te deserialiseren, kunt u met behulp van de stream-API's de prestaties verbeteren door het item rechtstreeks als een stream uit te geven aan het volgende onderdeel van uw toepassing. 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's uitvoeren op items

Delen via