Compartilhar via

Acessar dados com a API NoSQL do Azure Cosmos DB

  • Artigo

Este artigo mostra como adicionar o Spring Cloud Azure Starter for Spring Data for Azure Cosmos DB a um aplicativo personalizado. Esse início permite que você armazene dados e recupere dados do banco de dados do Azure Cosmos DB usando o Spring Data e o Azure Cosmos DB para NoSQL. O artigo começa mostrando como criar um Azure Cosmos DB por meio do portal do Azure. Em seguida, o artigo mostra como usar Spring Initializr para criar um aplicativo Spring Boot personalizado que você pode usar com o Spring Boot Starter.

O Azure Cosmos DB é um serviço de banco de dados distribuído globalmente que permite que os desenvolvedores trabalhem com dados usando várias APIs padrão, como SQL, MongoDB, Graph e APIs de Tabela. O Spring Boot Starter da Microsoft permite que os desenvolvedores usem aplicativos Spring Boot que se integram facilmente ao Azure Cosmos DB para NoSQL.

Pré-requisitos

Criar um Azure Cosmos DB usando o portal do Azure

Use as seguintes etapas para criar uma instância do Azure Cosmos DB:

  1. Navegue até o portal do Azure e clique em Criar um recurso .

  2. Selecione Bancos de Dadose, em seguida, selecione Azure Cosmos DB.

  3. Na tela Criar uma conta do Azure Cosmos DB, selecione Azure Cosmos DB para NoSQL.

    Captura de tela do portal do Azure que mostra a página Criar uma conta do Azure Cosmos DB com a opção Azure Cosmos DB para NoSQL realçada.

  4. Na página do Azure Cosmos DB, insira as seguintes informações:

    • Escolha a assinatura que você deseja usar para seu banco de dados.
    • Especifique se deseja criar um novo grupo de recursos para seu banco de dados ou escolher um grupo de recursos existente.
    • Insira um Nome de Conta exclusivo, que você usará como o URI para o seu banco de dados. Por exemplo: contosoaccounttest.
    • Especifique o Local para seu banco de dados.
    • Selecione Aplicar desconto de camada gratuita caso você queira criar uma conta somente para fins de demonstração.
    • Deixe o restante das opções e configurações padrão como está.

  5. Selecione Revisão + criar, examine suas especificações e selecione Criar.

    Captura de tela do portal do Azure que mostra a página Criar Conta do Azure Cosmos DB com as configurações do Azure Cosmos DB para NoSQL.

  6. Quando o banco de dados for criado, ele será listado no painel do Azure e nas páginas Todos os Recursos e Azure Cosmos DB. Para criar um banco de dados e um contêiner para um Azure Cosmos DB recém-criado, consulte a seção Adicionar um banco de dados e um contêiner de Início Rápido: Criar uma conta, banco de dados, contêiner e itens do Azure Cosmos DB no portal do Azure. Você pode selecionar seu banco de dados para qualquer um desses locais para abrir a página de propriedades do cache.

  7. Quando a página de propriedades do banco de dados for exibida, selecione Chaves e copie o URI e as chaves de acesso do banco de dados. Você usa esses valores em seu aplicativo Spring Boot.

    Captura de tela do portal do Azure que mostra a conta do Azure Cosmos DB com a página Chaves sendo exibida.

Importante

No Azure Cosmos DB recém-criado, atribua a função Owner à conta do Azure que você está usando no momento. Para mais informações, veja Atribuir funções do Azure usando o portal do Azure.

Criar um aplicativo Spring Boot com o Spring Initializr

Use as etapas a seguir para criar um novo projeto de aplicativo spring boot com suporte do Azure. Como alternativa, é possível usar a amostra spring-cloud-azure-data-cosmos-sample no repositório azure-spring-boot-samples. Em seguida, você pode pular diretamente para Criar e testar seu aplicativo.

  1. Navegue até https://start.spring.io/.

  2. Especifique as seguintes opções:

    • Gere um projeto Maven com Java.
    • Especifique sua versão do Spring Boot como 2.7.11.
    • Especifique os nomes de Grupo e Artefato do aplicativo.
    • Selecione 17 para a versão java.
    • Adicione o Suporte do Azure nas dependências.

    Nota

    O Spring Initializr usa os nomes de Grupo e Artefato para criar o nome do pacote; por exemplo: com.example.wingtiptoysdata.

    A versão do Spring Boot pode ser maior do que a versão compatível com o Suporte do Azure. Depois que o projeto é gerado automaticamente, você pode alterar manualmente a versão do Spring Boot para a versão mais recente suportada pelo Azure, que você pode encontrar em Spring-Versions-Mapping.

  3. Quando você tiver especificado as opções listadas anteriormente, selecione GERAR.

  4. Quando solicitado, baixe o projeto para um caminho no computador local e extraia os arquivos.

Seu aplicativo Spring Boot simples agora está pronto para edição.

Configurar seu aplicativo Spring Boot para usar o Azure Spring Boot Starter

  1. Localize o arquivo pom.xml no diretório do aplicativo; por exemplo:

    C:\SpringBoot\wingtiptoysdata\pom.xml

    -ou-

    /users/example/home/wingtiptoysdata/pom.xml

  2. Abra o arquivo pom.xml em um editor de texto e adicione o seguinte ao elemento <dependencies>:

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

    Nota

    Para obter mais informações sobre como gerenciar versões da biblioteca do Spring Cloud Azure usando uma fatura de materiais (BOM), consulte a seção Introdução do guia do desenvolvedor do Spring Cloud Azure.

  3. Salve e feche o arquivo de pom.xml.

Configurar seu aplicativo Spring Boot para usar o Azure Cosmos DB

  1. Localize o arquivo application.properties no diretório resources do seu aplicativo; por exemplo:

    C:\SpringBoot\wingtiptoysdata\src\main\resources\application.properties

    -ou-

    /users/example/home/wingtiptoysdata/src/main/resources/application.properties

  2. Abra o arquivo application.properties em um editor de texto e adicione as seguintes linhas ao arquivo e substitua os valores de exemplo pelas propriedades apropriadas para o banco de dados:

    # Specify the DNS URI of your Azure Cosmos DB.
spring.cloud.azure.cosmos.endpoint=https://contosoaccounttest.documents.azure.com:443/
spring.cloud.azure.cosmos.key=your-cosmosdb-account-key

# Specify the name of your database.
spring.cloud.azure.cosmos.database=contosoaccounttest
spring.cloud.azure.cosmos.populate-query-metrics=true

  3. Salve e feche o arquivo application.properties.

Adicionar código de exemplo para implementar a funcionalidade básica do banco de dados

Nesta seção, você criará duas classes Java para armazenar dados do usuário. Em seguida, modifique sua classe de aplicativo principal para criar uma instância da classe User e salvá-la em seu banco de dados.

Definir uma classe base para armazenar dados do usuário

  1. Crie um novo arquivo chamado User.java no mesmo diretório que o arquivo Java do aplicativo principal.

  2. Abra o arquivo User.java em um editor de texto e adicione as seguintes linhas ao arquivo para definir uma classe de usuário genérica que armazena e recupera valores em seu banco de dados:

    package com.example.wingtiptoysdata;

import com.azure.spring.data.cosmos.core.mapping.Container;
import com.azure.spring.data.cosmos.core.mapping.PartitionKey;
import org.springframework.data.annotation.Id;

@Container(containerName = "mycollection")
public class User {
    @Id
    private String id;
    private String firstName;
    @PartitionKey
    private String lastName;
    private String address;

    public User() {

    }

    public User(String id, String firstName, String lastName, String address) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.address = address;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    @Override
    public String toString() {
        return String.format("%s %s, %s", firstName, lastName, address);
    }
}

  3. Salve e feche o arquivo de User.java.

Definir uma interface do repositório de dados

  1. Crie um novo arquivo chamado UserRepository.java no mesmo diretório que o arquivo Java do aplicativo principal.

  2. Abra o arquivo UserRepository.java em um editor de texto e adicione as seguintes linhas ao arquivo para definir uma interface do repositório de usuário que estenda a interface de ReactiveCosmosRepository padrão:

    package com.example.wingtiptoysdata;

import com.azure.spring.data.cosmos.repository.ReactiveCosmosRepository;
import org.springframework.stereotype.Repository;
import reactor.core.publisher.Flux;

@Repository
public interface UserRepository extends ReactiveCosmosRepository<User, String> {
    Flux<User> findByFirstName(String firstName);
}

    A interface ReactiveCosmosRepository substitui a interface DocumentDbRepository da versão anterior do starter. A nova interface fornece APIs síncronas e reativas para operações básicas de salvamento, exclusão e localização.

  3. Salve e feche o arquivo UserRepository.java.

Modificar a classe de aplicativo principal

  1. Localize o arquivo Java do aplicativo principal no diretório do pacote do aplicativo, por exemplo:

    C:\SpringBoot\wingtiptoysdata\src\main\java\com\example\wingtiptoysdata\WingtiptoysdataApplication.java

    -ou-

    /users/example/home/wingtiptoysdata/src/main/java/com/example/wingtiptoysdata/WingtiptoysdataApplication.java

  2. Abra o arquivo Java do aplicativo principal em um editor de texto e adicione as seguintes linhas ao arquivo:

    package com.example.wingtiptoysdata;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.util.Assert;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.Optional;

@SpringBootApplication
public class WingtiptoysdataApplication implements CommandLineRunner {

    private static final Logger LOGGER = LoggerFactory.getLogger(WingtiptoysdataApplication.class);

    @Autowired
    private UserRepository repository;

    public static void main(String[] args) {
        SpringApplication.run(WingtiptoysdataApplication.class, args);
    }

    public void run(String... var1) {
        this.repository.deleteAll().block();
        LOGGER.info("Deleted all data in container.");

        final User testUser = new User("testId", "testFirstName", "testLastName", "test address line one");

        // Save the User class to Azure Cosmos DB database.
        final Mono<User> saveUserMono = repository.save(testUser);

        final Flux<User> firstNameUserFlux = repository.findByFirstName("testFirstName");

        //  Nothing happens until we subscribe to these Monos.
        //  findById won't return the user as user isn't present.
        final Mono<User> findByIdMono = repository.findById(testUser.getId());
        final User findByIdUser = findByIdMono.block();
        Assert.isNull(findByIdUser, "User must be null");

        final User savedUser = saveUserMono.block();
        Assert.state(savedUser != null, "Saved user must not be null");
        Assert.state(savedUser.getFirstName().equals(testUser.getFirstName()), "Saved user first name doesn't match");

        firstNameUserFlux.collectList().block();

        final Optional<User> optionalUserResult = repository.findById(testUser.getId()).blockOptional();
        Assert.isTrue(optionalUserResult.isPresent(), "Cannot find user.");

        final User result = optionalUserResult.get();
        Assert.state(result.getFirstName().equals(testUser.getFirstName()), "query result firstName doesn't match!");
        Assert.state(result.getLastName().equals(testUser.getLastName()), "query result lastName doesn't match!");

        LOGGER.info("findOne in User collection get result: {}", result.toString());
    }
}

  3. Salve e feche o arquivo Java do aplicativo principal.

Compilar e testar seu aplicativo

  1. Abra um prompt de comando e navegue até a pasta em que o arquivo pom.xml está localizado; por exemplo:

    cd C:\SpringBoot\wingtiptoysdata

    -ou-

    cd /users/example/home/wingtiptoysdata

  2. Use o seguinte comando para compilar e executar seu aplicativo:

    ./mvnw clean

    Esse comando executa o aplicativo automaticamente como parte da fase de teste. Você também pode usar:

    ./mvnw spring-boot:run

    Após alguma saída de build e teste, a janela do console exibirá uma mensagem semelhante ao seguinte exemplo:

    INFO 1365 --- [           main] c.e.w.WingtiptoysdataApplication         : Deleted all data in container.

... (omitting connection and diagnostics output) ...

INFO 1365 --- [           main] c.e.w.WingtiptoysdataApplication         : findOne in User collection get result: testFirstName testLastName, test address line one

    Essas mensagens de saída indicam que os dados foram salvos com êxito no Azure Cosmos DB e recuperados novamente.

Limpar recursos

Se você não quiser continuar a usar esse aplicativo, exclua o grupo de recursos que contém o Azure Cosmos DB criado anteriormente. Você pode excluir o grupo de recursos do portal do Azure.

Próximas etapas

Para saber mais sobre o Spring e o Azure, prossiga para o centro de documentação do Spring on Azure.

Spring no Azure

Mais recursos

Para obter mais informações sobre como usar o Azure Cosmos DB e Java, consulte os seguintes artigos:

Para obter mais informações sobre como usar aplicativos Spring Boot no Azure, consulte os seguintes artigos:

Para obter mais informações sobre como usar o Azure com Java, consulte o Azure para Desenvolvedores Java e Trabalhando com Azure DevOps e Java.

O Spring Framework é uma solução de software livre que ajuda os desenvolvedores Java a criar aplicativos de nível empresarial. Um dos projetos mais populares criados com base nessa plataforma é spring boot, que fornece uma abordagem simplificada para a criação de aplicativos Java autônomos. Para ajudar os desenvolvedores a começar a usar o Spring Boot, vários pacotes spring boot de exemplo estão disponíveis em https://github.com/spring-guides/. Além de escolher na lista de projetos básicos do Spring Boot, o Spring Initializr ajuda os desenvolvedores a começar a criar aplicativos Spring Boot personalizados.