Guia de início rápido: usar o Azure Cosmos DB para NoSQL com o SDK do Azure para Java

Neste início rápido, você implanta 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 os aplicativos armazenem dados de tabela estruturada na nuvem. Você aprende a criar tabelas, linhas e executar tarefas básicas em seu 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

  • Azure Developer CLI
  • Área de trabalho do Docker
  • Java 21

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

Inicializar o projeto

Use a CLI do Desenvolvedor do Azure (azd) para criar uma conta do Azure Cosmos DB for Table e implantar um aplicativo de exemplo em contêiner. O aplicativo de exemplo usa a biblioteca de cliente 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 CLI do Desenvolvedor do Azure usando azd auth logino . Siga as etapas especificadas pela ferramenta para autenticar na CLI usando suas credenciais preferidas do Azure.

    azd auth login
    
  3. Use 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 upo . Os modelos Bicep também implantam um aplicativo Web de exemplo.

    azd up
    
  6. Durante o processo de provisionamento, selecione sua assinatura, o local desejado e o grupo de recursos de destino. Aguarde a conclusão do processo de provisionamento. 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 o 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 cliente

A biblioteca do cliente está disponível através do Maven, como o azure-spring-data-cosmos pacote.

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

  2. Se ainda não existir, adicione uma entrada para o azure-spring-data-cosmos pacote.

    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-spring-data-cosmos</artifactId>
    </dependency>
    
  3. Além disso, adicione outra dependência para o azure-identity pacote, se ele ainda não existir.

    <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 para NoSQL.
CosmosRepository Essa classe é a classe de cliente principal e é usada para gerenciar dados dentro de um contêiner.
CosmosClientBuilder Esta classe é uma fábrica usada para criar um cliente usado pelo repositório.
Query Este tipo é um decorador de método usado para especificar a consulta que o repositório executa.

Exemplos de código

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

Autenticar o cliente

Primeiro, este exemplo cria uma nova classe que herda para configurar a conexão com AbstractCosmosConfiguration o Azure Cosmos DB para NoSQL.

@Configuration
@EnableCosmosRepositories
public class CosmosConfiguration extends AbstractCosmosConfiguration {
}

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

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

Obter uma base de dados

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

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

Obter um contentor

Use o decorador de Container método para configurar uma classe para representar itens em um contêiner. Crie a classe para incluir todos os membros que você 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.saveo .

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

Execute uma operação de leitura pontual usando os campos identificador exclusivo (id) e chave de partição. Use repository.findById para recuperar eficientemente 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 sobre vários itens em um contêiner definindo uma consulta na interface do repositório. Este exemplo usa o decorador de Query método 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);

}

Obtenha todos os resultados da consulta usando repository.getItemsByCategory. Percorra os resultados da consulta.

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

Clean up resources (Limpar recursos)

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

azd down