Suporte Spring Data

Este artigo descreve como o Spring Cloud Azure e o Spring Data podem ser usados juntos.

Suporte do Spring Data Azure Cosmos DB

do 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, Graph e armazenamento de tabela do Azure.

Configuração de dependência

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-data-cosmos</artifactId>
</dependency>

Configuração

Observação

Se você usar uma entidade de segurança para autenticar e autorizar com a ID do Microsoft Entra para acessar um recurso do Azure, verifique se a entidade de segurança recebeu permissão suficiente para acessar o recurso do Azure. Para obter mais informações, consulte Autorizar acesso com o Microsoft Entra ID.

A tabela a seguir lista as propriedades configuráveis de spring-cloud-azure-starter-data-cosmos:

Propriedade	Descrição
spring.cloud.azure.cosmos.enabled	Um valor que indica se o Serviço Azure Cosmos DB está habilitado. O valor padrão é true.
spring.cloud.azure.cosmos.database	A ID do banco de dados do Azure Cosmos DB.
spring.cloud.azure.cosmos.endpoint	O URI para ligar ao Azure Cosmos DB.
spring.cloud.azure.cosmos.key	A chave privada para ligar ao Azure Cosmos DB.
spring.cloud.azure.cosmos.credential.client-certificate-password	A senha do arquivo de certificado.
spring.cloud.azure.cosmos.credential.client-certificate-path	O caminho de um arquivo de certificado PEM a ser usado ao executar a autenticação da entidade de serviço com o Azure.
spring.cloud.azure.cosmos.credential.client-id	A ID do cliente a ser usada ao executar a autenticação da entidade de serviço com o Azure.
spring.cloud.azure.cosmos.credential.client-secret	O segredo do cliente a ser usado ao executar a autenticação da entidade de serviço com o Azure.
spring.cloud.azure.cosmos.credential.managed-identity-enabled	Se a identidade gerenciada deve ser habilitada. O valor padrão é false.
spring.cloud.azure.cosmos.credential.password	A senha a ser usada ao executar a autenticação de nome de usuário/senha com o Azure.
spring.cloud.azure.cosmos.credential.username	O nome de usuário a ser usado ao executar a autenticação de nome de usuário/senha com o Azure.
spring.cloud.azure.cosmos.populate-query-metrics	Um valor que indica se as cadeias de caracteres de diagnóstico e as métricas de consulta devem ser preenchidas. O valor padrão é false.
spring.cloud.azure.cosmos.consistency-level	Um nível de consistência para o Azure Cosmos DB.

Conceitos-chave

A lista a seguir mostra os principais conceitos do suporte ao Spring Data:

• O Spring Data CrudRepository e ReactiveCrudRepository, que fornecem a seguinte funcionalidade CRUD básica:

  • Gravar
  • findAll
  • findOne por ID
  • excluirTodos
  • excluir por ID
  • excluir entidade

• A anotação @Id do Spring Data. Há duas maneiras de mapear um campo em uma classe de domínio para o id de um documento do Azure Cosmos DB:

  • Anotar um campo na classe de domínio com @Id. Este campo será mapeado para documentar id no Azure Cosmos DB.
  • Defina o nome deste campo como id. Este campo será mapeado para documentar id no Azure Cosmos DB.

  Observação

  Se ambas as formas forem aplicadas, a anotação @Id terá prioridade maior.

• Nomes de coleção personalizados. Por padrão, o nome da coleção será o nome da classe de domínio do usuário. Para o personalizar, adicione a anotação @Document(collection="myCustomCollectionName") à sua classe de domínio, e já está.

• Suporta partição do Azure Cosmos DB. Para especificar um campo da sua classe de domínio como um campo de chave de partição, anote-o com @PartitionKey. Quando você fizer operações CRUD, especifique o valor da partição. Para obter mais exemplos, consulte AddressRepositoryIT.java no GitHub.

• Suporta consulta personalizada do Spring Data operação de localização.

• Suporta spring-boot-starter-data-rest.

• Suporta Lista e tipos aninhados em classes de domínio.

Utilização básica

Usar uma chave privada para acessar o Azure Cosmos DB

A maneira mais simples de conectar o Azure Cosmos DB ao spring-cloud-azure-starter-data-cosmos é com uma chave primária. Adicione as seguintes propriedades:

spring:
  cloud:
    azure:
      cosmos:
        key: ${AZURE_COSMOS_KEY}
        endpoint: ${AZURE_COSMOS_ENDPOINT}
        database: ${AZURE_COSMOS_DATABASE}

Definir uma entidade

Defina uma entidade como um documento no Azure Cosmos DB, conforme mostrado no exemplo a seguir:

@Container(containerName = "mycollection")
public class User {
    @Id
    private String id;
    private String firstName;
    @PartitionKey
    private String lastName;
    private String address;

    public User() {
    }

    public User(String id, String firstName, String lastName, String address) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.address = address;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    @Override
    public String toString() {
        return String.format("%s %s, %s", firstName, lastName, address);
    }
}

O campo id será usado como o documento id no Azure Cosmos DB. Como alternativa, você pode anotar qualquer campo com @Id para mapeá-lo para o documento id.

O @Container(containerName = "mycollection") de anotação é usado para especificar o nome da coleção do seu documento no Azure Cosmos DB.

Criar repositórios

Para criar repositórios, estenda a interface ReactiveCosmosRepository, que fornece suporte ao repositório Spring Data.

@Repository
public interface UserRepository extends ReactiveCosmosRepository<User, String> {
    Flux<User> findByFirstName(String firstName);
}

Atualmente, a interface ReactiveCosmosRepository fornece operações básicas de salvamento, exclusão e localização. Mais operações serão apoiadas mais tarde.

Criar uma classe de aplicativo

O exemplo a seguir cria uma classe de aplicativo com todos os componentes:

@SpringBootApplication
public class CosmosSampleApplication implements CommandLineRunner {

private static final Logger LOGGER = LoggerFactory.getLogger(CosmosSampleApplication.class);

    @Autowired
    private UserRepository repository;

    @Autowired
    private CosmosProperties properties;

    public static void main(String[] args) {
        SpringApplication.run(CosmosSampleApplication.class, args);
    }

    public void run(String... var1) {
        final User testUser = new User("testId", "testFirstName",
                "testLastName", "test address line one");

        // Save the User class to Azure Cosmos DB database.
        final Mono<User> saveUserMono = repository.save(testUser);

        final Flux<User> firstNameUserFlux = repository.findByFirstName("testFirstName");

        //  Nothing happens until we subscribe to these Monos.
        //  findById won't return the user as user isn't present.
        final Mono<User> findByIdMono = repository.findById(testUser.getId());
        final User findByIdUser = findByIdMono.block();
        Assert.isNull(findByIdUser, "User must be null");

        final User savedUser = saveUserMono.block();
        Assert.state(savedUser != null, "Saved user must not be null");
        Assert.state(savedUser.getFirstName().equals(testUser.getFirstName()),
                "Saved user first name doesn't match");

        firstNameUserFlux.collectList().block();

        final Optional<User> optionalUserResult = repository.findById(testUser.getId()).blockOptional();
        Assert.isTrue(optionalUserResult.isPresent(), "Cannot find user.");

        final User result = optionalUserResult.get();
        Assert.state(result.getFirstName().equals(testUser.getFirstName()),
                "query result firstName doesn't match!");
        Assert.state(result.getLastName().equals(testUser.getLastName()),
                "query result lastName doesn't match!");
        LOGGER.info("findOne in User collection get result: {}", result.toString());

    }

    @PostConstruct
    public void setup() {
        // For this example, remove all of the existing records.
        this.repository.deleteAll().block();
    }
}

Este exemplo inclui uma interface UserRepository com fio automático para dar suporte a operações de salvamento, exclusão e localização.

Amostras

Ver o azure-spring-boot-samples no GitHub.

Além de usar a biblioteca spring-cloud-azure-starter-data-cosmos, você pode usar diretamente azure-spring-data-cosmos biblioteca para cenários mais complexos. Para obter mais informações, consulte Spring Data for Azure Cosmos DB client library.