Exercício – Ler e consultar itens

  • 9 minutos

Lembre-se de que seu aplicativo deve adicionar itens a um contêiner do Azure Cosmos DB for NoSQL e ler esses mesmos itens de volta como validação. Neste ponto, seu aplicativo adiciona itens com êxito ao contêiner. Há duas maneiras principais de ler um item: executando uma leitura de ponto ou executando uma consulta.

Há três requisitos principais no momento:

  1. Executar uma leitura de ponto de um item usando o identificador exclusivo e o valor da chave de partição
  2. Criar uma consulta usando uma cadeia de caracteres de consulta simples
  3. Paginar os resultados da consulta usando um iterador de feed

Illustration of icons indicating data being queried using a query.

Depois de concluir este exercício, seu aplicativo estará quase pronto. Você terá consultas que podem ler os itens de categoria e produto que você criou anteriormente.

Ponto de leitura de um item

A maneira mais simples de recuperar um item no Azure Cosmos DB é executar uma leitura de ponto. As leituras de ponto usam um número pequeno e previsível de RUs em comparação com consultas. Aqui, você faz a leitura de ponto do item de categoria única capacetes que você criou.

  1. Retorne ao arquivo Program.cs.

  2. Crie uma instância PartitionKey para gear-climb-helmets.

    PartitionKey readKey = new("gear-climb-helmets");

  3. Use Container.ReadItemAsync para fazer a leitura de ponto de um item específico usando a propriedade id e o valor de chave de partição.

    ItemResponse<Category> readResponse = await container.ReadItemAsync<Category>(
    id: "91f79374-8611-4505-9c28-3bbbf1aa7df7",
    partitionKey: readKey
);

  4. Obtenha seu tipo genérico serializado usando a propriedade Resource da classe ItemResponse.

    Category readItem = readResponse.Resource;

  5. Gere o identificador exclusivo e a cobrança de solicitação para a operação de leitura de ponto.

    Console.WriteLine($"[Point read item]:\t{readItem.Id}\t(RUs: {readResponse.RequestCharge})");

  6. Salve o arquivo Program.cs.

Executar uma consulta

Em situações em que você precisa de vários itens, você pode usar uma consulta para localizar e recuperar esses itens. Lembre-se de que usamos a propriedade de chave de partição categoryId para agrupar nossos itens em categorias específicas. Se incluirmos essa propriedade em uma consulta, criaremos efetivamente uma consulta com escopo para uma única partição lógica. Agora, você usa uma consulta para localizar todos os itens na categoria tendas.

  1. Em Program.cs, crie uma cadeia de caracteres para a consulta SELECT * FROM products p WHERE p.categoryId = 'gear-camp-tents'. No entanto, use um parâmetro chamado @partitionKey para o filtro categoryId.

    string statement = "SELECT * FROM products p WHERE p.categoryId = @partitionKey";

  2. Crie uma instância da classe QueryDefinition com sua cadeia de caracteres de consulta.

    var query = new QueryDefinition(
    query: statement
);

  3. Use o método WithParameter fluente para atribuir o valor gear-camp-tents ao parâmetro @partitionKey.

    var parameterizedQuery = query.WithParameter("@partitionKey", "gear-camp-tents");

  4. Use Container.GetItemQueryIterator<> para recuperar um iterador para sua consulta específica.

    using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: parameterizedQuery
);

  5. Escreva a consulta no console.

    Console.WriteLine($"[Start query]:\t{statement}");

  6. Salve o arquivo Program.cs.

Paginar os resultados da consulta

O Azure Cosmos DB divide automaticamente os resultados da consulta em páginas que podem ser recuperadas de maneira assíncrona. Para gerenciar essas páginas, escreva seu código C# de uma forma específica para garantir que você recupere todas as páginas de resultados disponíveis. Aqui, você usará um loop while e foreach em C# para iterar nas páginas de resultados.

  1. Em Program.cs, crie uma variável dupla denominada totalRequestCharge definida como um valor de 0.

    double totalRequestCharge = 0d;

  2. Crie um loop while que itera até que a propriedade FeedIterator.HasMoreResults do iterador de feed seja falsa.

    while (feed.HasMoreResults)
{
}

  3. Dentro do loop while, obtenha uma nova página de resultados usando o método FeedIterator.ReadNextAsync.

    FeedResponse<Product> page = await feed.ReadNextAsync();

  4. Ainda no loop while, incremente o preço de solicitação total usando o valor de FeedResponse.RequestCharge.

    totalRequestCharge += page.RequestCharge;

  5. Ainda dentro do loop while, crie um loop foreach para iterar sobre os itens reais na página.

    foreach (Product item in page)
{
}

  6. Dentro do loop foreach, escreva no console as propriedades ID e name do item retornado.

    Console.WriteLine($"[Returned item]:\t{item.Id}\t(Name: {item.Name ?? "N/A"})");

  7. Fora do loop while, escreva no console a taxa total de solicitação calculada.

    Console.WriteLine($"[Query metrics]:\t(RUs: {totalRequestCharge})");

    Dica

    Se você não tiver certeza sobre qual código deve estar dentro ou fora dos loops while e foreach, vá para a seção de código de revisão em Verificar seu trabalho.

  8. Salve o arquivo Program.cs.

Verificar seu trabalho

Seu aplicativo agora lê e consulta itens do contêiner. Aqui, você executa o aplicativo para que possa observar os resultados de ambas as operações.

  1. Execute o aplicativo .NET no terminal:

    dotnet run

  2. Observe a saída da execução do aplicativo. A saída deve corresponder ao exemplo aqui:

    ...
[Point read item]:      91f79374-8611-4505-9c28-3bbbf1aa7df7    (RUs: 1)
[Start query]:          SELECT * FROM products p WHERE p.categoryId = @partitionKey
[Returned item]:        5df21ec5-813c-423e-9ee9-1a2aaead0be4    (Name: N/A)
[Returned item]:        e8dddee4-9f43-4d15-9b08-0d7f36adcac8    (Name: Cirroa Tent)
[Returned item]:        e6f87b8d-8cd7-4ade-a005-14d3e2fbd1aa    (Name: Kuloar Tent)
[Returned item]:        f7653468-c4b8-47c9-97ff-451ee55f4fd5    (Name: Mammatin Tent)
[Returned item]:        6e3b7275-57d4-4418-914d-14d1baca0979    (Name: Nimbolo Tent)
[Query metrics]:        (RUs: 2.94)

    Dica

    As RUs mostradas nesta saída de exemplo podem variar de acordo com a saída.

    Você notou que seu item de categoria foi desserializado com êxito no tipo que você usa para produtos? Como o item de categoria não tinha uma propriedade name, essa propriedade foi mantida no valor padrão. Verificação de tipos, gerenciamento de esquema e serialização/desserialização são tudo o que seu aplicativo pode gerenciar totalmente do lado do cliente.