Guia de desenvolvimento do Azure Cosmos DB

O Azure Spring Data para Azure Cosmos DB oferece suporte ao Spring Data para o Azure Cosmos DB for NoSQL. Azure Cosmos DB é um serviço de banco de dados distribuído globalmente que os desenvolvedores podem usar para trabalhar com dados usando várias APIs padrão, como SQL, MongoDB, Cassandra, Graph e Table.

Este guia explica os conceitos, as funcionalidades com suporte, a solução de problemas e os problemas conhecidos do SDK do Azure Spring Data para Azure Cosmos DB. Para obter mais informações sobre esses conceitos e exemplos de código, consulte o README do Spring Data for Azure Cosmos DB SDK.

Política de suporte à versão

Suporte à versão do Spring Boot

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

Suporte à versão do Spring Data

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

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

A biblioteca Spring Data Azure Cosmos DB do Azure oferece suporte a várias versões do Spring Boot e do Spring Cloud. Para obter mais informações sobre qual versão do Azure Spring Data Azure Cosmos DB usar com o Spring Boot e o 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 dependência a seguir.

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

Pré-requisitos

• do JDK (Java Development Kit), versão 8 ou superior.
• Uma conta ativa do Azure. Se você não tiver um, poderá se inscrever em uma conta gratuita . Como alternativa, você pode usar o do Emulador do Azure Cosmos DB para desenvolvimento e teste. Como o emulador usa um certificado HTTPS autoassinado, você precisa importar seu certificado para o Java repositório de certificados confiável, 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

Você só precisará do SLF4J se planeja usar o registro em log. Baixe também uma associação SLF4J, que vincula a API SLF4J à implementação de log de sua escolha. Para mais informações, consulte o manual do usuário SLF4J .

Configurar e personalizar a classe de configuração

Para configurar a classe de configuração, estenda AbstractCosmosConfiguration. Para obter mais informações, consulte a classe de configuração de instalação .

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

Configuração de entidade

Você pode definir uma entidade simples como um item no Azure Cosmos DB. Defina 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 do contêiner permite especificar o nome do contêiner, unidades de solicitação (RUs), tempo de vida, criação de contêineres com taxa de transferência com dimensionamento automático, suporte à chave de partição aninhada e outras propriedades do contêiner.

Configuração do repositório

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

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

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

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

Anotações do Spring Data

Anotação de @Id do Spring Data

Você pode mapear um campo em uma classe de domínio para id de várias maneiras. Para obter mais informações, consulte a seção de código de anotação de ID do Spring Data.

Geração automática de ID

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

Expressão SpEL e nome do contêiner personalizado

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

Política de Indexação Personalizada

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

Política de chaves exclusiva

O Azure Spring Data Azure Cosmos DB permite definir UniqueKeyPolicy no contêiner adicionando a anotação @CosmosUniqueKeyPolicy à classe de domínio. Para obter mais informações, consulte a seção política de chaves 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 como o campo de chave de partição, anote-o com @PartitionKey.

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

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

Bloqueio Otimista

Azure-spring-data-cosmos dá suporte ao bloqueio otimista para contêineres específicos. Esse suporte significa que upserts e exclusões por item falharão com uma exceção se outro processo modificar o item. 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 dá suporte a consultas personalizadas do Spring Data, como uma operação de localização como findByAFieldAndBField. Ele também dá suporte a Spring Data Pageable, Slice e Sort. Para obter mais informações, consulte a seção de consultas, paginação e classificação.

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

Azure-spring-data-cosmos dá suporte ao uso do Azure Cosmos DB Java SDK. Você pode obter um bean CosmosClient ou CosmosAsyncClient por meio de ApplicationContext e executar qualquer operação suportada pelo SDK do Azure Cosmos DB para Java. Para obter mais informações, consulte o usando o Cliente do Azure Cosmos por meio da seção Spring Data Cosmos.

Spring Data REST

Azure-spring-data-cosmos dá suporte ao REST do Spring Data. Para obter mais informações, consulte a seção API REST do Azure Spring Data Azure Cosmos DB.

Auditoria

Azure-spring-data-cosmos oferece suporte a campos de auditoria em entidades do banco de dados usando anotações padrão do Spring Data. 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 dá suporte à configuração de vários bancos de dados, incluindo várias contas de banco de dados e uma única conta com vários bancos de dados. Para obter um snippet de código completo, consulte a seção de configuração de vários bancos de dados.

Solução de Problemas

Geral

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

Para sugerir um novo recurso ou alterações, registre 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 registro em log que dá suporte ao registro em log em estruturas de registros em log populares como o log4j e logback. Para obter mais informações, consulte a seção habilitar o registro em 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 banco de dados múltiplo.

Conta única com vários bancos de dados

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

Próximas etapas

• Leia mais sobre o Azure Spring Data e o Azure Cosmos DB.
• Leia mais sobre Azure Cosmos DB Service.
• Consulte os exemplos do Azure Spring Data Azure Cosmos DB.
• Consulte o Spring MVC com Azure Cosmos DB Sample.

Participante

Este projeto recebe 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, e realmente concede a nós, os direitos de usar sua contribuição.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a 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 que estejam usando nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, consulte as perguntas frequentes sobre o Código de Conduta ou entre em contato com opencode@microsoft.com com quaisquer outras perguntas ou comentários.