Introdução ao SDK do Azure e ao Apache Maven

Este artigo mostra como usar o Apache Maven para criar aplicativos com o SDK do Azure para Java. Neste artigo, você configura um novo projeto com o Maven, cria projetos com o Maven e usa as ferramentas de imagem nativas do GraalVM para criar binários nativos específicos da plataforma.

O projeto SDK do Azure para Java inclui um arquétipo Maven que pode acelerar a inicialização de um novo projeto. O arquétipo do SDK do Azure para Java Maven cria um novo aplicativo, com arquivos e uma estrutura de diretórios que segue as práticas recomendadas. Em particular, o arquétipo do SDK do Azure para Java Maven cria um novo projeto Maven com os seguintes recursos:

• Uma dependência da versão mais recente azure-sdk-bom da lista técnica, que garante que todas as dependências do SDK do Azure para Java estejam alinhadas e oferece a melhor experiência de desenvolvedor possível.
• Suporte integrado para compilação de imagens nativas GraalVM.
• Suporte para gerar um novo projeto com um conjunto especificado de bibliotecas de cliente do SDK do Azure para Java.
• Integração com as ferramentas de compilação do SDK do Azure para Java, que fornecem análise em tempo de compilação do seu projeto para garantir que muitas práticas recomendadas sejam seguidas.

Pré-requisitos

• Java Developer Kit, versão 8 ou posterior. Recomendamos a versão 17 para a melhor experiência.
• Apache Maven

Criar um novo projeto do Maven

O arquétipo do SDK do Azure para Java Maven é publicado no Maven Central. Isso significa que você pode usar o arquétipo diretamente para inicializar um novo aplicativo com o seguinte comando:

mvn archetype:generate \
    -DarchetypeGroupId=com.azure.tools \
    -DarchetypeArtifactId=azure-sdk-archetype

Depois de inserir esse comando, uma série de prompts solicita detalhes sobre seu projeto para que o arquétipo possa gerar a saída certa para você. A tabela a seguir descreve as propriedades para as quais você precisa fornecer valores:

Nome	Descrição
groupId	(Obrigatório) O Maven groupId para usar no arquivo POM criado para o projeto gerado.
artifactId	(Obrigatório) O Maven artifactId para usar no arquivo POM criado para o projeto gerado.
package	(Opcional) O nome do pacote no qual colocar o código gerado. Inferido a partir do groupId se não for especificado.
azureLibraries	(Opcional) Uma lista separada por vírgulas do SDK do Azure para bibliotecas Java, usando suas IDs de artefato Maven. Para obter uma lista dessas IDs de artefato, consulte Versões do SDK do Azure.
enableGraalVM	(Opcional) false para indicar que o arquivo Maven POM gerado não deve incluir suporte para compilar seu aplicativo em uma imagem nativa usando GraalVM; caso contrário, true. O valor padrão é true.
javaVersion	(Opcional) A versão mínima do JDK a ser direcionada ao criar o projeto gerado, como 8, 11 ou 17. O valor padrão é a versão LTS mais recente (atualmente 17). O valor mínimo é 8.
junitVersion	(Opcional) A versão do JUnit a incluir como dependência. O valor padrão é 5. Valores válidos 4 e 5.

Como alternativa, você pode fornecer esses valores ao chamar o comando archetype mostrado anteriormente. Esta abordagem é útil, por exemplo, para fins de automação. Você pode especificar os valores como parâmetros usando a sintaxe Maven padrão de anexar -D ao nome do parâmetro, por exemplo:

-DjavaVersion=17

Suporte à versão Java

Como prática recomendada, você deve usar uma versão Java LTS ao implementar na produção. Por padrão, o arquétipo Maven do SDK do Azure seleciona a versão LTS mais recente, que atualmente define uma linha de base Java 17. No entanto, você pode substituir o comportamento padrão definindo o javaVersion parâmetro.

Usar a ferramenta de compilação do SDK do Azure para Java

O projeto SDK do Azure para Java fornece uma ferramenta de compilação Maven que você pode incluir em seus projetos. Esta ferramenta é executada localmente e não transmite quaisquer dados para a Microsoft. Você pode configurar a ferramenta para gerar um relatório ou falhar na compilação quando determinadas condições forem atendidas, o que é útil para garantir a conformidade com várias práticas recomendadas, como as seguintes práticas:

• Validação do uso correto da lista técnica, incluindo o uso da versão mais recente e a confiança nela para definir versões de azure-sdk-for-java dependência no SDK do Azure para bibliotecas de cliente Java. Para obter mais informações, consulte a seção Adicionar SDK do Azure para Java a um projeto existente.
• Validação de que as bibliotecas de cliente históricas do Azure não estão sendo usadas quando existem versões mais recentes e aprimoradas.

O relatório também fornece informações sobre o uso de APIs beta.

Você pode configurar a ferramenta de compilação em um arquivo de projeto Maven POM, conforme mostrado no exemplo a seguir. Certifique-se de substituir o espaço reservado {latest_version} pela versão mais recente listada online.

<build>
  <plugins>
    <plugin>
      <groupId>com.azure.tools</groupId>
      <artifactId>azure-sdk-build-tool</artifactId>
      <version>{latest_version}</version>
    </plugin>
  </plugins>
</build>

Depois de adicionar a ferramenta de compilação em um projeto Maven, você pode executar a ferramenta chamando mvn compile azure:run. Dependendo da configuração fornecida, você pode esperar ver falhas de compilação ou arquivos de relatório gerados que podem informá-lo sobre possíveis problemas antes que eles se tornem mais sérios. Recomendamos que você execute essa ferramenta como parte do seu pipeline de CI/CD. À medida que a ferramenta de compilação evolui, publicaremos novas versões e recomendamos que os desenvolvedores verifiquem frequentemente se há novas versões e atualizem conforme apropriado.

É possível configurar a ferramenta de compilação para ativar ou desativar recursos específicos. Para essa configuração, adicione uma configuration seção no XML mostrado anteriormente. Dentro dessa seção, defina as configurações mostradas na tabela a seguir. Qualquer configuração que não seja explicitamente mencionada usa o valor padrão especificado na tabela.

Nome da propriedade	Valor predefinido	Description
validateAzureSdkBomUsed	verdadeiro	Garante que o projeto tenha a lista técnica azure-sdk-for-java referenciada adequadamente, para que as dependências da biblioteca de cliente do SDK do Azure para Java possam tirar suas versões da lista técnica .
validateLatestBomVersionUsed	verdadeiro	Garante que as dependências sejam mantidas atualizadas relatando (ou falhando na compilação) se existir uma lista técnica azure-sdk-for-java mais recente. Pode sempre encontrar a versão mais recente online.
validateBomVersionsAreUsed	verdadeiro	Garante que, quando uma dependência estiver disponível na lista técnica azure-sdk-for-java, a versão não esteja sendo substituída manualmente.
validateNoDeprecatedMicrosoftLibraryUsed	verdadeiro	Garante que o projeto não use bibliotecas do Azure da geração anterior. É improvável que o uso das bibliotecas da nova geração e da geração anterior em um único projeto cause qualquer problema, mas resulta em uma experiência de desenvolvedor abaixo do ideal.
validateNoBetaLibraryUsed	false	Algumas bibliotecas de cliente do SDK do Azure para Java têm versões beta, com cadeias de caracteres de versão no formato x.y.z-beta.n. Ativar esse recurso garante que nenhuma biblioteca beta esteja sendo usada.
validateNoBetaApiUsed	verdadeiro	Às vezes, as bibliotecas de cliente do SDK do Azure para Java têm versões do GA com métodos anotados com @Beta. Esta verificação verifica se estão a ser utilizados métodos deste tipo.
sendToMicrosoft	verdadeiro	Especifica se o relatório de compilação deve ser enviado à Microsoft para fins de telemetria. Isso ajuda a orientar a equipe de desenvolvimento sobre onde priorizar documentação, exemplos e APIs de conveniência aprimoradas. Nenhum conteúdo identificável pelo usuário é enviado.
reportFile	-	(Opcional) Especifica o local para gravar o relatório de compilação, no formato JSON. Se não for especificado, nenhum relatório será escrito e um resumo da compilação, ou as falhas de compilação apropriadas, será mostrado no terminal.

Adicionar o SDK do Azure para Java a um projeto existente

Para simplificar o gerenciamento de versões de dependência, a equipe do SDK do Azure para Java publica a lista técnica do cliente do SDK do Azure para Java todos os meses. Este arquivo de BOM inclui todos os pacotes de cliente do SDK do Azure para Java geralmente disponíveis (GA) com sua versão de dependência compatível.

Para usar versões de dependência para uma biblioteca de cliente do SDK do Azure para Java que esteja na BOM, inclua o seguinte trecho no arquivo pom.xml do projeto. Substitua o espaço reservado {bom_version_to_target}pela versão mais recente do SDK do Azure para Java BOM. Substitua o espaço reservado {artifactId} pelo nome do pacote do SDK de serviço 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>

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>{artifactId}</artifactId>
  </dependency>
</dependencies>

Você pode encontrar todas as versões da lista técnica do cliente do SDK do Azure para Java em azure-sdk-bom. Recomendamos usar a versão mais recente para aproveitar os recursos mais recentes do SDK do Azure para bibliotecas de cliente Java.

Usar o Maven para definir dependências de projeto pode tornar o gerenciamento de seus projetos mais simples. Com o arquétipo BOM do SDK do Azure e o arquétipo Maven do SDK do Azure, você pode acelerar seu projeto enquanto tem mais confiança sobre o controle de versão da dependência a longo prazo. Recomendamos o uso da lista técnica para manter as dependências alinhadas e atualizadas.

Além de adicionar a lista técnica do SDK do Azure, recomendamos incluir também a ferramenta de compilação do SDK do Azure para Java. Essa ferramenta ajuda a diagnosticar muitos problemas comumente encontrados ao criar aplicativos, conforme descrito anteriormente neste artigo.

Incluir um pacote que não está na lista técnica

A lista técnica do cliente SDK do Azure para Java inclui apenas bibliotecas GA. Se você quiser depender de um pacote que ainda está em versão beta ou de uma versão de biblioteca diferente da incluída na BOM, você pode especificar a versão de dependência do Maven junto com o groupId e artifactId na seção de dependência. Você pode optar por ter dependências que usam versões de BOM e dependências com versões substituídas no mesmo arquivo POM de projeto, conforme mostrado no exemplo a seguir:

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventhubs</artifactId> <!-- Use the dependency version that is in the BOM -->
  </dependency>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-servicebus</artifactId>
    <version>7.4.0</version> <!-- Override the Service Bus dependency version specified in the BOM -->
  </dependency>
</dependencies>

Se você usar essa abordagem e especificar versões diretamente em seu projeto, poderá obter conflitos de versão de dependência. Esses conflitos surgem porque pacotes diferentes podem depender de versões diferentes de dependências comuns, e essas versões podem não ser compatíveis entre si. Quando ocorrem conflitos, você pode experimentar um comportamento indesejável em tempo de compilação ou tempo de execução. Recomendamos que você confie nas versões que estão na lista técnica do SDK do Azure, a menos que seja necessário. Para obter mais informações sobre como lidar com dependências ao usar o SDK do Azure para Java, consulte Solucionar conflitos de versão de dependência.

Crie uma imagem nativa com GraalVM

Você pode usar GraalVM para criar uma imagem nativa de um aplicativo Java. GraalVM compila o código Java antecipadamente em código de máquina nativo, o que pode gerar ganhos drásticos de desempenho em determinadas situações. O SDK do Azure para Java fornece os metadados necessários em cada uma de suas bibliotecas de cliente para dar suporte à compilação de imagens nativas GraalVM.

Para começar, você precisa instalar o GraalVM e preparar seu sistema de desenvolvimento para compilar imagens nativas. O processo de instalação do GraalVM é simples, e a documentação do GraalVM fornece instruções passo a passo para instalar o GraalVM e usar o GraalVM para instalar a imagem nativa. Siga a seção de pré-requisitos cuidadosamente para instalar os compiladores nativos necessários para seu sistema operacional.

O arquétipo do SDK do Azure para Java Maven pode configurar sua compilação para dar suporte à compilação de imagem nativa do GraalVM, mas você também pode adicioná-la a uma compilação Maven existente. Você pode encontrar instruções para o Maven no site da GraalVM.

Em seguida, você está pronto para executar uma compilação de imagem nativa. Você pode usar as ferramentas padrão do Maven para usar a imagem nativa do GraalVM. Para o Maven, use o seguinte comando:

mvn clean package -Pnative

Depois de executar esse comando, o GraalVM gera um executável nativo para a plataforma em que está sendo executado. O executável aparece no diretório Maven /target do seu projeto. Agora você pode executar seu aplicativo com esse arquivo executável, e ele deve funcionar de forma semelhante a um aplicativo Java padrão.

Próximos passos

Introdução às extensões do Azure para IntelliJ e Eclipse