Guía de desarrollo de Azure Cosmos DB

  • Artículo

Azure Spring Data para Azure Cosmos DB proporciona compatibilidad con Spring Data para Azure Cosmos DB para NoSQL. 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, 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 más información sobre los conceptos y ejemplos de código siguientes, consulte el archivo Léame del SDK de Spring Data for Azure Cosmos DB.

Directiva de compatibilidad 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 soporte técnico de Spring Boot. Los usuarios de Maven pueden heredar del proyecto spring-boot-starter-parent para obtener una sección de administración de dependencias que permita a Spring administrar las versiones para las dependencias. Para obtener más información, consulte Compatibilidad con versiones de Spring Boot.

Compatibilidad con 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.

Versión de Azure Spring Data Azure Cosmos DB que se va a 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?.

Introducción

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>

Requisitos previos

  • Kit de desarrollo de Java (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 el desarrollo y las pruebas. Como el certificado https del emulador está autofirmado, debe importar su certificado al almacén de certificados de confianza de Java, tal como 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 tiene previsto usar el registro, también descargue un enlace SLF4J, que vinculará la API de SLF4J con la implementación de registro que prefiera. Para más información, consulte Manual de usuario de SLF4J.

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

Para configurar la clase de configuración, debe extender AbstractCosmosConfiguration. Para obtener más información, vea Setup Configuration Class( Clase de configuración).

Puede personalizar la base de datos subyacente CosmosAsyncClient que usa el SDK de Azure Cosmos DB de Azure Spring Data proporcionando DirectConnectionConfig o ambos GatewayConnectionConfig y proporcionándolos a CosmosClientBuilder. Para obtener un ejemplo completo, visite la sección 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 @Container anotación y especificando propiedades relacionadas con el contenedor. Para obtener más información, consulte Definición de una entidad.

La anotación de contenedor admite la especificación del nombre del contenedor, las unidades de solicitud (RU), el período de vida, la creación de contenedores con rendimiento de escalado automático, la compatibilidad con claves de partición anidadas y otras propiedades de 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
  • deleteAll
  • delete by ID
  • delete entity

Puede ampliar CosmosRepository (para la compatibilidad con la 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 : Using annotated queries in repositories (Uso de consultas anotadas en repositorios).

Anotaciones de Spring Data

Anotación de Spring Data @Id

Hay varias maneras de asignar un campo en la clase de dominio a id. Para obtener más información, consulte la sección código de anotación de id. de datos de spring.

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 Generación automática de identificadores.

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 personalizar, 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.

Custom IndexingPolicy

De forma predeterminada, IndexingPolicy el servicio de Azure lo establecerá. Para personalizar, agregue la anotación @CosmosIndexingPolicy a la clase de dominio. Para obtener más información, consulte la sección directiva de indexación.

Directiva de clave única

Azure Spring Data Azure Cosmos DB admite la configuración UniqueKeyPolicy en el contenedor agregando la anotación @CosmosUniqueKeyPolicy a la clase de dominio. Para obtener más información, consulte la sección 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.

Cuando realice una operación CRUD, especifique el valor de la partición.

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

Bloqueo optimista

Azure-spring-data-cosmos admite el bloqueo optimista para contenedores específicos, lo que significa que upserts/deletes by item producirá un error 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 bloqueo optimista.

Consulta personalizada, paginable y ordenación de Spring Data

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 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 o CosmosAsyncClient bean CosmosClient mediante ApplicationContext y ejecutar cualquier operación compatible con el SDK de Java de Azure Cosmos DB. Para más información, consulte la sección uso de Azure Cosmos Client a través de Spring Data Cosmos.

Spring Data REST

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

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 más información, consulte la sección 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, registre una incidencia de la misma manera que haría en el caso de un error.

Habilitación del registro de cliente

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

Ejemplos

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

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 el proyecto de ejemplo Cuenta única con varias bases de datos.

Pasos siguientes

Contribución

Agradecemos las contribuciones y las sugerencias para el proyecto. 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.

Al enviar una solicitud de incorporación de cambios, un bot cla determinará automáticamente si necesita proporcionar un CLA y decorar la solicitud de incorporación de cambios de forma adecuada (por ejemplo, etiqueta, comentario). Solo tiene que seguir las instrucciones que proporciona el bot. Solo tendrá que hacerlo una vez en todos los repositorios con nuestro CLA.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para más información, consulte las preguntas frecuentes del código de conducta o escriba un correo electrónico a opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impressions