Os aplicativos ASP.NET CRUD consistem em criar, ler, atualizar e excluir. Em Parte 1Em seguida, configuramos um projeto básico do ASP.NET Core. Em Parte 2adicionamos o primeiro ler usando uma consulta SQL++ em relação aos dados da lista de desejos.
O SQL++ do Couchbase é uma linguagem de consulta avançada, que contém todos os melhores recursos do SQL relacional, com um superconjunto de recursos para consulta de dados JSON.
No entanto, o SQL++ não é a única maneira de interagir com os dados no Couchbase. Nesta postagem, exploraremos o uso da API de valor-chave.
Valor-chave versus SQL?
Se você tem um histórico relacional, provavelmente está acostumado com o SQL sendo o único maneira de interagir com os dados (mesmo que você esteja usando uma ferramenta como o Entity Framework Core, ele ainda está usando SQL). Um dos excelentes recursos de um banco de dados NoSQL (como o Couchbase) é que, embora o SQL esteja disponível, também há outros métodos de acesso disponíveis. (Por isso, o backrônimo "Not Only SQL").
Para o Couchbase, a maneira mais eficiente de acessar os dados é por meio de pesquisa de valor-chave. Todos os outros índices e consultas suportados pelo Couchbase (SQL++, Pesquisa de texto completo, Análises, Eventose outros) são, em última análise, construídos ou dependem da simples pesquisa de valores-chave.
A API de valor-chave lhe proporcionará o melhor desempenho, onde:
-
- Uma chave é especificada, ou
- Seu código recebe uma chave, ou
- Você pode construir uma chave de forma determinística
Exemplos: quando usar chave-valor
Aqui estão alguns exemplos de quando (e quando NÃO) usar a API de valor-chave para leitura:
| Caso de uso | Chave-valor? | Por que ou por que não? |
| Pesquisar um usuário com a chave "73892“ | Sim | Pesquisa direta |
| Pesquisar apenas o endereço de e-mail de um usuário com a chave "73892“ | Sim | Mesmo que o documento do usuário seja grande, o Couchbase tem um recurso baseado em chave API de subdocumentoque permite que você recupere uma parte do documento. |
| Pesquisar um grupo de usuários com as chaves "73892“, “47212", e “90491” | Sim | Isso pode exigir várias operações de pesquisa de chave, mas ainda assim pode ser mais rápido do que usar um SQL SELECT ... WHERE ... IN consulta. |
| Pesquisar os comentários de uma postagem de blog | Talvez | Se os comentários de um post de blog estiverem em um único documento e a chave do post de blog for conhecida, uma chave de comentário de post de blog poderá ser criada. Por exemplo, a chave do post do blog é Eu gosto de balõesPara obter comentários, use a tecla I-like-balloons::comments |
| Pesquisar todos os usuários de "Ohio“ | Não | O estado do usuário é provavelmente um atributo "secundário", não uma chave (vários usuários podem ser de Ohio). Esse é um bom caso de uso para o SQL++ |
| Pesquisar produtos com "balões" em sua descrição | Não | As descrições são um atributo secundário, não uma chave (vários produtos podem ter "balões" em sua descrição). Esse é um bom caso de uso para a Pesquisa de texto completo (FTS) |
Observe que o Couchbase tem uma arquitetura que prioriza a memória. O cache interno significa que uma pesquisa de valor-chave geralmente recupera dados diretamente da memória - latência de microssegundos, sem espera no disco.
Minha regra geral é: use a API de valor-chave sempre que possível e, quando necessário, recorra a uma opção mais flexível, como SQL++ ou Full-Text Search.
Criar um ponto de extremidade Get CRUD
Vamos criar um ponto de extremidade que use a API de valor-chave para recuperar um único item da lista de desejos.
Esse ponto de extremidade exigirá que a ID do item da lista de desejos seja fornecida como parâmetro:
|
1 2 3 4 5 6 7 8 9 10 11 |
[HttpGet] [Route("api/get/{id}")] public async Task<IActionResult> Get(Guid id) { var bucket = await _bucketProvider.GetBucketAsync("demo"); var collection = await bucket.CollectionAsync("wishlist"); var item = await collection.GetAsync(id.ToString()); return Ok(item.ContentAs<WishlistItem>()); } |
Neste exemplo, não precisamos de um agrupamento (como fizemos com o SQL++), mas precisamos de um objeto coleção objeto. Observe que, como a coleção de listas de desejos está no objeto Padrão escopo, podemos pular a obtenção do escopo e ir diretamente do balde para a coleção.
Quando o item é devolvido da GetAsync, está em um IGetResult objeto. O Couchbase não armazena objetos C#, ele armazena JSON. Portanto, para serializar em um objeto Item da lista de desejos objeto, use item.ContentAs.
Essa API lhe dá flexibilidade: um documento retornado do Couchbase pode ser serializado para Item da lista de desejos aqui e talvez AmazonWishlistItem em outra parte do aplicativo.
Chave-valor em ação
Execute o aplicativo ASP.NET Core e vamos dar uma olhada na página OpenAPI/Swagger atualizada.
O ponto de extremidade /api/get/{id} sob Presentes deve estar listado. Expanda esse endpoint clicando nele. Ao contrário do /api/getall esse ponto de extremidade requer um parâmetro: o ID do item da lista de desejos que você deseja obter.
Se você não se lembrar de um dos GUIDs, poderá executar /api/getall primeiro e copie um deles, ou use: "31c9cc33-8dfe-440c-bd1b-bb038939d2e0" (que foi a identificação que dei à camisa do Joey Votto). Clique aqui Experimente, cole essa ID e clique em Executar:
Observe que, na resposta, a ID retornada é nulo. Isso se deve ao fato de que, como expliquei em Parte 2O Couchbase armazena o ID como metadados. Nessa situação, isso não é um grande problema. O ID foi fornecido como parâmetro, portanto, você poderia simplesmente atribuí-lo ao objeto C# que está sendo retornado:
|
1 2 3 4 |
var itemObj = item.ContentAs<WishlistItem>(); itemObj.Id = Guid.Parse(id); return Ok(itemObj); |
Como alternativa, se você não quiser retornar a ID você pode criar uma classe de visualização C# separada que tenha apenas nome e usá-lo com ContentAs.
E quanto à validação e ao tratamento de erros?
Que sensato de sua parte perguntar! Esse endpoint definitivamente não está pronto para a produção. O que está faltando?
-
- Tratamento de erros: e se houver uma exceção?
- Validação: e se a ID informada for inválida?
- Autenticação/autorização: e se o consumidor dessa API não tiver acesso de leitura?
- Registro: e se algo não der muito certo e quisermos examinar o resultado mais tarde?
Todas essas são preocupações importantes. Para a maioria delas, o ASP.NET Core tem funcionalidade integrada e/ou bibliotecas populares de terceiros disponíveis para ajudar você. Mas não deixe de conferir a documentação do Couchbase em Manipulação de erros com o .NET SDK e Visão geral do gerenciamento de segurança.
O que vem a seguir?
O projeto ASP.NET Core está conectado ao Couchbase Capella e está lendo dados por meio do SQL++ e da API de valor-chave.
Na próxima postagem do blog, veremos como criar e atualizar dados ("C" e "U").
Nesse meio tempo, você deve:
-
- Inscreva-se para um teste gratuito do Capella
- Confira o Couchbase Playground para .NET exemplos que você pode executar diretamente no navegador.
