Sdílet prostřednictvím

Čtení položky ve službě Azure Cosmos DB for NoSQL pomocí .NET

  • Článek

PLATÍ PRO: NoSQL

Položky ve službě Azure Cosmos DB představují konkrétní entitu uloženou v kontejneru. V rozhraní API pro NoSQL se položka skládá z dat ve formátu JSON s jedinečným identifikátorem.

Čtení položek s jedinečnými identifikátory

Každá položka ve službě Azure Cosmos DB for NoSQL má jedinečný identifikátor určený id vlastností. V rámci oboru kontejneru nemůžou dvě položky sdílet stejný jedinečný identifikátor. Azure Cosmos DB ale vyžaduje jedinečný identifikátor i hodnotu klíče oddílu položky k rychlému přečtení této položky. Pokud je k dispozici pouze jedinečný identifikátor, budete muset provést méně efektivní dotaz , abyste mohli vyhledat položku v několika logických oddílech. Další informace o bodech čtení a dotazech najdete v tématu optimalizace nákladů na žádosti o čtení dat.

Čtení položky

Poznámka:

Příklady v tomto článku předpokládají, že jste již definovali typ jazyka C#, který představuje vaše data s názvem Product:

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

Chcete-li provést čtení bodu položky, zavolejte jednu z následujících metod:

Asynchronní čtení položky

Následující příklad bod načte jednu položku asynchronně a vrátí deserializovanou položku pomocí zadaného obecného typu:

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

Metoda Database.ReadItemAsync<> přečte položku a vrátí objekt typu ItemResponse<>. ItemResponse<> typ dědí z Response<> typu, který obsahuje implicitní převodní operátor pro převod objektu na obecný typ. Další informace o implicitních operátorech najdete v tématu operátory převodu definované uživatelem.

Alternativně můžete vrátit obecný typ ItemResponse<> a explicitně získat prostředek. Obecnější typ ItemResponse<> obsahuje také užitečná metadata o základní operaci rozhraní API. V tomto příkladu se shromáždí metadata o poplatcích za jednotku požadavku pro tuto operaci pomocí vlastnosti 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;

Asynchronní čtení položky jako datového proudu

Tento příklad přečte položku jako datový proud přímo:

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

Metoda Container.ReadItemStreamAsync vrátí položku jako položku Stream bez deserializace obsahu.

Pokud neplánujete položky deserializovat přímo, můžete pomocí rozhraní API streamu zlepšit výkon předáním položky jako datového proudu přímo do další komponenty vaší aplikace. Další tipy k optimalizaci sady SDK pro scénáře s vysokým výkonem najdete v tématu Tipy pro zvýšení výkonu sady SDK.

Asynchronní čtení více položek

V tomto příkladu se k vyhledání a načtení více položek používá seznam řazených kolekcí členů obsahující jedinečné identifikátory a páry klíčů oddílů:

// 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<> vrátí seznam položek na základě jedinečných identifikátorů a klíčů oddílů, které zadáte. Tato operace je určená k lepší latenci než dotaz s IN příkazy pro načtení velkého počtu nezávislých položek.

Další kroky

Teď, když jste si přečetli různé položky, použijte dalšího průvodce k dotazování položek.

Dotazování položek