Partilhar via

Biblioteca de Clientes do Azure Cosmos DB para Java – versão 4.52.0

  • Artigo

O Azure Cosmos DB é o serviço de banco de dados multimodelo da Microsoft, distribuído globalmente, para cargas de trabalho de análise e operacionais. Ele oferece o recurso de vários mestres dimensionando automaticamente a taxa de transferência, a computação e o armazenamento. Este projeto fornece a biblioteca do SDK em Java para interagir com a API do SQL do Serviço de Banco de Dados do Azure Cosmos DB.

Código-fonte | Pacote (Maven) | Documentação | de referência da APIDocumentação do produto | Amostras

Introdução

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Depois, inclua a dependência direta na seção de dependências sem a marca de versão.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira. //: # ({x-version-update-start; com.azure:azure-cosmos; current})

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-cosmos</artifactId>
  <version>4.52.0</version>
</dependency>

Consulte o maven central para versões anteriores

Consulte javadocs para obter mais detalhes sobre o pacote

Pré-requisitos

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.

O SDK fornece APIs assíncronas baseadas em Reactor Core. Você pode ler mais sobre os tipos Reactor Core e Flux/Mono aqui

Autenticar o cliente

Para interagir com o serviço do Azure Cosmos DB, você precisará criar uma instância da classe cliente cosmos. Para tornar isso possível, você precisará de uma URL e uma chave do serviço do Azure Cosmos DB.

O SDK fornece dois clientes.

  1. CosmosAsyncClient para operações que usam APIs assíncronas.
  2. CosmosClient para operações que usam APIs síncronas (bloqueio).

Criar CosmosAsyncClient

CosmosAsyncClient cosmosAsyncClient = new CosmosClientBuilder()
    .endpoint(serviceEndpoint)
    .key(key)
    .buildAsyncClient();

Criar CosmosClient

CosmosClient cosmosClient = new CosmosClientBuilder()
    .endpoint(serviceEndpoint)
    .key(key)
    .buildClient();

Conceitos Principais

O SDK do Java do Azure Cosmos DB fornece representação lógica do lado do cliente para acessar a API de SQL do Azure Cosmos DB. Uma conta do Cosmos DB contém zero ou mais bancos de dados, um banco de dados (BD) contém zero ou mais contêineres e um contêiner contém zero ou mais itens. Você pode ler mais sobre bancos de dados, contêineres e itens aqui. Algumas propriedades importantes definidas no nível do contêiner, entre elas, são a taxa de transferência provisionada e a chave de partição.

Distribuição Global

  • O Azure Cosmos DB é um serviço de banco de dados distribuído globalmente projetado para fornecer baixa latência, escalabilidade elástica de taxa de transferência, semântica bem definida para consistência de dados e alta disponibilidade. Em suma, se seu aplicativo precisar de tempo de resposta rápido garantido em qualquer lugar do mundo, se for necessário estar sempre online e precisar de escalabilidade ilimitada e elástica de taxa de transferência e armazenamento, você deverá criar seu aplicativo no Azure Cosmos DB. Você pode ler mais sobre a distribuição global aqui.

Provisionamento de taxa de transferência

  • O Azure Cosmos DB permite que você defina a taxa de transferência nos seus banco de dados e contêineres. Há dois tipos de taxa de transferência provisionada, padrão (manual) ou dimensionamento automático. A taxa de transferência provisionada pode ser selecionada na granularidade por contêiner ou na granularidade por banco de dados. No entanto, há preferência pela especificação da taxa de transferência no nível de contêiner normalmente. Você pode ler mais sobre o provisionamento de taxa de transferência aqui.

RUs (Unidades de Solicitação)

  • O Azure Cosmos DB dá suporte a muitas APIs como SQL, MongoDB, Cassandra, Gremlin e Table. Cada API tem seu próprio conjunto de operações de banco de dados. Essas operações variam de simples leituras e gravações de pontos a consultas complexas. Cada operação de banco de dados consome recursos do sistema com base na complexidade da operação. O custo de todas as operações do banco de dados é normalizado pelo Azure Cosmos DB e expresso por Unidades de Solicitação (ou RUs, abreviado na sigla em inglês). É possível pensar em RUs por segundo como a moeda para a taxa de transferência. RUs por segundo é uma moeda baseada em taxa. Elas extraem os recursos do sistema como CPU, IOPS e memória que são necessários para executar as operações do banco de dados com suporte no Azure Cosmos DB. Você pode ler mais sobre unidades de solicitação aqui.

Particionamento

  • À medida que itens são inseridos em um contêiner do Cosmos DB, o banco de dados cresce horizontalmente adicionando mais armazenamento e computação para lidar com solicitações. As capacidades de armazenamento e computação são adicionadas em unidades discretas conhecidas como partições e você deve escolher um campo em seus documentos para ser a chave de partição que mapeia cada documento para uma partição. A maneira como as partições são gerenciadas é que cada participação recebe uma fatia aproximadamente igual do intervalo dos valores de chave de partição; portanto, é recomendável escolher uma chave de partição relativamente aleatória ou distribuída uniformemente. Caso contrário, algumas partições terão substancialmente mais solicitações (partição a quente), enquanto outras partições terão substancialmente menos solicitações (partição a frio), o que deve ser evitado. Você pode saber mais sobre particionamento aqui.

Exemplos

A seção a seguir fornece vários snippets de código que abrangem algumas das tarefas mais comuns da API sql do Cosmos DB, incluindo:

Criar cliente do Cosmos

// Create a new CosmosAsyncClient via the CosmosClientBuilder
// It only requires endpoint and key, but other useful settings are available
CosmosAsyncClient cosmosAsyncClient = new CosmosClientBuilder()
    .endpoint("<YOUR ENDPOINT HERE>")
    .key("<YOUR KEY HERE>")
    .buildAsyncClient();

// Create a new CosmosClient via the CosmosClientBuilder
CosmosClient cosmosClient = new CosmosClientBuilder()
    .endpoint("<YOUR ENDPOINT HERE>")
    .key("<YOUR KEY HERE>")
    .buildClient();

// Create a new CosmosClient with customizations
cosmosClient = new CosmosClientBuilder()
    .endpoint(serviceEndpoint)
    .key(key)
    .directMode(directConnectionConfig, gatewayConnectionConfig)
    .consistencyLevel(ConsistencyLevel.SESSION)
    .connectionSharingAcrossClientsEnabled(true)
    .contentResponseOnWriteEnabled(true)
    .userAgentSuffix("my-application1-client")
    .preferredRegions(Arrays.asList("West US", "East US"))
    .buildClient();

Criar banco de dados

Usando qualquer um dos clientes criados no exemplo anterior, você pode criar um banco de dados como este:

// Get a reference to the container
// This will create (or read) a database and its container.
cosmosAsyncClient.createDatabaseIfNotExists("<YOUR DATABASE NAME>")
    // TIP: Our APIs are Reactor Core based, so try to chain your calls
    .map(databaseResponse -> cosmosAsyncClient.getDatabase(databaseResponse.getProperties().getId()))
    .subscribe(database -> System.out.printf("Created database '%s'.%n", database.getId()));

Create Container

Usando o banco de dados criado acima, você pode encadear outra operação a ele para criar um contêiner como este:

cosmosAsyncClient.createDatabaseIfNotExists("<YOUR DATABASE NAME>")
    // TIP: Our APIs are Reactor Core based, so try to chain your calls
    .flatMap(databaseResponse -> {
        String databaseId = databaseResponse.getProperties().getId();
        return cosmosAsyncClient.getDatabase(databaseId)
            // Create Container
            .createContainerIfNotExists("<YOUR CONTAINER NAME>", "/id")
            .map(containerResponse -> cosmosAsyncClient.getDatabase(databaseId)
                .getContainer(containerResponse.getProperties().getId()));
    })
    .subscribe(container -> System.out.printf("Created container '%s' in database '%s'.%n",
        container.getId(), container.getDatabase().getId()));

Operação CRUD em Itens

// Create an item
cosmosAsyncContainer.createItem(new Passenger("carla.davis@outlook.com", "Carla Davis", "SEA", "IND"))
    .flatMap(response -> {
        System.out.println("Created item: " + response.getItem());
        // Read that item 👓
        return cosmosAsyncContainer.readItem(response.getItem().getId(),
            new PartitionKey(response.getItem().getId()), Passenger.class);
    })
    .flatMap(response -> {
        System.out.println("Read item: " + response.getItem());
        // Replace that item 🔁
        Passenger p = response.getItem();
        p.setDestination("SFO");
        return cosmosAsyncContainer.replaceItem(p, response.getItem().getId(),
            new PartitionKey(response.getItem().getId()));
    })
    // delete that item 💣
    .flatMap(response -> cosmosAsyncContainer.deleteItem(response.getItem().getId(),
        new PartitionKey(response.getItem().getId())))
    .block(); // Blocking for demo purposes (avoid doing this in production unless you must)
// ...

Temos um aplicativo de exemplo de introdução disponível aqui.

Além disso, temos mais exemplos de projeto de exemplos.

Solução de problemas

Geral

O Azure Cosmos DB é um banco de dados distribuído rápido e flexível que pode ser dimensionado perfeitamente com garantia de latência e produtividade. Você não precisa fazer alterações importantes de arquitetura nem escrever um código complexo para dimensionar seu banco de dados com o Azure Cosmos DB. Aumentar e reduzir é tão fácil quanto fazer uma única chamada à API ou uma chamada ao método do SDK. No entanto, como o Azure Cosmos DB é acessado por meio de chamadas de rede, há otimizações do lado do cliente que você pode fazer para obter o desempenho máximo ao usar o SDK do Java v4 do Azure Cosmos DB.

  • O guia de desempenho aborda essas otimizações do lado do cliente.

  • O guia de solução de problemas aborda problemas comuns, soluções alternativas, etapas de diagnóstico e ferramentas quando você usa o SDK do Java v4 do Azure Cosmos DB com contas de API do SQL do Azure Cosmos DB.

Habilitar o Registro em log do Cliente

O SDK do Java v4 do Azure Cosmos DB usa SLF4 como a fachada de log que oferece suporte ao log em estruturas de log populares, como log4j e logback.

Por exemplo, se você quiser usar log4j como a estrutura de registros, adicione estas bibliotecas ao seu classpath de Java.

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-log4j12</artifactId>
  <version>${slf4j.version}</version>
</dependency>
<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>${log4j.version}</version>
</dependency>

Adicione também uma configuração de log4j.

# this is a sample log4j configuration

# Set root logger level to INFO and its only appender to A1.
log4j.rootLogger=INFO, A1

log4j.category.com.azure.cosmos=INFO
#log4j.category.io.netty=OFF
#log4j.category.io.projectreactor=OFF
# A1 is set to be a ConsoleAppender.
log4j.appender.A1=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d %5X{pid} [%t] %-5p %c - %m%n

Próximas etapas

Contribuição

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 de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (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 usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões