Prise en main du Kit de développement logiciel (SDK) Azure et d’Apache Maven

  • Article

Cet article explique comment utiliser Apache Maven pour générer des applications avec le Kit de développement logiciel (SDK) Azure pour Java. Dans cet article, vous allez configurer un nouveau projet avec Maven, générer des projets avec Maven et utiliser les outils d’images natives GraalVM pour créer des fichiers binaires natifs spécifiques à la plateforme.

Le projet Azure SDK pour Java inclut un archétype Maven qui peut accélérer l’amorçage d’un nouveau projet. Le Kit de développement logiciel (SDK) Azure pour Java Maven archétype crée une application, avec des fichiers et une structure de répertoires qui suit les meilleures pratiques. En particulier, le Kit de développement logiciel (SDK) Azure pour Java Maven archétype crée un projet Maven avec les fonctionnalités suivantes :

  • Une dépendance à la dernière azure-sdk-bom version de boM, qui garantit que toutes les dépendances pour le Kit de développement logiciel (SDK) Azure pour Java sont alignées et vous offre la meilleure expérience de développement possible.
  • Prise en charge intégrée de la compilation d’images natives GraalVM.
  • Prise en charge de la génération d’un nouveau projet avec un ensemble spécifié de sdk Azure pour les bibliothèques clientes Java.
  • Intégration avec l’outil de génération Azure SDK pour Java, qui fournit une analyse au moment de la génération de votre projet pour vous assurer que de nombreuses bonnes pratiques sont suivies.

Prérequis

  • Kit de développement Java, version 8 ou ultérieure. Nous vous recommandons la version 17 pour une expérience optimale.
  • Apache Maven

Création d’un projet Maven

L’archétype Du Kit de développement logiciel (SDK) Azure pour Java Maven est publié sur Maven Central. Cela signifie que vous pouvez utiliser l’archétype directement pour démarrer une nouvelle application avec la commande suivante :

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

Après avoir entré cette commande, une série d’invites demande des détails sur votre projet afin que l’archétype puisse générer la sortie appropriée pour vous. Le tableau suivant décrit les propriétés dont vous avez besoin pour fournir des valeurs :

Nom Description
groupId (Obligatoire) Maven groupId à utiliser dans le fichier POM créé pour le projet généré.
artifactId (Obligatoire) Maven artifactId à utiliser dans le fichier POM créé pour le projet généré.
package (Facultatif) Nom du package dans lequel placer le code généré. Déduit de la groupId valeur si elle n’est pas spécifiée.
azureLibraries (Facultatif) Liste séparée par des virgules des bibliothèques Du Kit de développement logiciel (SDK) Azure pour Java, à l’aide de leurs ID d’artefact Maven. Pour obtenir la liste de ces ID d’artefacts, consultez les versions du Kit de développement logiciel (SDK) Azure.
enableGraalVM (Facultatif) false pour indiquer que le fichier POM Maven généré ne doit pas inclure la prise en charge de la compilation de votre application sur une image native à l’aide de GraalVM ; sinon, true. La valeur par défaut est true.
javaVersion (Facultatif) Version minimale du JDK à cibler lors de la génération du projet généré, par exemple 8, 11 ou 17. La valeur par défaut est la dernière version LTS (actuellement 17). La valeur minimale est 8.
junitVersion (Facultatif) Version de JUnit à inclure en tant que dépendance. La valeur par défaut est 5. Valeurs valides 4 et 5.

Vous pouvez également fournir ces valeurs lorsque vous appelez la commande archétype indiquée précédemment. Cette approche est utile, par exemple, à des fins d’automatisation. Vous pouvez spécifier les valeurs en tant que paramètres à l’aide de la syntaxe Maven standard d’ajout -D au nom du paramètre, par exemple :

-DjavaVersion=17

Prise en charge des versions de Java

En guise de bonne pratique, vous devez utiliser une version Java LTS lors du déploiement en production. Par défaut, l’archétype Maven du Kit de développement logiciel (SDK) Azure sélectionne la dernière version LTS, qui définit actuellement une base de référence Java 17. Toutefois, vous pouvez remplacer le comportement par défaut en définissant le javaVersion paramètre.

Utiliser l’outil de génération Du Kit de développement logiciel (SDK) Azure pour Java

Le projet Azure SDK pour Java fournit un outil de génération Maven que vous pouvez inclure dans vos projets. Cet outil s’exécute localement et ne transmet aucune donnée à Microsoft. Vous pouvez configurer l’outil pour générer un rapport ou échouer la génération lorsque certaines conditions sont remplies, ce qui est utile pour garantir la conformité avec de nombreuses bonnes pratiques, telles que les pratiques suivantes :

  • Validation de l’utilisation correcte du azure-sdk-for-java boM, y compris l’utilisation de la dernière version, et en s’appuyant sur celle-ci pour définir des versions de dépendance sur les bibliothèques clientes Azure SDK pour Java. Pour plus d’informations, consultez la section Ajouter azure SDK pour Java à une section de projet existante.
  • Validation que les bibliothèques clientes Azure historiques ne sont pas utilisées quand des versions plus récentes et améliorées existent.

Le rapport fournit également des informations sur l’utilisation des API bêta.

Vous pouvez configurer l’outil de génération dans un fichier POM Maven de projet, comme illustré dans l’exemple suivant. Veillez à remplacer l’espace {latest_version} réservé par la dernière version répertoriée en ligne.

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

Après avoir ajouté l’outil de génération à un projet Maven, vous pouvez exécuter l’outil en appelant mvn compile azure:run. Selon la configuration fournie, vous pouvez vous attendre à voir les échecs de build ou les fichiers de rapport générés qui peuvent vous informer des problèmes potentiels avant qu’ils ne deviennent plus sérieux. Nous vous recommandons d’exécuter cet outil dans le cadre de votre pipeline CI/CD. À mesure que l’outil de génération évolue, nous publierons de nouvelles versions et nous recommandons aux développeurs de case activée fréquemment pour les nouvelles versions et les mises à jour appropriées.

Il est possible de configurer l’outil de génération pour activer ou désactiver des fonctionnalités particulières. Pour cette configuration, ajoutez une configuration section dans le code XML indiqué précédemment. Dans cette section, configurez les paramètres indiqués dans le tableau suivant. Toute configuration qui n’est pas explicitement mentionnée prend la valeur par défaut spécifiée dans la table.

Nom de la propriété Default value Description
validateAzureSdkBomUsed true Garantit que le projet dispose du boM azure-sdk-for-java référencé de manière appropriée, afin que les dépendances de bibliothèque cliente Azure SDK pour Java puissent prendre leurs versions à partir du boM.
validateLatestBomVersionUsed true Garantit que les dépendances sont conservées à jour en revenant (ou en cas d’échec de la build) si un boM Azure-sdk-for-java plus récent existe. Vous pouvez toujours trouver la dernière version en ligne.
validateBomVersionsAreUsed true Garantit que, lorsqu’une dépendance est disponible à partir d’azure-sdk-for-java BOM, la version n’est pas remplacée manuellement.
validateNoDeprecatedMicrosoftLibraryUsed true Garantit que le projet n’utilise pas les bibliothèques Azure de génération précédente. L’utilisation des bibliothèques de nouvelle génération et précédente dans un seul projet est peu susceptible d’entraîner un problème, mais entraîne une expérience de développement non optimale.
validateNoBetaLibraryUsed false Certains sdk Azure pour les bibliothèques clientes Java ont des versions bêta, avec des chaînes de version sous la forme x.y.z-beta.n. L’activation de cette fonctionnalité garantit qu’aucune bibliothèque bêta n’est utilisée.
validateNoBetaApiUsed true Les bibliothèques clientes Azure SDK pour Java ont parfois des versions en disponibilité générale avec des méthodes annotées avec @Beta. Cette case activée recherche si de telles méthodes sont utilisées.
sendToMicrosoft true Spécifie s’il faut envoyer le rapport de build à Microsoft à des fins de télémétrie. Cela permet de guider l’équipe de développement sur l’endroit où hiérarchiser la documentation, les exemples et les API pratiques améliorées. Aucun contenu identifiable par l’utilisateur n’est envoyé.
reportFile - (Facultatif) Spécifie l’emplacement dans lequel écrire le rapport de build au format JSON. S’il n’est pas spécifié, aucun rapport n’est écrit et un résumé de la build ou des échecs de build appropriés s’affiche dans le terminal.

Ajouter le Kit de développement logiciel (SDK) Azure pour Java à un projet existant

Pour simplifier la gestion des versions des dépendances, l’équipe Du KIT de développement logiciel (SDK) Azure pour Java publie le Kit de développement logiciel (SDK) Azure pour le bom client Java chaque mois. Ce fichier BOM inclut tous les packages client Azure (GA) disponibles en disponibilité générale pour les packages clients Java avec leur version de dépendance compatible.

Pour utiliser des versions de dépendance pour une bibliothèque cliente Azure SDK pour Java qui se trouve dans le boM, incluez l’extrait de code suivant dans le fichier project pom.xml . Remplacez l’espace {bom_version_to_target} réservé par la dernière version du Kit de développement logiciel (SDK) Azure pour Java BOM. Remplacez l’espace {artifactId} réservé par le nom du package du Kit de développement logiciel (SDK) du service 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>

Vous trouverez toutes les versions du Kit de développement logiciel (SDK) Azure pour Java client BOM sur azure-sdk-bom. Nous vous recommandons d’utiliser la dernière version pour tirer parti des fonctionnalités les plus récentes du Kit de développement logiciel (SDK) Azure pour les bibliothèques clientes Java.

L’utilisation de Maven pour définir des dépendances de projet peut simplifier la gestion de vos projets. Avec l’archétype Du Kit de développement logiciel (SDK) Azure et le Kit de développement logiciel (SDK) Azure Maven, vous pouvez accélérer votre projet tout en étant plus confiant sur votre contrôle de version des dépendances à long terme. Nous vous recommandons d’utiliser le boM pour maintenir l’alignement et la mise à jour des dépendances.

Outre l’ajout du boM du KIT de développement logiciel (SDK) Azure, nous vous recommandons également d’inclure l’outil de build Azure SDK pour Java. Cet outil permet de diagnostiquer de nombreux problèmes couramment rencontrés lors de la création d’applications, comme décrit précédemment dans cet article.

Inclure un package non dans le boM

Le Kit de développement logiciel (SDK) Azure pour les boM client Java inclut uniquement les bibliothèques en disponibilité générale (GA). Si vous souhaitez dépendre d’un package toujours en version bêta ou d’une version de bibliothèque différente de celle incluse dans le boM, vous pouvez spécifier la version de dépendance Maven avec la groupId section de dépendance et artifactId dans la section dépendance. Vous pouvez choisir d’avoir des dépendances qui utilisent des versions boM et des dépendances avec des versions substituées dans le même fichier POM de projet, comme illustré dans l’exemple suivant :

<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 vous utilisez cette approche et spécifiez des versions directement dans votre projet, vous pouvez obtenir des conflits de version de dépendance. Ces conflits se produisent, car différents packages peuvent dépendre de différentes versions des dépendances courantes, et ces versions peuvent ne pas être compatibles entre elles. Lorsque des conflits se produisent, vous pouvez rencontrer un comportement indésirable au moment de la compilation ou au moment de l’exécution. Nous vous recommandons de vous appuyer sur les versions qui se trouvent dans le BOM du Kit de développement logiciel (SDK) Azure, sauf si nécessaire. Pour plus d’informations sur la gestion des dépendances lors de l’utilisation du Kit de développement logiciel (SDK) Azure pour Java, consultez Résoudre les conflits de version des dépendances.

Créer une image native avec GraalVM

Vous pouvez utiliser GraalVM pour créer une image native d’une application Java. GraalVM compile le code Java à l’avance dans du code machine natif, ce qui peut générer des gains de performances spectaculaires dans certaines situations. Le Kit de développement logiciel (SDK) Azure pour Java fournit les métadonnées nécessaires dans chacune de ses bibliothèques clientes pour prendre en charge la compilation d’images natives GraalVM.

Pour commencer, vous devez installer GraalVM et préparer votre système de développement pour la compilation d’images natives. Le processus d’installation de GraalVM est simple et la documentation GraalVM fournit des instructions pas à pas pour installer GraalVM et l’utilisation de GraalVM pour installer l’image native. Suivez attentivement la section des prérequis pour installer les compilateurs natifs nécessaires pour votre système d’exploitation.

Le Kit de développement logiciel (SDK) Azure pour Java Maven archétype peut configurer votre build pour prendre en charge la compilation d’images natives GraalVM, mais vous pouvez également l’ajouter à une build Maven existante. Vous trouverez des instructions pour Maven sur le site web GraalVM.

Ensuite, vous êtes prêt à exécuter une build d’image native. Vous pouvez utiliser des outils Maven standard pour utiliser l’image native GraalVM. Pour Maven, utilisez la commande suivante :

mvn clean package -Pnative

Après avoir exécuté cette commande, GraalVM génère un exécutable natif pour la plateforme sur laquelle il s’exécute. L’exécutable apparaît dans le répertoire Maven /target de votre projet. Vous pouvez maintenant exécuter votre application avec ce fichier exécutable, et elle doit s’effectuer de la même façon qu’une application Java standard.

Étapes suivantes

Prise en main des extensions Azure pour IntelliJ et Eclipse