Guia de início rápido: biblioteca do Azure Cosmos DB para NoSQL para Java

Artigo
01/10/2024

APLICA-SE A: NoSQL

Comece a usar a biblioteca de cliente do Azure Cosmos DB para NoSQL para Java para consultar dados em seus contêineres e executar operações comuns em itens individuais. Siga estas etapas para implantar uma solução mínima em seu ambiente usando a CLI do Azure Developer.

Documentação | de referência da API Código fonte | da biblioteca Pacote (Maven) | Azure Developer CLI

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Conta do GitHub

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
CLI do desenvolvedor do Azure
Área de trabalho do Docker

Configuração

Implante o contêiner de desenvolvimento deste projeto em seu ambiente. Em seguida, use a CLI do Desenvolvedor do Azure (azd) para criar uma conta do Azure Cosmos DB para NoSQL e implantar um aplicativo de exemplo em contêiner. O aplicativo de exemplo usa a biblioteca de cliente para gerenciar, criar, ler e consultar dados de exemplo.

Importante

As contas do GitHub incluem um direito de armazenamento e horas essenciais sem nenhum custo. Para obter mais informações, consulte armazenamento incluído e horas principais para contas do GitHub.

Abra um terminal no diretório raiz do projeto.
Autentique-se na CLI do Desenvolvedor do Azure usando azd auth logino . Siga as etapas especificadas pela ferramenta para autenticar na CLI usando suas credenciais preferidas do Azure.
```
azd auth login
```
Use azd init para inicializar o projeto.
```
azd init
```
Durante a inicialização, configure um nome de ambiente exclusivo.

Gorjeta

O nome do ambiente também será usado como o nome do grupo de recursos de destino. Para este guia de início rápido, considere usar msdocs-cosmos-db-o .
Implante a conta do Azure Cosmos DB usando azd upo . Os modelos Bicep também implantam um aplicativo Web de exemplo.
```
azd up
```
Durante o processo de provisionamento, selecione sua assinatura e o local desejado. Aguarde a conclusão do processo de provisionamento. O processo pode levar aproximadamente cinco minutos.

Depois que o provisionamento dos recursos do Azure for concluído, uma URL para o aplicativo Web em execução será incluída na saída.

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

Use o URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.

Instalar a biblioteca de cliente

A biblioteca do cliente está disponível através do Maven, como o azure-spring-data-cosmos pacote.

Navegue até a /src/web pasta e abra o arquivo pom.xml .

Se ainda não existir, adicione uma entrada para o azure-spring-data-cosmos pacote.

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

Além disso, adicione outra dependência para o azure-identity pacote, se ele ainda não existir.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Modelo de objeto

Nome	Descrição
`EnableCosmosRepositories`	Esse tipo é um decorador de método usado para configurar um repositório para acessar o Azure Cosmos DB para NoSQL.
`CosmosRepository`	Essa classe é a classe de cliente principal e é usada para gerenciar dados dentro de um contêiner.
`CosmosClientBuilder`	Esta classe é uma fábrica usada para criar um cliente usado pelo repositório.
`Query`	Este tipo é um decorador de método usado para especificar a consulta que o repositório executa.

O código de exemplo no modelo usa um banco de dados chamado cosmicworks e um contêiner chamado products. O products recipiente contém detalhes como nome, categoria, quantidade, um identificador exclusivo e um sinalizador de venda para cada produto. O contêiner usa a /category propriedade como uma chave de partição lógica.

Autenticar o cliente

As solicitações de aplicativo para a maioria dos serviços do Azure devem ser autorizadas. Use o tipo como a maneira preferida de implementar uma conexão sem senha entre seus aplicativos e o DefaultAzureCredential Azure Cosmos DB para NoSQL. DefaultAzureCredential suporta vários métodos de autenticação e determina qual método deve ser usado em tempo de execução.

Importante

Você também pode autorizar solicitações aos serviços do Azure usando senhas, cadeias de conexão ou outras credenciais diretamente. No entanto, esta abordagem deve ser utilizada com precaução. Os desenvolvedores devem ser diligentes para nunca expor esses segredos em um local inseguro. Qualquer pessoa que obtenha acesso à senha ou chave secreta pode se autenticar no serviço de banco de dados. DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança sobre a chave da conta para permitir autenticação sem senha sem o risco de armazenar chaves.

Primeiro, este exemplo cria uma nova classe que herda para configurar a conexão com AbstractCosmosConfiguration o Azure Cosmos DB para NoSQL.

@Configuration
@EnableCosmosRepositories
public class CosmosConfiguration extends AbstractCosmosConfiguration {

Dentro da classe de configuração, este exemplo cria uma nova instância da classe e configura a CosmosClientBuilder autenticação usando uma DefaultAzureCredential instância.

@Bean
public CosmosClientBuilder getCosmosClientBuilder() {
    DefaultAzureCredential azureTokenCredential = new DefaultAzureCredentialBuilder()
        .build();
        
    return new CosmosClientBuilder()
        .endpoint(uri)
        .credential(azureTokenCredential);
}

Obter uma base de dados

Na classe de configuração, o exemplo implementa um método para retornar o nome do banco de dados existente chamado cosmicworks.

@Override
protected String getDatabaseName() {
    return "cosmicworks";
}

Obter um contentor

Use o decorador de Container método para configurar uma classe para representar itens em um contêiner. Crie a classe para incluir todos os membros que você deseja serializar em JSON. Neste exemplo, o tipo tem um identificador exclusivo e campos para categoria, nome, quantidade, preço e liberação.

@Container(containerName = "products", autoCreateContainer = false)
public class Item {
    private String id;
    private String name;
    private Integer quantity;
    private Boolean sale;

    @PartitionKey
    private String category;

Criar um item

Crie um item no contêiner usando repository.saveo .

Item item = new Item(
    "70b63682-b93a-4c77-aad2-65501347265f",
    "gear-surf-surfboards",
    "Yamba Surfboard",
    12,
    false
);
Item created_item = repository.save(item);

Ler um item

Execute uma operação de leitura pontual usando os campos identificador exclusivo (id) e chave de partição. Use repository.findById para recuperar eficientemente o item específico.

PartitionKey partitionKey = new PartitionKey("gear-surf-surfboards");
Optional<Item> existing_item = repository.findById("70b63682-b93a-4c77-aad2-65501347265f", partitionKey);
if (existing_item.isPresent()) {
    // Do something  
}

Itens de consulta

Execute uma consulta sobre vários itens em um contêiner definindo uma consulta na interface do repositório. Este exemplo usa o decorador de Query método para definir um método que executa esta consulta parametrizada:

SELECT * FROM products p WHERE p.category = @category

@Repository
public interface ItemRepository extends CosmosRepository<Item, String> {
    @Query("SELECT * FROM products p WHERE p.category = @category")
    List<Item> getItemsByCategory(@Param("category") String category);
}

Obtenha todos os resultados da consulta usando repository.getItemsByCategory. Percorra os resultados da consulta.

List<Item> items = repository.getItemsByCategory("gear-surf-surfboards");
for (Item item : items) {
    // Do something
}

Próximo passo

Tutorial: Construir um aplicativo Web Java