Compatibilidad con Spring Data

En este artículo se describe cómo se puede usar Spring Cloud Azure y Spring Data juntos.

Compatibilidad con Spring Data Azure Cosmos DB

azure Cosmos DB es un servicio de base de datos distribuido globalmente que permite a los desarrolladores trabajar con datos mediante diversas API estándar, como SQL, MongoDB, Graph y Azure Table Storage.

Configuración de dependencias

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

Configuración

Nota

Si usa una entidad de seguridad para autenticar y autorizar con el identificador de Entra de Microsoft para acceder a un recurso de Azure, asegúrese de que a la entidad de seguridad se le ha concedido permiso suficiente para acceder al recurso de Azure. Para obtener más información, consulte Autorizar el acceso con el identificador de Entra de Microsoft.

En la tabla siguiente se enumeran las propiedades configurables de spring-cloud-azure-starter-data-cosmos:

Propiedad	Descripción
spring.cloud.azure.cosmos.enabled	Valor que indica si el servicio Azure Cosmos DB está habilitado. El valor predeterminado es true.
spring.cloud.azure.cosmos.database	Identificador de base de datos de Azure Cosmos DB.
spring.cloud.azure.cosmos.endpoint	URI para conectar Azure Cosmos DB.
spring.cloud.azure.cosmos.key	La PrivateKey para conectarse a Azure Cosmos DB.
spring.cloud.azure.cosmos.credential.client-certificate-password	Contraseña del archivo de certificado.
spring.cloud.azure.cosmos.credential.client-certificate-path	Ruta de acceso de un archivo de certificado PEM que se va a usar al realizar la autenticación de la entidad de servicio con Azure.
spring.cloud.azure.cosmos.credential.client-id	ID de cliente que se va a usar al realizar la autenticación de entidad de servicio con Azure.
spring.cloud.azure.cosmos.credential.client-secret	Secreto de cliente que se va a usar al realizar la autenticación de entidad de servicio con Azure.
spring.cloud.azure.cosmos.credential.managed-identity-enabled	Si se va a habilitar la identidad administrada. El valor predeterminado es false.
spring.cloud.azure.cosmos.credential.password	Contraseña que se va a usar al realizar la autenticación de nombre de usuario y contraseña con Azure.
spring.cloud.azure.cosmos.credential.username	Nombre de usuario que se va a usar al realizar la autenticación de nombre de usuario y contraseña con Azure.
spring.cloud.azure.cosmos.populate-query-metrics	Valor que indica si se deben rellenar las cadenas de diagnóstico y las métricas de consulta. El valor predeterminado es false.
spring.cloud.azure.cosmos.consistency-level	Un nivel de coherencia para Azure Cosmos DB.

Conceptos clave

En la lista siguiente se muestran los conceptos clave de la compatibilidad con Spring Data:

• Spring Data CrudRepository y ReactiveCrudRepository, que proporcionan la siguiente funcionalidad CRUD básica:

  • salvar
  • findAll
  • findOne por ID
  • eliminarTodo
  • eliminar por identificador
  • eliminar entidad

• Anotación de Spring Data @Id. Hay dos maneras de asignar un campo en una clase de dominio al id de un documento de Azure Cosmos DB:

  • Anotar un campo en la clase de dominio con @Id. Este campo se asignará al documento id en Azure Cosmos DB.
  • Establezca el nombre de este campo en id. Este campo se asignará al documento id en Azure Cosmos DB.

  Nota

  Si se aplican ambas formas, la anotación @Id tiene mayor prioridad.

• Nombres de colección personalizados. De forma predeterminada, el nombre de la colección será el nombre de clase de la clase de dominio de usuario. Para personalizarlo, añada la anotación @Document(collection="myCustomCollectionName") a la clase del dominio, eso es todo.

• Es compatible con la partición de Azure Cosmos DB. Para especificar un campo de la clase de dominio para que sea un campo de clave de partición, anote con @PartitionKey. Al realizar operaciones CRUD, especifique el valor de partición. Para obtener más ejemplos, consulte AddressRepositoryIT.java en GitHub.

• Admite la operación de búsqueda de consulta personalizada de Spring Data.

• Admite spring-boot-starter-data-rest.

• Admite listas y tipos anidados en las clases de dominio.

Uso básico

Uso de una clave privada para acceder a Azure Cosmos DB

La manera más sencilla de conectar Azure Cosmos DB con spring-cloud-azure-starter-data-cosmos es con una clave principal. Agregue las siguientes propiedades:

spring:
  cloud:
    azure:
      cosmos:
        key: ${AZURE_COSMOS_KEY}
        endpoint: ${AZURE_COSMOS_ENDPOINT}
        database: ${AZURE_COSMOS_DATABASE}

Definición de una entidad

Defina una entidad como documento en Azure Cosmos DB, como se muestra en el ejemplo siguiente:

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

El campo id se usará como el id del documento en Azure Cosmos DB. Como alternativa, puede anotar cualquier campo con @Id para asignarlo al documento id.

La anotación @Container(containerName = "mycollection") se usa para especificar el nombre de colección del documento en Azure Cosmos DB.

Creación de repositorios

Para crear repositorios, amplíe la interfaz ReactiveCosmosRepository, que proporciona compatibilidad con el repositorio spring Data.

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

Actualmente, la interfaz ReactiveCosmosRepository proporciona operaciones básicas de guardado, eliminación y búsqueda. Habrá más operaciones compatibles más adelante.

Creación de una clase de aplicación

En el ejemplo siguiente se crea una clase de aplicación con todos los componentes:

@SpringBootApplication
public class CosmosSampleApplication implements CommandLineRunner {

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

    @Autowired
    private UserRepository repository;

    @Autowired
    private CosmosProperties properties;

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

    public void run(String... var1) {
        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());

    }

    @PostConstruct
    public void setup() {
        // For this example, remove all of the existing records.
        this.repository.deleteAll().block();
    }
}

Este ejemplo incluye una interfaz UserRepository inyectada automáticamente para realizar operaciones de guardado, eliminación y búsqueda.

Muestras

Consulte el azure-spring-boot-samples en GitHub.

Además de usar la biblioteca spring-cloud-azure-starter-data-cosmos, puede usar directamente la biblioteca azure-spring-data-cosmos en escenarios más complejos. Para más información, consulte Spring Data for Azure Cosmos DB client library.