Läsa ett objekt i Azure Cosmos DB för NoSQL med hjälp av .NET

GÄLLER FÖR: NoSQL

Objekt i Azure Cosmos DB representerar en specifik entitet som lagras i en container. I API:et för NoSQL består ett objekt av JSON-formaterade data med en unik identifierare.

Läsa objekt med unika identifierare

Varje objekt i Azure Cosmos DB för NoSQL har en unik identifierare som anges av id egenskapen. Inom omfånget för en container kan två objekt inte dela samma unika identifierare. Azure Cosmos DB kräver dock både den unika identifieraren och partitionsnyckelvärdet för ett objekt för att utföra en snabbpunktsläsning av objektet. Om endast den unika identifieraren är tillgänglig måste du utföra en mindre effektiv fråga för att leta upp objektet över flera logiska partitioner. Mer information om punktläsningar och frågor finns i Optimera kostnaden för begäranden för att läsa data.

Läsa ett objekt

Anteckning

Exemplen i den här artikeln förutsätter att du redan har definierat en C#-typ som representerar dina data med namnet Product:

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

Om du vill utföra en punktläsning av ett objekt anropar du någon av följande metoder:

• ReadItemAsync<>
• ReadItemStreamAsync<>
• ReadManyItemsAsync<>

Läsa ett objekt asynkront

Följande exempelpunkt läser ett enskilt objekt asynkront och returnerar ett deserialiserat objekt med den angivna generiska typen:

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

Metoden Database.ReadItemAsync<> läser ett objekt och returnerar ett objekt av typen ItemResponse<>. Typen ItemResponse<> ärver från Response<> typen, som innehåller en implicit konverteringsoperator för att konvertera objektet till den allmänna typen. Mer information om implicita operatorer finns i användardefinierade konverteringsoperatorer.

Du kan också returnera den allmänna typen ItemResponse<> och uttryckligen hämta resursen. Den mer allmänna Typen ItemResponse<> innehåller även användbara metadata om den underliggande API-åtgärden. I det här exemplet samlas metadata om kostnaden för begärandeenheten för den här åtgärden in med egenskapen 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;

Läsa ett objekt som en ström asynkront

Det här exemplet läser ett objekt som en dataström direkt:

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

Metoden Container.ReadItemStreamAsync returnerar objektet som en Stream utan att deserialisera innehållet.

Om du inte planerar att deserialisera objekten direkt kan dataström-API:erna förbättra prestanda genom att lämna över objektet som en ström direkt till nästa komponent i ditt program. Fler tips om hur du optimerar SDK för scenarier med höga prestanda finns i SDK-prestandatips.

Läsa flera objekt asynkront

I det här exemplet används en lista över tupplar som innehåller unika identifierare och partitionsnyckelpar för att leta upp och hämta flera objekt:

// 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<> returnerar en lista med objekt baserat på de unika identifierare och partitionsnycklar som du anger. Den här åtgärden är avsedd att fungera bättre svarstidsmässigt än en fråga med IN instruktioner för att hämta ett stort antal oberoende objekt.

Nästa steg

Nu när du har läst olika objekt använder du nästa guide för att fråga efter objekt.

Frågeobjekt