Guía de desarrollo de Azure Cosmos DB

Azure Spring Data para Azure Cosmos DB proporciona soporte de Spring Data para Azure Cosmos DB for NoSQL. Azure Cosmos DB es un servicio de base de datos distribuido globalmente que los desarrolladores pueden usar para trabajar con datos mediante diversas API estándar, como SQL, MongoDB, Cassandra, Graph y Table.

En esta guía se explican los conceptos de Azure SDK de Spring Data Azure Cosmos DB, características admitidas, solución de problemas y problemas conocidos. Para obtener más información sobre estos conceptos y ejemplos de código, consulte el archivo README del SDK de Spring Data for Azure Cosmos DB.

Directiva de soporte de versiones

Compatibilidad con versiones de Spring Boot

Este proyecto admite varias versiones de Spring Boot. Para obtener más información, consulte Directiva de compatibilidad con Spring Boot. Los usuarios de Maven pueden heredar del spring-boot-starter-parent proyecto para obtener una sección de administración de dependencias que permita a Spring administrar las versiones de las dependencias. Para obtener más información, consulte Compatibilidad con versiones de Spring Boot.

Soporte de versiones de Spring Data

Este proyecto admite diferentes spring-data-commons versiones. Para obtener más información, consulte Compatibilidad con versiones de Spring Data.

Qué versión de Azure Spring Data Azure Cosmos DB usar

Azure biblioteca de Spring Data Azure Cosmos DB admite varias versiones de Spring Boot y Spring Cloud. Para obtener más información sobre qué versión de Azure Spring Data Azure Cosmos DB usar con Spring Boot y Spring Cloud, consulte ¿Qué versión de Azure Spring Data para Azure Cosmos DB debo usar?

Comenzar

Inclusión del paquete

Si usa Maven, agregue la siguiente dependencia.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-spring-data-cosmos</artifactId>
    <version>LATEST</version>
</dependency>

Prerrequisitos

  • Java Development Kit (JDK), versión 8 o posterior.
  • Una cuenta de Azure activa. Si no tiene una, puede registrarse para obtener una cuenta gratuita . Como alternativa, puede usar el emulador de Azure Cosmos DB para desarrollo y pruebas. Dado que el emulador usa un certificado HTTPS autofirmado, debe importar su certificado al almacén de certificados de confianza de Java, que se explica aquí.
  • (Opcional) SLF4J es una fachada de registro.
  • (Opcional) El enlace SLF4J se utiliza para asociar una plataforma de registro específica a SLF4J.
  • (Opcional) maven

Solo necesitas SLF4J si tienes pensado utilizar el registro de eventos. Descargue también un adaptador de SLF4J, que vincula la API de SLF4J con la implementación de registro que prefiera. Para obtener más información, consulte los manuales de instrucción de SLF4J.

Configuración y personalización de la clase de configuración

Para configurar la clase de configuración, extienda AbstractCosmosConfiguration. Para obtener más información, consulte Configuración de clase de configuración.

Puede personalizar el CosmosAsyncClient subyacente que utiliza el SDK de Azure Spring Data Azure Cosmos DB proporcionando DirectConnectionConfig, GatewayConnectionConfig o ambos, y pasándolos a CosmosClientBuilder. Para obtener un ejemplo completo, visite la sección de personalización de la configuración.

Configuración de entidades

Puede definir una entidad simple como un elemento en Azure Cosmos DB. Defina entidades agregando la @Container anotación y especificando las propiedades relacionadas con el contenedor. Para obtener más información, consulte Definir una entidad.

La anotación de contenedor permite especificar el nombre del contenedor, las unidades de solicitud (RU), el tiempo de vida, la creación de contenedores con rendimiento de escalado automático, la compatibilidad con claves de partición anidadas y otras propiedades del contenedor.

Configuración del repositorio

Azure Spring Data Azure Cosmos DB admite ReactiveCrudRepository (API asincrónicas) y CrudRepository (API de sincronización), que proporcionan la siguiente funcionalidad CRUD básica:

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

Puede ampliar CosmosRepository (para la compatibilidad con api de sincronización) o ReactiveCosmosRepository (para la compatibilidad con API asincrónica) para configurar repositorios de Spring Data para la aplicación. Para obtener más información, consulte Creación de repositorios.

Azure Spring Data Azure Cosmos DB admite la especificación de consultas anotadas en los repositorios mediante @Query. Para obtener más información, consulte QueryAnnotation: Uso de consultas anotadas en repositorios.

Anotaciones de Spring Data

Anotación @Id de Spring Data

Se puede asignar un campo de una clase de dominio a id de varias maneras. Para obtener más información, consulte la sección de código de anotación de ID de Spring Data.

Generación automática de identificadores

Azure Spring Data Azure Cosmos DB admite la generación automática de identificadores mediante la @GeneratedValue anotación . Para obtener más información, consulte la sección de generación automática de ID .

Expresión spEL y nombre de contenedor personalizado

De forma predeterminada, el nombre del contenedor es el nombre de clase de la clase de dominio de usuario. Para personalizar el nombre del contenedor, agregue la @Container(containerName="myCustomContainerName") anotación a la clase de dominio. Para obtener más información, consulte la sección Expresión SpEL y nombre de contenedor personalizado.

Política de Indexación Personalizada

De forma predeterminada, el servicio de Azure establece el IndexingPolicy. Para personalizar el IndexingPolicy, añada la anotación @CosmosIndexingPolicy a la clase de dominio. Para obtener más información, consulte la sección de la política de indexación .

Directiva de clave única

Azure Spring Data Azure Cosmos DB permite establecer UniqueKeyPolicy en el contenedor agregando la anotación @CosmosUniqueKeyPolicy a la clase de dominio. Para obtener más información, consulte la sección de directiva de clave única.

Partición de Azure Cosmos DB

Azure-spring-data-cosmos admite particiones de Azure Cosmos DB .

Para especificar un campo de la clase de dominio como campo de clave de partición, anote con @PartitionKey.

Al realizar una operación CRUD, especifique el valor de partición.

Para obtener más información, consulte la sección probar aquí.

Bloqueo optimista

Azure-spring-data-cosmos admite el bloqueo optimista para contenedores específicos. Esta compatibilidad implica que las operaciones de upsert y eliminación por elemento fallarán y generarán una excepción si otro proceso modifica el elemento. Para obtener más información, consulte la sección de bloqueo optimista.

Consulta personalizada de Spring Data, paginación y ordenamiento

Azure-spring-data-cosmos admite consultas personalizadas de Spring Data, como una operación de búsqueda como findByAFieldAndBField. También admite Spring Data Pageable, Slice y Sort. Para obtener más información, consulte la sección de consulta, paginación y ordenación.

Uso del SDK de Java de Azure Cosmos DB mediante Spring Data Cosmos

Azure-spring-data-cosmos admite el uso de Azure Cosmos DB Java SDK. Puede obtener un bean CosmosClient o CosmosAsyncClient a través de ApplicationContext y ejecutar cualquier operación compatible con el SDK de Java para Azure Cosmos DB. Para obtener más información, consulte la sección sobre el uso del cliente de Azure Cosmos con Spring Data Cosmos.

Spring Data REST

Azure-spring-data-cosmos es compatible con Spring Data REST. Para obtener más información, consulte la sección de la API REST de Azure Cosmos DB de Azure Spring Data.

Auditoría

Azure-spring-data-cosmos admite la auditoría de campos en entidades de base de datos mediante anotaciones de spring-data estándar. Para obtener más información, consulte la sección de auditoría de Spring Data Azure Cosmos DB .

Configuración de varias bases de datos

Azure-spring-data-cosmos admite la configuración de varias bases de datos, incluidas varias cuentas de base de datos y una sola cuenta con varias bases de datos. Para obtener un fragmento de código completo, consulte la sección configuración de varias bases de datos.

Solución de problemas

General

Si se produce un error, presente un problema aquí.

Para sugerir una nueva característica o cambios, abra un problema de la misma manera que lo haría para un error.

Habilitación del registro de cliente

Azure-spring-data-cosmos usa SLF4j como fachada de registro que admite el registro en frameworks de registro populares, como log4j y logback. Para obtener más información, consulte la sección de habilitación del registro de cliente.

Ejemplos

Para obtener un proyecto de ejemplo completo, consulte el proyecto de ejemplo de .

Cuentas de varias bases de datos

Para obtener un proyecto de ejemplo completo, consulte el proyecto de ejemplo de varias bases de datos.

Cuenta única con varias bases de datos

Para obtener un proyecto de ejemplo completo, consulte la cuenta única con varios proyectos de ejemplo de bases de datos.

Pasos siguientes

Contribución

Este proyecto da la bienvenida a las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente, por ejemplo, la etiqueta o el comentario. Solo tiene que seguir las instrucciones proporcionadas por el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante el CLA.

Este proyecto ha adoptado el Código de Conducta de Código Abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com para cualquier otra pregunta o comentario.

  • Last updated on