Exercício – Configurar seu aplicativo Java usando o Maven

  • 15 minutos

Nesta unidade, você criará um aplicativo de console básico usando um IDE de sua escolha para editar o código. Opcionalmente, você usará o terminal de sua escolha para executar o código.

Criar recursos do Azure Cosmos DB

Para a realização deste laboratório, o Microsoft Learn fornece uma área restrita do Azure gratuita na qual você pode criar contas e recursos. Configure uma conta do Azure Cosmos DB nessa assinatura e crie um banco de dados e um contêiner.

  1. Entre no portal do Azure usando a mesma conta com a qual você ativou a área restrita.
  2. Usando o portal do Azure, crie uma conta do Azure Cosmos DB com um nome de sua escolha. Quando precisar escolher um grupo de recursos para a sua conta, localize o grupo de recursos [Grupo de recursos da área restrita] e selecione-o.
  3. Na sua conta do Azure Cosmos DB, crie um banco de dados chamado Usuários.
  4. No banco de dados Usuários, crie um contêiner chamado WebCustomers com uma chave de partição de /userId. Provisione 400 RU/s para WebCustomers.

Criar o seu diretório de trabalho

  1. Fornecemos um modelo para seu aplicativo Java. Clone o repositório do modelo no seu sistema.

    git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git

  2. Abra o Explorador de Arquivos do Windows e acesse o repositório clonado. Insira o subdiretório java_lab.

    Importante

    Todo o trabalho realizado neste módulo estará no subdiretório java_lab.

  3. O modelo contém um arquivo Maven pom.xml que já efetua pull das dependências necessárias para seu projeto. Abra esse arquivo e examine-o para encontrar a seguinte dependência:

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

    Essa dependência efetua pull da versão mais recente do SDK do Java do Azure Cosmos DB. Você pode fechar este arquivo.

  4. Em seguida, você criará e executará Olá, Mundo. Usando o IDE ou o terminal, abra esse projeto. Dependendo do seu IDE, pode haver uma opção para abrir o arquivo pom.xml no subdiretório java como um projeto.

    Depois que o projeto estiver aberto, acesse src/main/java/com/azure/cosmos/examples/mslearnbasicapp e abra CosmosApp.java, que é um modelo para o aplicativo Java que desenvolveremos. Ele deverá ser semelhante a este:

    import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public final class CosmosApp {

    /** For application to log INFO and ERROR. */
    private static Logger logger = LoggerFactory.getLogger(CosmosApp.class.getSimpleName());

    private CosmosApp() {
        // not called
    }

    /**
    * Main.
    * @param args Command line arguments
    */
    public static void main(final String[] args) {
        logger.info("Hello World.");
    }
}

    No estado em que se encontra, o código do aplicativo implementa um "Olá, Mundo" simples.

  5. Caso seu IDE ofereça ferramentas para compilar e executar o aplicativo Maven: compile e execute o aplicativo usando o IDE e confirme se o aplicativo registra Hello World no terminal.

  6. Se você usar o terminal para compilar e executar o aplicativo Maven: use o seguinte comando para compilar o projeto Marven:

    mvn clean package

    Em seguida, execute:

    mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    Confirme se o aplicativo registra a seguinte saída no terminal:

    INFO: Hello World.

Conectar o aplicativo ao Azure Cosmos DB

  1. Na classe CosmosApp, crie as seguintes variáveis de classe estática para os detalhes de conexão do Azure Cosmos DB:

    /** Azure Cosmos DB endpoint URI. */
private static String endpointUri = "<your-cosmosdb-hostname>";

/** Azure Cosmos DB primary key. */
private static String primaryKey = "<your-cosmosdb-master-key>";

  2. Retorne ao portal do Azure, vá para o painel Chaves e copie/cole o URI de ponto de extremidade do Azure Cosmos DB e a chave primária nas definições de variável acima.

    Por exemplo, se o URI for https://cosmosacct.documents.azure.com:443/, a nova atribuição de variável terá a seguinte aparência: private static String endpointUri = "https://cosmosacct.documents.azure.com:443/";. Se a sua chave primária for elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==, a nova atribuição de variável terá a seguinte aparência: private static String primaryKey = "elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==";.

Criar a instância CosmosAsyncClient

Agora é hora de criar uma instância do CosmosAsyncClient, que é a representação do lado do cliente do serviço Azure Cosmos DB. Esse cliente é usado para configurar e executar solicitações no serviço.

  1. No CosmosApp.Java, adicione a seguinte declaração de variável estática à classe CosmosApp:

    /** Azure Cosmos DB client instance. */
private static CosmosAsyncClient client;

/** Azure Cosmos DB database instance. */
private static CosmosAsyncDatabase database;

/** Azure Cosmos DB container instance. */
private static CosmosAsyncContainer container;

    Provavelmente, as classes client, database e container ainda não foram importadas para o arquivo Java. É um bom momento para cuidar disso agora. Alguns IDEs podem permitir que você importe dependências automaticamente com base no código digitado, e isso pode ser útil nesse momento. De modo geral, esperamos que, ao fornecermos um bloco de código para colagem, talvez seja necessário adicionar algumas instruções import para que ele funcione.

  2. Crie um método private void chamado basicOperations sem argumentos na classe.

  3. Adicione o código a seguir para criar uma instância CosmosAsyncClient no método basicOperations e inclua o código para verificar se o banco de dados Usuários existe.

     client = new CosmosClientBuilder()
     .endpoint(endpointUri)
     .key(primaryKey)
     .consistencyLevel(ConsistencyLevel.EVENTUAL)
     .directMode()
     .contentResponseOnWriteEnabled(true)
     .buildAsyncClient();

 database = client.getDatabase("Users");
 container = database.getContainer("WebCustomers");            

 logger.info("Database and container validation complete");

 client.close();

  4. Nesse momento, o seu método basicOperations contém o código para interagir com o Azure Cosmos DB. No entanto, esse método não é chamado no main, portanto, nosso aplicativo ainda serve para imprimir "Olá, Mundo". Como uma verificação, compile e execute CosmosApp.java no IDE ou execute o programa no terminal usando:

    mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    Confirme se o aplicativo ainda registra a seguinte saída no terminal:

    INFO: Hello World.

  5. Copie e cole o seguinte código no método main, substituindo a linha logger.info("Hello World."); atual.

    try {
    CosmosApp p = new CosmosApp();
    p.basicOperations();
} catch (CosmosException e) {
    logger.error("Failed while executing app.", e);
} finally {
    logger.info("End of demo, press any key to exit.");
}

    Isso dispara o código do Azure Cosmos DB no nosso aplicativo.

  6. Crie e execute o CosmosApp.java no IDE ou execute o programa no terminal usando:

    mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    Você pode ver um grande número de mensagens de log no terminal, algumas delas geradas pelo próprio SDK. Leia e confirme se o aplicativo registra a seguinte saída no terminal:

    INFO: Database and container validation complete

Nesta unidade, você configurou as bases do aplicativo Java do Azure Cosmos DB. Você configurou o seu aplicativo Maven, criou um projeto básico de "Olá, Mundo" e estendeu-o para conectar o projeto ao ponto de extremidade do Azure Cosmos DB.

  1. Fornecemos um modelo para o seu aplicativo Java. Clonar o repositório de modelos no seu sistema

    git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git

  2. Abra o Windows Explorer e navegue até o repositório clonado. Insira o subdiretório spring_lab.

    Importante

    Todo o trabalho realizado neste módulo estará no subdiretório spring_lab.

  3. O modelo contém um Maven pom.xml que já efetua pull das dependências necessárias para o seu projeto. Abra esse arquivo e examine-o para encontrar a dependência abaixo:

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

    Essa dependência efetua pull da versão mais recente do Spring Data para Azure Cosmos DB. Você pode fechar este arquivo.

Conectar o aplicativo ao Azure Cosmos DB

  1. Usando o IDE ou o terminal, abra esse projeto. Dependendo do seu IDE, pode haver uma opção para abrir o arquivo pom.xml no subdiretório spring como um projeto. Depois que o projeto estiver aberto, navegue até src/main/resources/ usando uma ferramenta do explorador de arquivos. Você deverá ver um arquivo chamado application.properties.rename. O Spring Data prioriza arquivos de configuração em vez de parâmetros de configuração embutidos em código; para criar o arquivo de configuração de seu projeto Spring Data, copie application.properties.rename para application.properties e abra o novo arquivo application.properties. Você deverá ver

    cosmos.uri=${ACCOUNT_HOST}
cosmos.key=${ACCOUNT_KEY}
cosmos.secondaryKey=${SECONDARY_ACCOUNT_KEY}

dynamic.collection.name=spel-property-collection
# Populate query metrics
cosmos.queryMetricsEnabled=true

    Você preencherá ${ACCOUNT_HOST} e ${ACCOUNT_KEY} usando um destes métodos de sua escolha: copiar e colar os valores em application.properties ou definir essas variáveis de ambiente em seu IDE. Na próxima etapa, você descobrirá os valores que essas variáveis devem ter.

  2. Retorne ao portal do Azure, vá para Chaves e copie o URI de ponto de extremidade do Azure Cosmos DB e a chave primária. Conforme discutido na etapa anterior, use o método de sua escolha para atribuir o URI de ponto de extremidade do Azure Cosmos DB e a chave primária para as variáveis mencionadas anteriormente.

    Por exemplo, se o URI for https://cosmosacct.documents.azure.com:443/ e você optar por colar o ponto de extremidade e a chave primária em application.properties, a linha em application.properties terá a seguinte aparência: cosmos.uri=https://cosmosacct.documents.azure.com:443/. Se a sua chave primária for elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ== e você seguir o mesmo processo, a nova atribuição de variável terá a seguinte aparência: cosmos.key=elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==.

Configurar o cliente do Azure Cosmos DB

O Spring Data para Azure Cosmos DB cria automaticamente uma instância para o cliente do Azure Cosmos DB na inicialização. O cliente do Azure Cosmos DB é a representação do lado do cliente do serviço do Azure Cosmos DB, usado para executar solicitações no serviço. Seu código pode configurar o cliente do Azure Cosmos DB antes da criação da instância, usando um conjunto de métodos de construtor com as propriedades extraídas de application.properties.

  1. Abra CosmosProperties.java. Nós fornecemos esse arquivo em um formato completo, portanto, basta examinar o conteúdo.

    @ConfigurationProperties(prefix = "cosmos")
public class CosmosProperties {

    private String uri;

    private String key;

    private String secondaryKey;

    private boolean queryMetricsEnabled;

    public String getUri() {
        return uri;
    }

    public void setUri(String uri) {
        this.uri = uri;
    }

    public String getKey() {
        return key;
    }

    public void setKey(String key) {
        this.key = key;
    }

    public String getSecondaryKey() {
        return secondaryKey;
    }

    public void setSecondaryKey(String secondaryKey) {
        this.secondaryKey = secondaryKey;
    }

    public boolean isQueryMetricsEnabled() {
        return queryMetricsEnabled;
    }

    public void setQueryMetricsEnabled(boolean enableQueryMetrics) {
        this.queryMetricsEnabled = enableQueryMetrics;
    }
}

    Observe os membros de classe uri, key, secondaryKey, queryMetricsEnabled. Olhando novamente para application.properties, observe que os nomes de membros de CosmosProperties correspondem de forma mais próxima aos nomes de propriedade de application.properties. A classe CosmosProperties apresenta getters e setters ao restante do seu aplicativo para o acesso às definições de configuração de application.properties. Observe que não há nenhum código para efetuar pull da configuração de application.properties – o Spring Data compreende a estrutura desse arquivo e define automaticamente as variáveis de membro depois de analisar o arquivo de configuração.

    Aproveitaremos essa configuração no futuro, quando configurarmos o cliente do Azure Cosmos DB.

  2. Em CosmosSampleConfiguration.java, examine a classe CosmosSampleConfiguration e encontre o método cosmosClientBuilder vazio:

    @Bean
public CosmosClientBuilder cosmosClientBuilder() {
    return null;
}

    Na inicialização, o Spring Data chamará automaticamente esse método, obterá o CosmosClientBuilder que esse método retorna e chamará o método build() – neste ponto (nos bastidores), uma instância CosmosAsyncClient será criada com base nas definições de configuração contidas no CosmosClientBuilder. Você pode usar esse método para configurar CosmosClientBuilder usando métodos do construtor.

  3. Observe que usamos injeção de construtor (em vez de injeção de campo) usando @Autowired) para instanciar a variável propertiese preencher as respectivas variáveis de membro com valores analisados do arquivo de configuração. Isso garante que todas as dependências necessárias estejam presentes quando a instância dessa classe for criada e facilita a gravação do código de teste no futuro.

    //use constructor injection for spring dependencies 
public CosmosSampleConfiguration(CosmosProperties properties){
    this.properties = properties;
}

    Podemos usar properties para obter o URI e a chave de nossa conta do Azure Cosmos DB e implementar cosmosClientBuilder conforme mostrado abaixo:

    @Bean
public CosmosClientBuilder cosmosClientBuilder() {
    DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();
    return new CosmosClientBuilder()
        .endpoint(properties.getUri())
        .key(properties.getKey())
        .directMode(directConnectionConfig);
}

    Essa implementação

    1. Efetua pull do URI e da chave de properties
    2. Conecta-os aos métodos endpoint e key do construtor
    3. Além disso, configura a conexão de rede ao serviço do Azure Cosmos DB. (No modo direto, seu aplicativo cliente se comunica diretamente com as partições back-end do Azure Cosmos DB.)

  4. Volte para CosmosSampleConfiguration.java e localize o método getDatabaseName:

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

    Altere o valor retornado padrão para "Users", o nome do seu banco de dados. Dessa forma, quando o Spring Data se conectar automaticamente ao Azure Cosmos DB na inicialização, ele se conectará ao banco de dados *Usuários.

  5. Navegue até WebCustomer.java. Você observará que a classe WebCustomer é precedida por uma anotação @Container:

    @Container(containerName = "", ru = "")

    @Container usa dois argumentos:

    • containerName: o nome do contêiner do Azure Cosmos DB (Webcustomers)
    • ru: a taxa de transferência provisionada em seu contêiner. 400 RU/s é um bom padrão para um exercício do Microsoft Learn.

    Personalize o @Container para seu caso de uso, conforme mostrado:

    @Data
@NoArgsConstructor
@AllArgsConstructor
@Container(containerName = "WebCustomers", ru = "400")
public class WebCustomer {

  6. Neste momento, seu projeto Spring Data é configurado para interagir com o Azure Cosmos DB. Em seguida, você criará e executará Olá, Mundo. Acesse src/main/java/com/azure/cosmos/examples/springexamples e abra CosmosSample.java, que é um modelo para o aplicativo de dados do Spring que desenvolveremos. Ele deverá ser semelhante a este:

    // Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.cosmos.examples.springexamples;

import com.azure.cosmos.CosmosException;
import com.azure.cosmos.examples.springexamples.common.CouponsUsed;
import com.azure.cosmos.examples.springexamples.common.OrderHistory;
import com.azure.cosmos.examples.springexamples.common.ShippingPreference;
import com.azure.cosmos.models.CosmosItemResponse;
import com.azure.cosmos.models.PartitionKey;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

@SpringBootApplication
public class CosmosSample implements CommandLineRunner {

    private final Logger logger = LoggerFactory.getLogger(CosmosSample.class);

    private ReactiveWebCustomerRepository reactiveWebCustomerRepository;

    //constructor dependency injection
    public CosmosSample(ReactiveWebCustomerRepository reactiveWebCustomerRepository){
        this.reactiveWebCustomerRepository = reactiveWebCustomerRepository;
    }

    public void run(String... var1) {
        logger.info("Hello world.");
    }
}

    No estado em que se encontra, o código do aplicativo implementa um "Olá, Mundo" simples.

  7. Caso seu IDE ofereça ferramentas para compilar e executar o aplicativo Maven: compile e execute o aplicativo usando o IDE e confirme se o aplicativo registra Hello World no terminal.

  8. Se você usar o terminal para compilar e executar o aplicativo Maven: use o seguinte comando para compilar o projeto Marven:

    mvn clean package

    Em seguida, execute:

    mvn spring-boot:run

    Confirme se o aplicativo registra a seguinte saída no terminal, entre todas as outras saídas:

    INFO: Hello World.

Nesta unidade, você configurou as bases do aplicativo Java do Azure Cosmos DB. Você personalizou seu aplicativo Maven e estendeu um projeto básico de "Olá, Mundo" para conectá-lo ao ponto de extremidade do Azure Cosmos DB.