Ler um item no Azure Cosmos DB for NoSQL usando o .NET

  • Artigo

APLICA-SE A: NoSQL

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

Como ler itens com identificadores exclusivos

Cada item no Azure Cosmos DB for NoSQL tem um identificador exclusivo especificado pela propriedade id. No escopo de um contêiner, dois itens não podem compartilhar o mesmo identificador exclusivo. No entanto, o Azure Cosmos BD requer ambos, o identificador exclusivo e o valor da chave de partição de um item, para executar uma leitura pontual desse item. Se apenas o identificador exclusivo estiver disponível, você precisará executar uma consulta menos eficiente para pesquisar o item em várias partições lógicas. Para saber mais sobre leituras pontuais e consultas, confira Otimizar os custos da solicitação de leitura de dados.

Ler um item

Observação

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

// 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:

Ler um item de modo assíncrono

O seguinte exemplo efetuar a leitura pontual de um item de modo assíncrono 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 método Database.ReadItemAsync<> lê um item e retorna um objeto do tipo ItemResponse<>. O tipo ItemResponse<> herda do tipo Response<>, 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, confira 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 o custo da unidade de solicitação para essa 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 modo assíncrono

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 método Container.ReadItemStreamAsync 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 poderá melhorar o desempenho entregando o item como um fluxo diretamente para o próximo componente do aplicativo. Para obter mais dicas sobre como otimizar o SDK para cenários de alto desempenho, confira Dicas de desempenho para o SDK.

Ler vários itens de modo assíncrono

Neste exemplo, uma lista de tuplas que contêm pares de chave de partição e identificador exclusivos são usadas 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 nas chaves de partição que você fornece. Essa operação tem o objetivo de executar melhor latência do que uma consulta com instruções IN para buscar um grande número de itens independentes.

Próximas etapas

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

Itens de consulta