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 permite a los desarrolladores trabajar con datos mediante varias API estándar, como SQL, MongoDB, Cassandra, Graph y Table.

Esta guía le guiará por los conceptos del SDK de Azure Spring Data de Azure Cosmos DB, las características admitidas, la solución de problemas y los problemas conocidos. Para obtener más información sobre los conceptos y ejemplos de código siguientes, consulte el archivo Léame del SDK de Spring Data para 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 proyecto de spring-boot-starter-parent para obtener una sección de administración de dependencias para permitir que Spring administre 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 versiones de spring-data-commons. Para obtener más información, consulte Compatibilidad con versiones de Spring Data.

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

La biblioteca de Azure Spring Data Azure Cosmos DB admite varias versiones de Spring Boot o Spring Cloud. Para más información sobre qué versión de Azure Spring Data Azure Cosmos DB se va a usar con Spring Boot o 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 certificado HTTPS del emulador está autofirmado, es necesario importar su certificado al almacén de certificados de confianza de Java, lo cual 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

SLF4J solo es necesario si planea usar el registro, también descargue un enlace SLF4J, que vinculará la API de SLF4J con la implementación de registro de su elección. 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, deberá ampliar AbstractCosmosConfiguration. Para obtener más información, consulte Configuración de clase de configuración.

Puede personalizar los componentes subyacentes CosmosAsyncClient utilizados por el SDK de Azure Cosmos DB de Azure Spring Data proporcionando DirectConnectionConfig, GatewayConnectionConfig, o ambos, y entregá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 elemento en Azure Cosmos DB. Puede definir entidades agregando la anotación @Container y especificando propiedades relacionadas con el contenedor. Para obtener más información, consulte Definir una entidad.

La anotación de contenedor admite la especificación del nombre del contenedor, unidades de solicitud (RU), período de vida, la creación de contenedores con escalabilidad automática de rendimiento, soporte para clave de partición anidada 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 by ID
• eliminarTodo
• delete by ID
• 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

Hay varias maneras de asignar un campo en la clase de dominio a id. 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 anotación @GeneratedValue. 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 será el nombre de clase de la clase de dominio de usuario. Para personalizarlo, agregue la anotación @Container(containerName="myCustomContainerName") 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 establecerá IndexingPolicy. Para personalizar, agregue 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 admite la configuración de 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 para que sea un campo de clave de partición, basta con anotarlo con @PartitionKey.

Al realizar la 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, lo que significa que las inserciones/actualizaciones/eliminaciones por elemento fallarán con una excepción en caso de que otro proceso modifique el elemento mientras tanto. 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, por ejemplo, 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, paginable 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. Los usuarios pueden obtener CosmosClient o CosmosAsyncClient bean a través de ApplicationContext y ejecutar cualquier operación compatible con el SDK de Java de 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 admite REST de Spring Data. 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 estándar de Spring Data. 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 "cuenta única, 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 encuentra algún error, presente un problema aquí.

Para sugerir una nueva característica o cambios que se podrían realizar, 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 un proyecto de ejemplo completo, consulte el ejemplo de proyecto de cuenta única con varias bases de datos.

Pasos siguientes

• Obtenga más información sobre Azure Spring Data y la Azure Cosmos DB.
• Más información sobre Azure Cosmos DB Service
• Consulte los ejemplos de Azure Spring Data para Azure Cosmos DB
• Consulte el ejemplo spring MVC con Azure Cosmos DB

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.