Guia de desenvolvimento do Azure Cosmos DB

  • Artigo

O Azure Spring Data para Azure Cosmos DB fornece suporte a Spring Data para o Azure Cosmos DB para NoSQL. O Azure Cosmos DB é um serviço de banco de dados distribuído globalmente que permite que os desenvolvedores trabalhem com dados usando várias APIs padrão, como SQL, MongoDB, Cassandra, Gráfico e Tabela.

Este guia orientará você pelos conceitos do SDK do Azure Spring Data Azure Cosmos DB, recursos com suporte, solução de problemas e problemas conhecidos. Para obter mais informações sobre os conceitos e exemplos de código abaixo, consulte o Leiame do SDK do Spring Data for Azure Cosmos DB.

Política de suporte de versão

Suporte à versão do Spring Boot

Este projeto suporta várias versões do Spring Boot. Para obter mais informações, consulte Política de suporte de inicialização do Spring. Os usuários do Maven podem herdar do projeto spring-boot-starter-parent para obter uma seção de gerenciamento de dependência para permitir que o Spring gerencie as versões para as dependências. Para obter mais informações, consulte Suporte à versão de inicialização do Spring.

Suporte à versão do Spring Data

Este projeto dá suporte a diferentes versões spring-data-commons. Para obter mais informações, consulte Suporte à versão de dados do Spring.

Qual versão do Azure Spring Data Azure Cosmos DB usar

A biblioteca do Azure Spring Data Cosmos Azure Cosmos DB dá suporte a várias versões do Spring Boot/Spring Cloud. Para obter mais informações sobre qual versão do Azure Spring Data Azure Cosmos DB usar com a versão Spring Boot / Spring Cloud, consulte Qual versão do Azure Spring Data para Azure Cosmos DB devo usar?.

Introdução

Incluir o pacote

Se você estiver usando o Maven, adicione a seguinte dependência.

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

Pré-requisitos

  • Java Development Kit (JDK), versão 8 ou superior.
  • Uma conta ativa do Azure. Se não tiver uma, você poderá se inscrever em uma conta gratuita. Como alternativa, você pode usar o Emulador do Azure Cosmos DB para desenvolvimento e teste. Como o certificado https do emulador é autoassinado, você precisa importar o certificado dele para o repositório de certificados confiáveis do java, explicado aqui
  • (Opcional) SLF4J é uma fachada de registro em log.
  • (Opcional) A associação SLF4J é usada para associar uma estrutura de registro em log específica ao SLF4J.
  • (Opcional) Maven

O SLF4J só será necessário se você planejar usar o registro em log. Baixe também uma associação SLF4J que vinculará a API SLF4J à implementação do registro em log de sua escolha. Para obter mais informações, confira o Manual do usuário do SLF4J.

Configurar e personalizar a classe de configuração

Para configurar a classe de configuração, você precisa estender AbstractCosmosConfigurationo . Para obter mais informações, consulte Classe de configuração de instalação.

Você pode personalizar o subjacente CosmosAsyncClient usado pelo SDK do Azure Spring Data Azure Cosmos DB fornecendo DirectConnectionConfig ou GatewayConnectionConfig ambos e fornecê-los ao CosmosClientBuilder. Para obter um exemplo completo, visite a seção de configuração de personalização.

Configuração da entidade

Você pode definir uma entidade simples como item no Azure Cosmos DB. Você pode definir entidades adicionando a @Container anotação e especificando propriedades relacionadas ao contêiner. Para obter mais informações, consulte Definir uma entidade.

A anotação de contêiner oferece suporte à especificação do nome do contêiner, unidades de solicitação (RUs), tempo de vida, criação de contêineres com taxa de transferência de escala automática, suporte a chave de partição aninhada e outras propriedades de contêiner.

Configuração do repositório

Azure Spring Data O Azure Cosmos DB oferece suporte ReactiveCrudRepository (APIs assíncronas) e CrudRepository (APIs de sincronização), que fornecem a seguinte funcionalidade CRUD básica:

  • Salvar
  • findAll
  • findOne por ID
  • deleteAll
  • excluir por ID
  • excluir entidade

Você pode estender CosmosRepository (para suporte à API de sincronização) ou ReactiveCosmosRepository (para suporte à API assíncrona) para configurar repositórios de dados do Spring para seu aplicativo. Para obter mais informações, consulte Criar repositórios.

Azure Spring Data O Azure Cosmos DB dá suporte à especificação de consultas anotadas nos repositórios usando @Queryo . Para obter mais informações, consulte QueryAnnotation: Usando consultas anotadas em repositórios.

Anotações do Spring Data

Anotação do Spring Data @Id

Há várias maneiras de mapear um campo na classe de domínio para id. Para obter mais informações, consulte a seção de código de anotação de ID de dados do spring.

Geração automática de ID

Azure Spring Data O Azure Cosmos DB dá suporte à geração automática de IDs usando a @GeneratedValue anotação. Para obter mais informações, consulte a seção Geração automática de ID.

Expressão SpEL e nome do contêiner personalizado

Por padrão, o nome do contêiner será o nome da classe de domínio do usuário. Para personalizar, adicione a @Container(containerName="myCustomContainerName") anotação à classe de domínio. Para obter mais informações, consulte a seção Expressão SpEL e nome do contêiner personalizado.

Política de indexação personalizada

Por padrão, IndexingPolicy será definido pelo serviço do Azure. Para personalizar, adicione a anotação @CosmosIndexingPolicy à classe de domínio. Para obter mais informações, consulte a seção Política de indexação.

Política de chave única

Azure Spring Data O Azure Cosmos DB dá suporte à configuração UniqueKeyPolicy no contêiner adicionando a anotação @CosmosUniqueKeyPolicy à classe de domínio. Para obter mais informações, consulte a seção de política de chave exclusiva.

Partição do Azure Cosmos DB

Azure-spring-data-cosmos dá suporte a partições do Azure Cosmos DB.

Para especificar um campo da classe de domínio para ser um campo de chave de partição, basta anotá-lo com @PartitionKey.

Ao executar a operação CRUD, especifique o valor da partição.

Para obter mais informações, consulte a seção de teste aqui.

Bloqueio Otimista

Azure-spring-data-cosmos suporta Bloqueio Otimista para contêineres específicos, o que significa que upserts/exclusões por item falharão com uma exceção caso o item seja modificado por outro processo nesse meio tempo. Para obter mais informações, consulte a seção de bloqueio otimista.

Consulta personalizada do Spring Data, paginável e classificação

Azure-spring-data-cosmos oferece suporte a consultas personalizadas do Spring Data, por exemplo, uma operação de localização como findByAFieldAndBField. Ele também suporta Spring Data Pageable, Slice e Sort. Para obter mais informações, consulte a seção de consulta, paginável e classificação.

Usando o SDK Java do Azure Cosmos DB por meio do Spring Data Cosmos

Azure-spring-data-cosmos suporta o uso do Azure Cosmos DB Java SDK. Os usuários podem obter CosmosClient ou CosmosAsyncClient utilizar ApplicationContext e executar quaisquer operações suportadas pelo SDK Java do Azure Cosmos DB. Para obter mais informações, consulte a seção Usando o Azure Cosmos Client por meio do Spring Data Cosmos.

Dados de mola REST

Azure-spring-data-cosmossuporta Spring Data REST. Para obter mais informações, consulte a seção Azure Spring Data Azure Cosmos DB REST API.

Auditoria

Azure-spring-data-cosmos Oferece suporte a campos de auditoria em entidades de banco de dados usando anotações padrão de dados Spring. Para obter mais informações, consulte a seção de auditoria do Spring Data Azure Cosmos DB.

Configuração de vários bancos de dados

Azure-spring-data-cosmos suporta configuração de vários bancos de dados, incluindo "várias contas de banco de dados" e "conta única, com vários bancos de dados". Para obter um trecho de código completo, consulte a seção Configuração de vários bancos de dados.

Solução de problemas

Geral

Se você encontrar algum bug, registre um problema aqui.

Para sugerir um novo recurso ou alterações possíveis, envie um problema da mesma maneira que faria para um bug.

Habilitar o Registro em log do Cliente

Azure-spring-data-cosmos usa SLF4j como a fachada de log que oferece suporte ao registro em estruturas de log populares, como log4j e logback. Para obter mais informações, consulte a seção habilitar log do cliente.

Exemplos

Para obter um projeto de exemplo completo, consulte o projeto de exemplo.

Contas de vários bancos de dados

Para obter um projeto de exemplo completo, consulte o projeto de exemplo de vários bancos de dados.

Conta única com vários bancos de dados

Para obter um projeto de exemplo completo, consulte o projeto de exemplo Conta única com vários bancos de dados.

Próximas etapas

Participante

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder e de fato concede, os direitos de usar sua contribuição.

Quando você envia uma solicitação pull, um bot CLA determina automaticamente se você precisa fornecer um CLA e decorar o PR adequadamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios usando nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para saber mais, confira as Perguntas frequentes sobre o Código de Conduta ou contate o opencode@microsoft.com caso tenha outras dúvidas ou comentários.

Impressions