Introducción a SDK de Azure y Maven

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:

  • Dependencia de la versión más reciente azure-sdk-bom 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 SDK de Azure 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.

Prerrequisitos

Creación de un nuevo proyecto de Maven

El arquetipo de Maven del SDK de Azure para Java está disponible en Maven Central. Puede usar el arquetipo directamente para arrancar una nueva aplicación ejecutando 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) El groupId de Maven que se debe usar en el archivo POM creado para el proyecto generado.
artifactId (Obligatorio) El artifactId de Maven que se debe 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 del SDK de Azure para Java usando sus ID 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; de lo contrario, true. El valor predeterminado es true.
javaVersion (Opcional) Versión mínima del JDK de destino al compilar el proyecto generado, como 8, 11o 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. Los valores válidos son 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, use una versión de Java LTS 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 parámetro javaVersion.

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 agregar a sus proyectos. Esta herramienta se ejecuta localmente y no envía 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. Esta característica ayuda a garantizar el cumplimiento de los procedimientos recomendados, como los procedimientos siguientes:

  • Validación del uso correcto del BOM de azure-sdk-for-java, incluido el uso de la última versión y basarse en ella para definir las versiones de dependencias en las bibliotecas cliente de SDK de Azure para Java. Para obtener más información, consulte la sección Incorporación del SDK de Azure para Java a un proyecto existente.
  • Validación de que no se utilicen bibliotecas cliente heredadas de Azure cuando existan 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 marcador de posición de {latest_version} por la versión más reciente enumerada 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, ejecute la herramienta llamando a mvn compile azure:run. Dependiendo de la configuración que proporcione, 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. Ejecute esta herramienta como parte de su pipeline de CI/CD. A medida que evoluciona la herramienta de compilación, el equipo de desarrollo publica nuevas versiones. Compruebe con frecuencia las nuevas versiones y actualice según corresponda.

Puede configurar la herramienta de compilación para habilitar o deshabilitar características concretas. Para esta configuración, agregue una sección configuration 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 cierto Garantiza que el proyecto haga referencia correctamente a la azure-sdk-for-java BOM, de modo que las dependencias de las bibliotecas cliente de SDK de Azure para Java obtengan sus versiones de la BOM.
validateLatestBomVersionUsed cierto Garantiza que las dependencias se mantengan actualizadas informando (o haciendo fallar la compilación) si existe un BOM de azure-sdk-for-java más reciente. Siempre puede encontrar la versión más reciente en línea.
validateBomVersionsAreUsed cierto Garantiza que, si una dependencia está disponible en el azure-sdk-for-java BOM, la versión no se sobrescriba manualmente.
validateNoDeprecatedMicrosoftLibraryUsed cierto 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 falso Algunas bibliotecas cliente de SDK de Azure 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 cierto A veces, las bibliotecas cliente del SDK de Azure para Java tienen versiones de disponibilidad general con métodos anotados con @Beta. Esta comprobación busca ver si se usan estos métodos.
sendToMicrosoft cierto Especifica si se debe enviar el informe de compilación a Microsoft con fines de telemetría. Este informe 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 simplificar la gestión de las versiones de las dependencias, el equipo de SDK de Azure para Java publica el BOM de cliente de SDK de Azure para Java cada mes. Este archivo BOM incluye todos los paquetes cliente del SDK de Azure para Java de disponibilidad general (GA), junto con las versiones compatibles de sus dependencias.

Para usar las versiones de las dependencias de una biblioteca cliente del SDK de Azure para Java incluida en la BOM, agregue el siguiente fragmento de código al 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 el BOM en Java. Reemplace el marcador de posición {artifactId} 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 del SDK de Azure para Java en azure-sdk-bom. Use la versión más reciente para aprovechar las características más recientes de la SDK de Azure para Java bibliotecas cliente.

El uso de Maven para definir dependencias del proyecto puede simplificar la administración de los proyectos. Al usar el BOM del SDK de Azure y el arquetipo de Maven del SDK de Azure, puede acelerar su proyecto al tiempo que tiene más confianza en el control de versiones de sus dependencias a largo plazo. Usa la BOM para mantener las dependencias alineadas y al día.

Además de añadir la BOM de SDK de Azure, incluya también la herramienta de compilación de SDK de Azure 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 que no está en el BOM

La BOM del SDK de Azure para Java solo incluye bibliotecas de disponibilidad general (GA). Si quiere usar una dependencia de un paquete que aún está en versión beta o una versión de biblioteca distinta de la incluida en la BOM, especifique la versión de la dependencia de Maven junto con groupId y artifactId 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 su proyecto, es posible que enfrente conflictos de versión de dependencia. Estos conflictos surgen porque los distintos 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. Confíe en las versiones que se encuentran en la SDK de Azure BOM a menos que sea necesario. Para obtener 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, instale GraalVM y prepare 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 mediante 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 del SDK de Azure para Java Maven puede configurar su compilación para admitir la compilación nativa 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, estará listo para ejecutar una construcció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 ejecutable aparece en el directorio /target de Maven de tu 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

  • Last updated on