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. Este starter permite armazenar e recuperar dados do seu 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 o Spring Initializr para criar um aplicativo personalizado do Spring Boot 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 Table APIs. 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 uma base de dados do Azure Cosmos DB com 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 selecione Criar um recurso.

  2. Selecione Bases de dados e, em seguida, Azure Cosmos DB.

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

    Captura de ecrã 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 Azure Cosmos DB, introduza as seguintes informações:

    • Selecione a Subscrição que pretende utilizar para a sua base de dados.
    • Especifique se pretende criar um novo Grupo de recursos para a sua base de dados ou escolher um grupo de recursos já existente.
    • Insira um Nome de Conta exclusivo, que você usa como URI para seu banco de dados. Por exemplo: contosoaccounttest.
    • Especifique a Localização da sua base de dados.
    • Selecione Aplicar desconto de nível gratuito se quiser criar uma conta apenas para fins de demonstração.
    • Deixe o restante das opções e configurações padrão como estão.

  5. Selecione Rever + criar, reveja as suas especificações e selecione Criar.

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

  6. Quando seu banco de dados tiver sido criado, ele será listado em seu 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 Guia 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 ecrã do portal do Azure que mostra a conta do Azure Cosmos DB com a página Chaves a aparecer.

Importante

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

Crie um aplicativo Spring Boot com o Spring Initializr

Siga os seguintes passos para criar um novo projeto da aplicação Spring Boot com suporte do Azure. Como alternativa, você pode usar o exemplo spring-cloud-azure-data-cosmos-sample no repositório azure-spring-boot-samples . Em seguida, pode avançar diretamente para Criar e testar a sua aplicação.

  1. Navegue para https://start.spring.io/.

  2. Especifique as seguintes opções:

    • Gere um projeto do Maven com Java.
    • Especifique sua versão do Spring Boot para 2.7.11.
    • Especifique os nomes do Grupo e do Artefacto da aplicação.
    • Selecione 17 para a versão Java.
    • Adicione o Suporte do Azure nas dependências.

    Nota

    O Spring Initializr usa os nomes Group e Artifact 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 suportada pelo Suporte do Azure. Depois que o projeto é gerado automaticamente, você pode alterar manualmente a versão do Spring Boot para a versão mais alta suportada pelo Azure, que você pode encontrar em Spring-Versions-Mapping.

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

  4. Quando lhe for pedido, transfira o projeto para um caminho no seu computador local e extraia os ficheiros.

A sua aplicação Spring Boot simples está agora pronta para a edição.

Configurar a sua aplicação Spring Boot para que esta utilize o Azure Spring Boot Starter

  1. Localize o ficheiro pom.xml no diretório da sua aplicação. Por exemplo:

    C:\SpringBoot\wingtiptoysdata\pom.xml

    -or-

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

  2. Abra o ficheiro pom.xml num 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 lista de materiais (BOM), consulte a seção Introdução do guia do desenvolvedor do Spring Cloud Azure.

  3. Guarde e feche o ficheiro pom.xml.

Configurar a sua aplicação Spring Boot para que esta utilize o Azure Cosmos DB

  1. Localize o ficheiro application.properties no diretório resources (recursos) da sua aplicação. Por exemplo:

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

    -or-

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

  2. Abra o ficheiro application.properties num editor de texto, adicione as seguintes linhas ao ficheiro e substitua os exemplos de valores pelas propriedades adequadas à sua base de dados:

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

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

  3. Guarde e feche o ficheiro application.properties.

Adicionar código de exemplo para implementar funcionalidades básicas de base de dados

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

Definir uma classe base para armazenar dados de utilizadores

  1. Crie um novo ficheiro chamado User.java no mesmo diretório do ficheiro Java da aplicação principal.

  2. Abra o ficheiro User.java num editor de texto e adicione as seguintes linhas ao ficheiro para definir uma classe de utilizador geral que armazena e obtém valores na sua base 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. Guarde e feche o ficheiro User.java.

Definir uma interface repositório de dados

  1. Crie um novo ficheiro chamado UserRepository.java no mesmo diretório do ficheiro Java da aplicação principal.

  2. Abra o ficheiro UserRepository.java num editor de texto e adicione as seguintes linhas ao ficheiro para definir uma interface de repositório de utilizador que expanda a interface ReactiveCosmosRepository predefinida:

    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 iniciador. A interface nova fornece APIs síncronos e reativos para operações básicas de guardar, eliminar e localizar.

  3. Guarde e feche o ficheiro UserRepository.java.

Modificar a classe da aplicação principal

  1. Localize o ficheiro Java da aplicação principal no diretório de pacotes da sua aplicação. Por exemplo:

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

    -or-

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

  2. Abra o ficheiro Java da aplicação principal num editor de texto e adicione as seguintes linhas ao ficheiro:

    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. Guarde e feche o ficheiro Java da aplicação principal.

Criar e testar a sua aplicação

  1. Abra uma linha de comandos e navegue para a pasta onde se encontra o seu ficheiro pom.xml. Por exemplo:

    cd C:\SpringBoot\wingtiptoysdata

    -or-

    cd /users/example/home/wingtiptoysdata

  2. Utilize o seguinte comando para criar e executar a sua aplicação:

    ./mvnw clean

    Este comando executa automaticamente a aplicação como parte da fase de teste. Também pode utilizar:

    ./mvnw spring-boot:run

    Após algumas saídas de compilação e teste, a janela do console exibe uma mensagem semelhante ao exemplo a seguir:

    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, em seguida, recuperados novamente.

Clean up resources (Limpar recursos)

Se você não vai continuar a usar este aplicativo, certifique-se de excluir 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óximos passos

Para saber mais sobre o Spring e o Azure, avance para o centro de documentação relativa ao Spring no Azure.

Spring no Azure

Mais recursos

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

Para obter mais informações sobre como utilizar as aplicações Spring Boot no Azure, veja os artigos seguintes:

Para obter mais informações sobre a utilização do Azure com Java, veja Azure para Programadores de Java e Working with Azure DevOps and Java (Trabalhar com o Azure DevOps e Java).

O Spring Framework é uma solução open source que ajuda os programadores de Java a criar aplicações de nível empresarial. Um dos projetos mais populares criado com base nessa plataforma é o Spring Boot, que fornece uma abordagem simplificada para a criação de aplicações Java autónomas. Para ajudar os programadores a começarem a utilizar o Spring Boot, encontram-se vários exemplos de pacotes do Spring Boot disponíveis em https://github.com/spring-guides/. Além de escolher a partir da lista de projetos básicos do Spring Boot, o Spring Initializr ajuda os programadores a começarem a criar aplicações Spring Boot personalizadas.