Compatibilidad con Spring Data

2025-06-22
Se aplica a: ✅ Version 4.20.0, ✅ Version 5.22.0

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.
.key spring.cloud.azure.cosmos	PrivateKey para conectar 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	Identificador 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.cosmosnivel de coherencia	Una de 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 identificador
- 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, agregue @Document(collection="myCustomCollectionName") de anotación a la clase de dominio, eso es todo.
Admite 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 consulta personalizada de Spring Data operación de búsqueda.
Admite spring-boot-starter-data-rest.
Admite tipos de lista y anidados en 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 id de 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. Más operaciones se admitirán 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();
    }
}

En este ejemplo se incluye una interfaz de UserRepository autowired para admitir operaciones de guardado, eliminación y búsqueda.

Muestras

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

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

Compartir a través de

Compatibilidad con Spring Data