Introducción al SDK de Azure y Apache Maven

  • Artículo

En este artículo se muestra cómo usar Apache Maven para compilar aplicaciones con el SDK de Azure para Java. En este artículo, configurará un nuevo proyecto con Maven, compilará proyectos con Maven y usará las herramientas de imágenes nativas de GraalVM para crear archivos binarios nativos específicos de la plataforma.

El proyecto azure SDK para Java incluye un arquetipo de Maven que puede acelerar el arranque de un nuevo proyecto. El arquetipo de Maven del SDK de Azure para Java crea una nueva aplicación, con archivos y una estructura de directorios que sigue los procedimientos recomendados. En concreto, el arquetipo azure SDK para Java Maven crea un nuevo proyecto de Maven con las siguientes características:

  • Una dependencia de la versión más reciente azure-sdk-bom de boM, que garantiza que todas las dependencias del SDK de Azure para Java estén alineadas y le proporcione la mejor experiencia de desarrollador posible.
  • Compatibilidad integrada con la compilación de imágenes nativas de GraalVM.
  • Compatibilidad con la generación de un nuevo proyecto con un conjunto especificado de bibliotecas cliente de Azure SDK para Java.
  • Integración con las herramientas de compilación del SDK de Azure para Java, que proporciona análisis en tiempo de compilación del proyecto para asegurarse de que se siguen muchos procedimientos recomendados.

Requisitos previos

  • Kit para desarrolladores de Java, versión 8 o posterior. Se recomienda la versión 17 para obtener la mejor experiencia.
  • Apache Maven

Creación de un nuevo proyecto de Maven

El arquetipo maven del SDK de Azure para Java se publica en Maven Central. Esto significa que puede usar el arquetipo directamente para arrancar una nueva aplicación con el siguiente comando:

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

Después de escribir este comando, una serie de mensajes solicita detalles sobre el proyecto para que el arquetipo pueda generar la salida correcta automáticamente. En la tabla siguiente se describen las propiedades para las que debe proporcionar valores:

Nombre Descripción
groupId (Obligatorio) Maven groupId que se va a usar en el archivo POM creado para el proyecto generado.
artifactId (Obligatorio) Maven artifactId que se va a usar en el archivo POM creado para el proyecto generado.
package (Opcional) Nombre del paquete en el que se va a colocar el código generado. Se deduce de groupId si no se especifica.
azureLibraries (Opcional) Una lista separada por comas de las bibliotecas de Azure SDK para Java mediante sus identificadores de artefacto de Maven. Para obtener una lista de estos identificadores de artefacto, consulte Versiones del SDK de Azure.
enableGraalVM (Opcional) false para indicar que el archivo POM de Maven generado no debe incluir compatibilidad para compilar la aplicación en una imagen nativa mediante GraalVM; en caso contrario, true. El valor predeterminado es true.
javaVersion (Opcional) Versión mínima del JDK de destino al compilar el proyecto generado, como 8, 11 o 17. El valor predeterminado es la versión ltS más reciente (actualmente 17). El valor mínimo es 8.
junitVersion (Opcional) Versión de JUnit que se va a incluir como dependencia. El valor predeterminado es 5. Valores válidos 4 y 5.

Como alternativa, puede proporcionar estos valores al llamar al comando archetype mostrado anteriormente. Este enfoque es útil, por ejemplo, con fines de automatización. Puede especificar los valores como parámetros mediante la sintaxis estándar de Maven de anexar -D al nombre del parámetro, por ejemplo:

-DjavaVersion=17

Compatibilidad con versiones de Java

Como procedimiento recomendado, debe usar una versión ltS de Java al implementar en producción. De forma predeterminada, el arquetipo Maven del SDK de Azure selecciona la versión más reciente de LTS, que actualmente establece una línea base de Java 17. Sin embargo, puede invalidar el comportamiento predeterminado estableciendo el javaVersion parámetro .

Uso de la herramienta de compilación del SDK de Azure para Java

El proyecto sdk de Azure para Java incluye una herramienta de compilación de Maven que puede incluir en los proyectos. Esta herramienta se ejecuta localmente y no transmite ningún dato a Microsoft. Puede configurar la herramienta para generar un informe o producir un error en la compilación cuando se cumplan determinadas condiciones, lo que resulta útil para garantizar el cumplimiento de numerosos procedimientos recomendados, como los procedimientos siguientes:

  • Validación del uso correcto de la azure-sdk-for-java lista de materiales, incluido el uso de la versión más reciente, y la confianza en ella para definir versiones de dependencia en azure SDK para bibliotecas cliente de Java. Para más información, consulte la sección Incorporación del SDK de Azure para Java a un proyecto existente.
  • Validación de que las bibliotecas cliente históricas de Azure no se usan cuando existen versiones más recientes y mejoradas.

El informe también proporciona información sobre el uso de las API beta.

Puede configurar la herramienta de compilación en un archivo POM de Maven de proyecto como se muestra en el ejemplo siguiente. Asegúrese de reemplazar el {latest_version} marcador de posición por la versión más reciente que aparece en línea.

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

Después de agregar la herramienta de compilación a un proyecto de Maven, puede ejecutar la herramienta llamando a mvn compile azure:run. Dependiendo de la configuración proporcionada, puede esperar ver errores de compilación o archivos de informe generados que pueden informar sobre posibles problemas antes de que se vuelvan más graves. Se recomienda ejecutar esta herramienta como parte de la canalización de CI/CD. A medida que evoluciona la herramienta de compilación, publicaremos nuevas versiones y recomendamos que los desarrolladores comprueben con frecuencia las nuevas versiones y actualicen según corresponda.

Es posible configurar la herramienta de compilación para habilitar o deshabilitar características concretas. Para esta configuración, agregue una configuration sección en el XML mostrado anteriormente. Dentro de esa sección, configure las opciones que se muestran en la tabla siguiente. Cualquier configuración que no se mencione explícitamente toma el valor predeterminado especificado en la tabla.

Nombre de propiedad Valor predeterminado Descripción
validateAzureSdkBomUsed true Garantiza que el proyecto tenga la BOM azure-sdk-for-java a la que se hace referencia correctamente, de modo que las dependencias de la biblioteca cliente de Azure SDK para Java puedan tomar sus versiones de la boM.
validateLatestBomVersionUsed true Garantiza que las dependencias se mantengan actualizadas mediante la creación de informes (o con errores en la compilación) si existe una boM de azure-sdk-for-java más reciente. Siempre puede encontrar la versión más reciente en línea.
validateBomVersionsAreUsed true Garantiza que, cuando una dependencia esté disponible en la boM azure-sdk-for-java, la versión no se invalida manualmente.
validateNoDeprecatedMicrosoftLibraryUsed true Garantiza que el proyecto no use bibliotecas de Azure de generación anterior. Es poco probable que el uso de las bibliotecas de nueva y anterior en un solo proyecto cause ningún problema, pero da lugar a una experiencia de desarrollador poco óptima.
validateNoBetaLibraryUsed false Algunas bibliotecas cliente de Azure SDK para Java tienen versiones beta, con cadenas de versión con el formato x.y.z-beta.n. La habilitación de esta característica garantiza que no se use ninguna biblioteca beta.
validateNoBetaApiUsed true Las bibliotecas cliente del SDK de Azure para Java a veces tienen versiones de disponibilidad general con métodos anotados con @Beta. Esta comprobación busca ver si se usan estos métodos.
sendToMicrosoft true Especifica si se debe enviar el informe de compilación a Microsoft con fines de telemetría. Esto ayuda a guiar al equipo de desarrollo sobre dónde priorizar la documentación, los ejemplos y las API de comodidad mejoradas. No se envía ningún contenido identificable por el usuario.
reportFile - (Opcional) Especifica la ubicación en la que se va a escribir el informe de compilación, en formato JSON. Si no se especifica, no se escribe ningún informe y se muestra un resumen de la compilación o los errores de compilación adecuados en el terminal.

Adición del SDK de Azure para Java a un proyecto existente

Para que la administración de versiones de dependencia sea más sencilla, el equipo de Azure SDK para Java publica la BOM de cliente de Azure SDK para Java cada mes. Este archivo BOM incluye todos los paquetes de cliente de Azure SDK de Azure (GA) disponibles con carácter general para Java con su versión de dependencia compatible.

Para usar versiones de dependencia para una biblioteca cliente de Azure SDK para Java que se encuentra en la lista de materiales, incluya el siguiente fragmento de código en el archivo pom.xml del proyecto. Reemplace el {bom_version_to_target} marcador de posición por la versión más reciente del SDK de Azure para Java BOM. Reemplace el marcador de {artifactId} posición por el nombre del paquete del SDK de servicio de 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>

Puede encontrar todas las versiones de la BOM del cliente de Azure SDK para Java en azure-sdk-bom. Se recomienda usar la versión más reciente para aprovechar las características más recientes de las bibliotecas cliente de Azure SDK para Java.

El uso de Maven para definir dependencias del proyecto puede simplificar la administración de los proyectos. Con el arquetipo BoM del SDK de Azure y maven del SDK de Azure, puede acelerar el proyecto mientras está más seguro sobre el control de versiones de dependencia a largo plazo. Se recomienda usar la lista de materiales para mantener las dependencias alineadas y actualizadas.

Además de agregar la boM del SDK de Azure, también se recomienda incluir la herramienta de compilación azure SDK para Java. Esta herramienta ayuda a diagnosticar muchos problemas que se suelen encontrar al compilar aplicaciones, como se ha descrito anteriormente en este artículo.

Incluir un paquete no en la lista de materiales

La BOM del cliente de Azure SDK para Java solo incluye bibliotecas disponibles con carácter general (GA). Si desea depender de un paquete que todavía está en versión beta o en una versión de biblioteca diferente de la incluida en la lista de materiales, puede especificar la versión de dependencia de Maven junto con y groupIdartifactId en la sección de dependencias. Puede elegir tener dependencias que usen versiones de BOM y dependencias con versiones invalidadas en el mismo archivo POM del proyecto, como se muestra en el ejemplo siguiente:

<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>

Si usa este enfoque y especifica las versiones directamente en el proyecto, es posible que obtenga conflictos de versión de dependencia. Estos conflictos surgen porque diferentes paquetes pueden depender de diferentes versiones de dependencias comunes y es posible que estas versiones no sean compatibles entre sí. Cuando se producen conflictos, puede experimentar un comportamiento no deseado en tiempo de compilación o tiempo de ejecución. Se recomienda confiar en las versiones que se encuentran en la BOM del SDK de Azure a menos que sea necesario. Para más información sobre cómo tratar las dependencias al usar el SDK de Azure para Java, consulte Solución de problemas de conflictos de versiones de dependencia.

Creación de una imagen nativa con GraalVM

Puede usar GraalVM para crear una imagen nativa de una aplicación Java. GraalVM compila el código Java con antelación en código de máquina nativa, lo que puede producir mejoras drásticas en el rendimiento en determinadas situaciones. El SDK de Azure para Java proporciona los metadatos necesarios en cada una de sus bibliotecas cliente para admitir la compilación de imágenes nativas de GraalVM.

Para empezar, debe instalar GraalVM y preparar el sistema de desarrollo para compilar imágenes nativas. El proceso de instalación de GraalVM es sencillo y la documentación de GraalVM proporciona instrucciones paso a paso para instalar GraalVM y usar GraalVM para instalar imágenes nativas. Siga la sección de requisitos previos cuidadosamente para instalar los compiladores nativos necesarios para el sistema operativo.

El arquetipo de Maven del SDK de Azure para Java puede configurar la compilación para admitir la compilación de imágenes nativas de GraalVM, pero también puede agregarla a una compilación de Maven existente. Puede encontrar instrucciones para Maven en el sitio web de GraalVM.

A continuación, está listo para ejecutar una compilación de imagen nativa. Puede usar herramientas estándar de Maven para usar la imagen nativa de GraalVM. Para Maven, use el siguiente comando:

mvn clean package -Pnative

Después de ejecutar este comando, GraalVM genera un archivo ejecutable nativo para la plataforma en la que se ejecuta. El archivo ejecutable aparece en el directorio /target de Maven del proyecto. Ahora puede ejecutar la aplicación con este archivo ejecutable y debe realizar de forma similar a una aplicación Java estándar.

Pasos siguientes

Introducción a las extensiones de Azure para IntelliJ y Eclipse