Prise en main du Kit de développement logiciel (SDK) Azure et d’Apache Maven
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 version de
azure-sdk-bomBOM, 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. - Support intégré pour la compilation d'image native 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.
Conditions préalables
- Kit de développement Java, version 8 ou ultérieure. Nous vous recommandons la version 17 pour une expérience optimale.
- Apache Maven
Créer 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 à partir du groupId s'il n'est pas spécifié. |
azureLibraries |
(Facultatif) Liste séparée par des virgules des bibliothèques du kit de développement logiciel (SDK) Azure pour Java, en utilisant leurs identifiants d'artefacts Maven. Pour une liste de tels identifiants d'artefact, veuillez consulter la section Versions Azure SDK. |
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é, tel que 8, 11ou 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 de -D au nom du paramètre, par exemple :
-DjavaVersion=17
Support des versions 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 paramètre javaVersion.
Utilisez l'outil de build du 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-javaBOM, 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 un Kit de développement logiciel (SDK) Azure pour Java à un projet existant section. - 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. Assurez-vous de remplacer le placeholder {latest_version} par la dernière version indiqué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 de vérifier fréquemment les nouvelles versions et de les mettre à jour selon les besoins.
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 section configuration 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é | Valeur par défaut | Description |
|---|---|---|
validateAzureSdkBomUsed |
vrai | S'assure que le projet référence correctement le azure-sdk-for-java BOM, afin que les dépendances de la bibliothèque cliente Azure SDK for Java récupèrent leurs versions à partir du BOM. |
validateLatestBomVersionUsed |
vrai | S'assure que les dépendances restent à jour en signalant (ou en faisant échouer la build) si un azure-sdk-for-java BOM plus récent existe. Vous pouvez toujours trouver la dernière version en ligne. |
validateBomVersionsAreUsed |
vrai | S'assure que, lorsqu'une dépendance est disponible depuis le azure-sdk-for-java BOM, la version n'est pas remplacée manuellement. |
validateNoDeprecatedMicrosoftLibraryUsed |
vrai | 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 |
faux | 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 |
vrai | Le Kit de développement logiciel (SDK) Azure pour les bibliothèques clientes Java dispose parfois de versions en disponibilité générale avec des méthodes annotées avec @Beta. Cette vérification examine si de telles méthodes sont utilisées. |
sendToMicrosoft |
vrai | 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 SDK Azure pour Java publie le SDK Azure pour Java client BOM chaque mois. Ce fichier BOM inclut tous les packages SDK client Azure pour Java en disponibilité générale (GA) 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 de projet pom.xml. Remplacez l’espace réservé {bom_version_to_target} par la dernière version de l'Azure SDK pour Java BOM. Remplacez l’espace réservé {artifactId} 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 le BOM Azure SDK et l'archetype Maven Azure SDK, vous pouvez accélérer votre projet tout en étant plus confiant quant à la gestion des versions de vos 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 paquet qui n'est pas 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 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 de GraalVM fournit des instructions détaillées pour installer GraalVM et utiliser GraalVM pour installer native-image. Suivez attentivement la section des prérequis pour installer les compilateurs natifs nécessaires à votre système d'exploitation.
L'archetype Maven pour Azure SDK for Java peut configurer votre build pour prendre en charge la compilation d'image native GraalVM, mais vous pouvez aussi l'ajouter à un build Maven existant. Vous trouverez des instructions pour maven sur le site web GraalVM.
Ensuite, vous êtes prêt à exécuter la construction d'une 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.