Compartilhar via

Início Rápido: Usar o Azure Cosmos DB for NoSQL com o SDK do Azure para Java

  • Artigo
  • Aplica-se a:
    ✅ NoSQL

Neste início rápido, você implantará um aplicativo básico do Azure Cosmos DB for Table usando o SDK do Azure para Java. O Azure Cosmos DB for Table é um armazenamento de dados sem esquema que permite que aplicativos armazenem dados de tabela estruturados na nuvem. Você aprenderá a criar tabelas, linhas e executar tarefas básicas no recurso do Azure Cosmos DB usando o SDK do Azure para Java.

Documentação de referência da API | Código-fonte da biblioteca | Pacote (Maven) | Azure Developer CLI

Pré-requisitos

  • CLI do Desenvolvedor do Azure
  • Docker Desktop
  • Java 21

Se você ainda não tiver uma conta do Azure, crie uma conta gratuita antes de começar.

Inicializar o projeto

Use a Azure Developer CLI (azd) para criar uma conta do Azure Cosmos DB for Table e implantar um aplicativo de exemplo em contêineres. O aplicativo de exemplo usa a biblioteca de clientes para gerenciar, criar, ler e consultar dados de exemplo.

  1. Abra um terminal em um diretório vazio.

  2. Se você ainda não estiver autenticado, autentique-se na Azure Developer CLI usando azd auth login. Siga as etapas especificadas pela ferramenta para se autenticar na CLI usando suas credenciais preferenciais do Azure.

    azd auth login

  3. Execute azd init para inicializar o projeto.

    azd init --template cosmos-db-nosql-java-quickstart

  4. Durante a inicialização, configure um nome de ambiente exclusivo.

  5. Implante a conta do Azure Cosmos DB usando azd up. Os modelos do Bicep também implantam um aplicativo Web de exemplo.

    azd up

  6. Durante o processo de provisionamento, selecione a sua assinatura, o local desejado e o grupo de recursos de destino. Aguarde o processo de provisionamento ser concluído. O processo pode levar aproximadamente cinco minutos.

  7. Depois que o provisionamento dos recursos do Azure for concluído, uma URL para o aplicativo Web em execução será incluída na saída.

    Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

  8. Use a URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.

Captura de tela do aplicativo Web em execução.

Instalar a biblioteca de clientes

A biblioteca de clientes está disponível por meio do Maven, como o pacote azure-spring-data-cosmos.

  1. Navegue até a pasta /src/web e abra o arquivo pom.xml.

  2. Caso ela ainda não exista, adicione uma entrada ao pacote azure-spring-data-cosmos.

    <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-spring-data-cosmos</artifactId>
</dependency>

  3. Além disso, adicione outra dependência ao pacote azure-identity, caso ela ainda não exista.

    <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Modelo de objeto

Nome Descrição
EnableCosmosRepositories Esse tipo é um decorador de método usado para configurar um repositório para acessar o Azure Cosmos DB for NoSQL.
CosmosRepository Essa classe é a classe de cliente principal e é usada para gerenciar dados em um contêiner.
CosmosClientBuilder Essa classe é um alocador usado para criar um cliente usado pelo repositório.
Query Esse tipo é um decorador de método usado para especificar a consulta executada pelo repositório.

Exemplos de código

O código de exemplo do modelo usa um banco de dados chamado cosmicworks e um contêiner chamado products. O contêiner products traz detalhes como o nome, a categoria, a quantidade, um identificador exclusivo e um sinalizador de venda para cada produto. O contêiner usa a propriedade /category como uma chave de partição lógica.

Autenticar o cliente

Primeiro, essa amostra cria uma classe que herda de AbstractCosmosConfiguration para configurar a conexão com o Azure Cosmos DB for NoSQL.

@Configuration
@EnableCosmosRepositories
public class CosmosConfiguration extends AbstractCosmosConfiguration {
}

Dentro da classe de configuração, a amostra cria uma instância da classe CosmosClientBuilder e configura a autenticação usando uma instância de DefaultAzureCredential.

@Bean
public CosmosClientBuilder getCosmosClientBuilder() {
    DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
        .build();
        
    return new CosmosClientBuilder()
        .endpoint("<azure-cosmos-db-nosql-account-endpoint>")
        .credential(credential);
}

Obter um banco de dados

Na classe de configuração, a amostra implementa um método para retornar o nome do banco de dados existente chamado cosmicworks.

@Override
protected String getDatabaseName() {
    return "cosmicworks";
}

Obter um contêiner

Use o decorador de método Container para configurar uma classe, a fim de representar os itens de um contêiner. Crie a classe para incluir todos os membros que deseja serializar em JSON. Neste exemplo, o tipo tem um identificador exclusivo e campos para categoria, nome, quantidade, preço e liberação.

@Container(containerName = "products", autoCreateContainer = false)
public class Item {
    private String id;
    private String name;
    private Integer quantity;
    private Boolean sale;

    @PartitionKey
    private String category;

    // Extra members omitted for brevity
}

Criar um item

Crie um item no contêiner usando repository.save.

Item item = new Item(
    "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "gear-surf-surfboards",
    "Yamba Surfboard",
    12,
    false
);
Item created_item = repository.save(item);

Ler um item

Realize uma operação de leitura de ponto usando o identificador exclusivo (id) e os campos de chave de partição. Use repository.findById para recuperar com eficiência o item específico.

PartitionKey partitionKey = new PartitionKey("gear-surf-surfboards");
Optional<Item> existing_item = repository.findById("aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", partitionKey);
if (existing_item.isPresent()) {
    // Do something
}

Itens de consulta

Execute uma consulta em vários itens de um contêiner definindo uma consulta na interface do repositório. Esta amostra usa o decorador de método Query para definir um método que executa esta consulta parametrizada:

SELECT * FROM products p WHERE p.category = @category

@Repository
public interface ItemRepository extends CosmosRepository<Item, String> {

    @Query("SELECT * FROM products p WHERE p.category = @category")
    List<Item> getItemsByCategory(@Param("category") String category);

}

Busce todos os resultados da consulta usando repository.getItemsByCategory. Execute um loop pelos resultados da consulta.

List<Item> items = repository.getItemsByCategory("gear-surf-surfboards");
for (Item item : items) {
    // Do something
}

Limpar os recursos

Quando você não precisar mais dos recursos ou do aplicativo de exemplo, remova a implantação correspondente e todos os recursos.

azd down

Conteúdo relacionado