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

Artigo
08/15/2024

APLICA-SE A: NoSQL

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

Leitura de itens com identificadores exclusivos

Cada item no Azure Cosmos DB para NoSQL tem um identificador exclusivo especificado pela id propriedade. No escopo de um contêiner, dois itens não podem compartilhar 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 executar uma leitura rápida desse item. Se apenas o identificador exclusivo estiver disponível, você terá que executar uma consulta menos eficiente para procurar o item em várias partições lógicas. Para saber mais sobre leituras e consultas pontuais, consulte Otimizar o custo da solicitação para leitura de dados.

Ler um item

Nota

Os exemplos neste artigo pressupõem que você já definiu um tipo C# para representar seus dados chamado Product:

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

Para executar uma leitura pontual de um item, chame um dos seguintes métodos:

ReadItemAsync<>
ReadItemStreamAsync<>
ReadManyItemsAsync<>

Ler um item de forma assíncrona

O ponto de exemplo a seguir lê um único item de forma assíncrona e retorna um item desserializado usando 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 retorna um objeto do tipo ItemResponse<>. O tipo ItemResponse<> herda do Response<> tipo, que contém um operador de conversão implícito para converter o objeto no tipo genérico. Para saber mais sobre operadores implícitos, consulte Operadores de conversão definidos pelo usuário.

Como alternativa, você pode retornar 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 a taxa de unidade de solicitação para esta operação são coletados usando 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 retorna o item como um Stream sem desserializar o conteúdo.

Se você não estiver planejando desserializar os itens diretamente, usar as APIs de fluxo pode melhorar o desempenho entregando o item como um fluxo diretamente para o próximo componente do seu aplicativo. Para obter mais dicas sobre como otimizar o SDK para cenários de alto desempenho, consulte Dicas de desempenho do SDK.

Ler vários itens de forma assíncrona

Neste exemplo, uma lista de tuplas contendo identificador exclusivo e pares de chaves de partição é usada para pesquisar e recuperar 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<> Retorna uma lista de itens com base nos identificadores exclusivos e chaves de partição fornecidos. Esta operação destina-se a executar melhor latência do que uma consulta com IN instruções para buscar um grande número de itens independentes.

Próximos passos

Agora que você leu vários itens, use o próximo guia para consultar itens.

Itens de consulta

Partilhar via