Ler um item no Azure Cosmos DB para NoSQL com .NET

  • Artigo

APLICA-SE A: NoSQL

Os itens no Azure Cosmos DB representam uma entidade específica armazenada num contentor. Na API para NoSQL, um item consiste em dados formatados em JSON com um identificador exclusivo.

Ler itens com identificadores exclusivos

Cada item no Azure Cosmos DB para NoSQL tem um identificador exclusivo especificado pela id propriedade. No âmbito de um contentor, dois itens não podem partilhar o mesmo identificador exclusivo. No entanto, o Azure Cosmos DB requer o identificador exclusivo e o valor da chave de partição de um item para realizar uma leitura rápida desse item. Se apenas o identificador exclusivo estiver disponível, terá de efetuar uma consulta menos eficiente para procurar o item em várias partições lógicas. Para saber mais sobre leituras de pontos e consultas, veja Otimizar o custo do pedido para ler dados.

Ler um item

Nota

Os exemplos neste artigo partem do princípio de que já definiu um tipo C# para representar os seus dados denominados Produto:

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

Para efetuar uma leitura de um ponto de um item, chame um dos seguintes métodos:

Ler um item de forma assíncrona

O ponto de exemplo seguinte lê um único item de forma assíncrona e devolve um item desserializado com o tipo genérico fornecido:

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

O Database.ReadItemAsync<> método lê um item e devolve um objeto do tipo ItemResponse<>. O tipo ItemResponse<> herda do Response<> tipo, que contém um operador de conversão implícita para converter o objeto no tipo genérico. Para saber mais sobre operadores implícitos, veja Operadores de conversão definidos pelo utilizador.

Em alternativa, pode devolver o tipo genérico ItemResponse<> e obter explicitamente o recurso. O tipo ItemResponse<> mais geral também contém metadados úteis sobre a operação de API subjacente. Neste exemplo, os metadados sobre o custo da unidade de pedido para esta operação são recolhidos com a propriedade 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;

Ler um item como um fluxo de forma assíncrona

Este exemplo lê um item como um fluxo de dados diretamente:

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

O Container.ReadItemStreamAsync método devolve o item como um Stream sem anular a serialização dos conteúdos.

Se não estiver a planear anular a serialização direta dos itens, a utilização das APIs de transmissão em fluxo pode melhorar o desempenho ao entregar o item como um fluxo diretamente para o componente seguinte da sua aplicação. Para obter mais sugestões sobre como otimizar o SDK para cenários de elevado desempenho, veja Sugestões de desempenho do SDK.

Ler vários itens de forma assíncrona

Neste exemplo, é utilizada uma lista de cadeias de identificação exclusivas e pares de chaves de partição para procurar e obter vários itens:

// 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<> devolve uma lista de itens com base nos identificadores exclusivos e nas chaves de partição que fornecer. Esta operação destina-se a realizar uma melhor latência do que uma consulta com IN instruções para obter um grande número de itens independentes.

Passos seguintes

Agora que leu vários itens, utilize o guia seguinte para consultar itens.

Consultar itens