Acceso a datos con la API NoSQL de Azure Cosmos DB

  • Artículo

En este artículo se muestra cómo agregar Spring Cloud Azure Starter para Spring Data para Azure Cosmos DB a una aplicación personalizada. Este inicio le permite almacenar datos en la base de datos de Azure Cosmos DB y recuperarlos mediante Spring Data y Azure Cosmos DB para NoSQL. El artículo comienza mostrando cómo crear una instancia de Azure Cosmos DB a través de Azure Portal. A continuación, en el artículo se muestra cómo usar Spring Initializr para crear una aplicación personalizada de Spring Boot que puede usar con Spring Boot Starter.

Azure Cosmos DB es un servicio de base de datos de distribución global que permite a los desarrolladores trabajar con datos mediante diversas API estándar, como SQL, MongoDB, Graph y Table. Spring Boot Starter de Microsoft permite a los desarrolladores usar aplicaciones de Spring Boot que se integran fácilmente con Azure Cosmos DB para NoSQL.

Requisitos previos

Creación de una instancia de Azure Cosmos DB mediante Azure Portal

Siga estos pasos para crear una instancia de Azure Cosmos DB:

  1. Vaya a Azure Portal y seleccione Crear un recurso.

  2. Seleccione Bases de datos y, luego, elija Azure Cosmos DB.

  3. En la pantalla Crear una cuenta de Azure Cosmos DB, seleccione Azure Cosmos DB para NoSQL.

    Captura de pantalla de Azure Portal que muestra la página Crear una cuenta de Azure Cosmos DB con la opción Azure Cosmos DB para NoSQL resaltada.

  4. En la página Azure Cosmos DB, escriba la información siguiente:

    • Elija la suscripción que quiere usar para la base de datos.
    • Especifique si quiere crear un nuevo grupo de recursos para la base de datos o elija un grupo de recursos diferente.
    • Escriba un nombre de cuenta único, que se usa como URI para la base de datos. Por ejemplo: contosoaccounttest.
    • Especifique la ubicación de la base de datos.
    • Seleccione Aplicar descuento de nivel gratis si desea crear una cuenta solo con fines de demostración.
    • Deje el resto de las opciones y la configuración predeterminadas tal como está.

  5. Seleccione Revisar y crear, revise las especificaciones y seleccione Crear.

    Captura de pantalla de Azure Portal que muestra la página Crear cuenta de Azure Cosmos DB con la configuración de NoSQL de Azure Cosmos DB.

  6. Cuando se ha creado la base de datos, aparece en el panel de Azure y, en las páginas Todos los recursos y Azure Cosmos DB. Para crear una base de datos y un contenedor para una instancia de Azure Cosmos DB recién creada, consulte la sección Incorporación de una base de datos y un contenedor de Inicio rápido: Creación de una cuenta, una base de datos, un contenedor y elementos de Azure Cosmos DB desde Azure Portal. Puede seleccionar la base de datos en cualquiera de esas ubicaciones para abrir la página de propiedades de la memoria caché.

  7. Cuando se muestre la página de propiedades de la base de datos, seleccione Claves y copie el URI y las claves de acceso de la base de datos. Estos valores se usan en la aplicación Spring Boot.

    Captura de pantalla de Azure Portal que muestra la cuenta de Azure Cosmos DB con la página Claves que se muestra.

Importante

En la instancia de Azure Cosmos DB recién creada, asigne el Owner rol a la cuenta de Azure que está usando actualmente. Para más información, consulte Asignación de roles de Azure mediante Azure Portal.

Creación de una aplicación de Spring Boot con Spring Initializr

Use los pasos siguientes para crear un nuevo proyecto de aplicación de Spring Boot con el soporte técnico de Azure. Como alternativa, puede usar el ejemplo spring-cloud-azure-data-cosmos-sample en el repositorio azure-spring-boot-samples . Después, puede ir directamente a Compilación y prueba de la aplicación.

  1. Vaya a https://start.spring.io/.

  2. Especifique las opciones siguientes:

    • Genere un proyecto de Maven con Java.
    • Especifique la versión de Spring Boot en 2.7.11.
    • Especifique los nombres de Group (Grupo) y Artifact (Artefacto) de la aplicación.
    • Seleccione 17 para la versión de Java.
    • Agregue compatibilidad para Azure en las dependencias.

    Nota:

    Spring Initializr usa los nombres de Group (Grupo) y Artifact (Artefacto) para crear el nombre del paquete, por ejemplo: com.example.wingtiptoysdata.

    La versión de Spring Boot puede ser mayor que la versión admitida por Azure. Una vez generado automáticamente el proyecto, puede cambiar manualmente la versión de Spring Boot a la versión más alta compatible con Azure, que puede encontrar en Spring-Versions-Mapping.

  3. Cuando haya especificado las opciones enumeradas anteriormente, seleccione GENERAR.

  4. Cuando se le pida, descargue el proyecto en una ruta de acceso del equipo local y extraiga los archivos.

La aplicación simple de Spring Boot ya está lista para su edición.

Configuración de la aplicación de Spring Boot para usar Azure Spring Boot Starter

  1. Busque el archivo pom.xml en el directorio de la aplicación; por ejemplo:

    C:\SpringBoot\wingtiptoysdata\pom.xml

    O bien

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

  2. Abra el archivo pom.xml en un editor de texto y agregue lo siguiente al elemento <dependencies>:

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

    Nota:

    Para más información sobre cómo administrar las versiones de la biblioteca de Azure de Spring Cloud mediante una lista de materiales (BOM), consulte la sección Introducción de la guía para desarrolladores de Azure de Spring Cloud.

  3. Guarde y cierre el archivo pom.xml.

Configuración de la aplicación de Spring Boot para usar su base de datos de Azure Cosmos DB

  1. Busque el archivo application.properties en el directorio resources de su aplicación; por ejemplo:

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

    O bien

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

  2. Abra el archivo application.properties en un editor de texto y agréguele las siguientes líneas; a continuación, sustituya los valores de ejemplo por las propiedades adecuadas de su base de datos:

    # 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 y cierre el archivo application.properties.

Adición de ejemplo de código para implementar funcionalidad básica de base de datos

En esta sección, creará dos clases de Java para almacenar datos de usuario. A continuación, modifique la clase de aplicación principal para crear una instancia de la clase y guardarla en la User base de datos.

Definición de una clase base para almacenar datos de usuario

  1. Cree un nuevo archivo llamado User.java en el mismo directorio que el archivo de Java de la aplicación principal.

  2. Abra el archivo User.java en un editor de texto y agréguele las siguientes líneas para definir una clase de usuario genérica que almacene y recupere valores de la base de datos:

    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 y cierre el archivo User.java.

Definición de una interfaz del repositorio de datos

  1. Cree un nuevo archivo llamado UserRepository.java en el mismo directorio que el archivo de Java de la aplicación principal.

  2. Abra el archivo UserRepository.java en un editor de texto y agréguele las siguientes líneas para definir una interfaz de repositorio de usuario que extienda la interfaz de ReactiveCosmosRepository predeterminada:

    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);
}

    La interfaz ReactiveCosmosRepository reemplaza a la interfaz DocumentDbRepository de la versión anterior del iniciador. La nueva interfaz proporciona API sincrónicas y reactivas para las operaciones básicas de guardado, eliminación y búsqueda.

  3. Guarde y cierre el archivo UserRepository.java.

Modificación de la clase de aplicación principal

  1. Busque el archivo de Java de la aplicación principal en el directorio del paquete de la aplicación; por ejemplo:

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

    O bien

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

  2. Abra el archivo de Java de la aplicación principal en un editor de texto y agregue las siguientes líneas al archivo:

    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 y cierre el archivo de Java de la aplicación principal.

Compilación y prueba de la aplicación

  1. Abra un símbolo del sistema y vaya a la carpeta donde se encuentra el archivo pom.xml; por ejemplo:

    cd C:\SpringBoot\wingtiptoysdata

    O bien

    cd /users/example/home/wingtiptoysdata

  2. Use el siguiente comando para compilar y ejecutar la aplicación:

    ./mvnw clean

    Este comando ejecuta la aplicación automáticamente como parte de la fase de prueba. También puede usar:

    ./mvnw spring-boot:run

    Después de una salida de compilación y prueba, la ventana de la consola muestra un mensaje similar al ejemplo siguiente:

    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

    Estos mensajes de salida indican que los datos se guardaron correctamente en Azure Cosmos DB y, a continuación, se recuperaron de nuevo.

Limpieza de recursos

Si no va a seguir usando esta aplicación, asegúrese de eliminar el grupo de recursos que contiene Azure Cosmos DB que creó anteriormente. Puede eliminar el grupo de recursos de Azure Portal.

Pasos siguientes

Para más información acerca de Spring y Azure, vaya al centro de documentación de Azure.

Spring en Azure

Más recursos

Para más información sobre el uso de Azure Cosmos DB y Java, consulte los siguientes artículos:

Para obtener más información sobre el uso de aplicaciones de Spring Boot en Azure, consulte los siguientes artículos:

Para más información sobre el uso de Azure con Java, consulte Azure para desarrolladores de Java y Working with Azure DevOps and Java (Trabajo con Azure DevOps y Java).

Spring Framework es una solución de código abierto que ayuda a los desarrolladores de Java a crear aplicaciones de nivel empresarial. Uno de los proyectos más populares que se basa en esa plataforma es Spring Boot, que proporciona un enfoque simplificado para crear aplicaciones de Java independientes. Para ayudar a los desarrolladores a empezar con Spring Boot, hay varios paquetes de ejemplo de Spring Boot disponibles en https://github.com/spring-guides/. Además de elegir de la lista de proyectos básicos de Spring Boot, el Spring Initializr ayuda a los desarrolladores en los primeros pasos para crear aplicaciones de Spring Boot personalizadas.