Aan de slag met Azure SDK en Apache Maven

Artikel
01/20/2025

In dit artikel leest u hoe u Apache Maven gebruikt om toepassingen te bouwen met de Azure SDK voor Java. In dit artikel stelt u een nieuw project in met Maven, bouwt u projecten met Maven en gebruikt u de systeemeigen hulpprogramma's voor installatiekopieën van GraalVM om platformspecifieke systeemeigen binaire bestanden te maken.

Het Azure SDK voor Java-project bevat een Maven-archetype waarmee het opstarten van een nieuw project kan worden versneld. Met de Azure SDK voor Java Maven-archetype wordt een nieuwe toepassing gemaakt, met bestanden en een mapstructuur die de aanbevolen procedures volgt. Met name de Azure SDK voor Java Maven-archetype maakt een nieuw Maven-project met de volgende functies:

Een afhankelijkheid van de nieuwste azure-sdk-bom BOM-release, die ervoor zorgt dat alle afhankelijkheden voor Azure SDK voor Java zijn uitgelijnd en u de beste ontwikkelaarservaring biedt.
Ingebouwde ondersteuning voor GraalVM-native image-compilatie.
Ondersteuning voor het genereren van een nieuw project met een opgegeven set Azure SDK voor Java-clientbibliotheken.
Integratie met de Azure SDK voor Java-buildhulpprogramma's, die build-time-analyse van uw project biedt om ervoor te zorgen dat er veel aanbevolen procedures worden gevolgd.

Voorwaarden

Java Developer Kitversie 8 of hoger. We raden versie 17 aan voor de beste ervaring.
Apache Maven

Een nieuw Maven-project maken

De Azure SDK voor Java Maven-archetype wordt gepubliceerd naar Maven Central. Dit betekent dat u het archetype rechtstreeks kunt gebruiken om een nieuwe toepassing te bootstrapen met de volgende opdracht:

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

Nadat u deze opdracht hebt ingevoerd, vraagt een reeks prompts om details over uw project, zodat het archetype de juiste uitvoer voor u kan genereren. In de volgende tabel worden de eigenschappen beschreven waarvoor u waarden moet opgeven:

Naam	Beschrijving
`groupId`	(Vereist) De Maven `groupId` te gebruiken in het POM-bestand dat is gemaakt voor het gegenereerde project.
`artifactId`	(Vereist) Maven `artifactId` te gebruiken in het POM-bestand dat is gemaakt voor het gegenereerde project.
`package`	(Optioneel) De pakketnaam waar de gegenereerde code in moet worden geplaatst. Afgeleid uit de `groupId` indien niet specifiek vermeld.
`azureLibraries`	(Optioneel) Een door komma's gescheiden lijst met Azure SDK voor Java-bibliotheken met behulp van hun Maven-artefact-id's. Zie Azure SDK-releasesvoor een lijst met dergelijke artefact-id's.
`enableGraalVM`	(Optioneel) `false` om aan te geven dat het gegenereerde Maven POM-bestand geen ondersteuning moet bevatten voor het compileren van uw toepassing naar een naieve afbeelding met behulp van GraalVM; anders: `true`. De standaardwaarde is `true`.
`javaVersion`	(Optioneel) De minimale versie van de JDK die moet worden gebruikt bij het bouwen van het gegenereerde project, zoals `8`, `11`of `17`. De standaardwaarde is de nieuwste LTS-release (momenteel `17`). De minimumwaarde is `8`.
`junitVersion`	(Optioneel) De versie van JUnit die moet worden opgenomen als een afhankelijkheid. De standaardwaarde is `5`. Geldige waarden `4` en `5`.

U kunt deze waarden ook opgeven wanneer u de eerder weergegeven archetypeopdracht aanroept. Deze benadering is bijvoorbeeld handig voor automatiseringsdoeleinden. U kunt de waarden opgeven als parameters met behulp van de standaard-Maven-syntaxis voor het toevoegen van -D aan de parameternaam, bijvoorbeeld:

-DjavaVersion=17

Ondersteuning voor Java-versies

Als best practice moet u een Java LTS-release gebruiken bij het implementeren in productie. Standaard selecteert het Azure SDK Maven-archetype de nieuwste LTS-release, waarmee momenteel een Java 17-basislijn wordt ingesteld. U kunt het standaardgedrag echter overschrijven door de parameter javaVersion in te stellen.

Het hulpprogramma Azure SDK voor Java-build gebruiken

Met de Azure SDK voor Java-project wordt een Maven-buildhulpprogramma geleverd dat u in uw projecten kunt opnemen. Dit hulpprogramma wordt lokaal uitgevoerd en verzendt geen gegevens naar Microsoft. U kunt het hulpprogramma configureren om een rapport te genereren of de build te laten mislukken wanneer aan specifieke voorwaarden is voldaan, wat handig is om te zorgen voor naleving van talloze aanbevolen procedures, zoals de volgende procedures:

Validatie van het juiste gebruik van de azure-sdk-for-java BOM, inclusief het gebruik van de nieuwste versie en het vertrouwen erop om afhankelijkheidsversies te definiëren in Azure SDK voor Java-clientbibliotheken. Zie de sectie Azure SDK voor Java toevoegen aan een bestaand project voor meer informatie.
Validatie dat historische Azure-clientbibliotheken niet worden gebruikt wanneer er nieuwere en verbeterde versies bestaan.

Het rapport biedt ook inzicht in het gebruik van bèta-API's.

U kunt het buildhulpprogramma configureren in een Maven POM-bestand van een project, zoals wordt weergegeven in het volgende voorbeeld. Zorg ervoor dat je de tijdelijke aanduiding {latest_version} vervangt door de meest recente versie die online wordt vermeld.

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

Nadat u het buildhulpprogramma hebt toegevoegd aan een Maven-project, kunt u het hulpprogramma uitvoeren door mvn compile azure:runaan te roepen. Afhankelijk van de opgegeven configuratie kunt u verwachten dat er buildfouten optreden of rapportbestanden die u kunnen informeren over mogelijke problemen voordat ze ernstiger worden. U wordt aangeraden dit hulpprogramma uit te voeren als onderdeel van uw CI/CD-pijplijn. Naarmate het buildhulpprogramma zich ontwikkelt, publiceren we nieuwe releases en raden we ontwikkelaars aan regelmatig te controleren op nieuwe releases en naar behoren bij te werken.

Het is mogelijk om het buildhulpprogramma te configureren om bepaalde functies in of uit te schakelen. Voeg voor deze configuratie een configuration sectie toe in de XML die eerder is weergegeven. Configureer in die sectie de instellingen die worden weergegeven in de volgende tabel. Elke configuratie die niet expliciet wordt vermeld, gebruikt de standaardwaarde die is opgegeven in de tabel.

Naam van eigenschap	Standaardwaarde	Beschrijving
`validateAzureSdkBomUsed`	waar	Zorgt ervoor dat in het project op de juiste manier wordt verwezen naar de azure-sdk-for-java BOM, zodat afhankelijkheden van de Azure SDK-clientbibliotheken voor Java hun versies uit de BOM kunnen halen.
`validateLatestBomVersionUsed`	waar	Zorgt ervoor dat afhankelijkheden up-to-date blijven door te rapporteren (of het bouwen mislukt) als er een nieuwere azure-sdk-for-java BOM bestaat. U vindt altijd de nieuwste versie online.
`validateBomVersionsAreUsed`	waar	Hiermee zorgt u ervoor dat, wanneer een afhankelijkheid beschikbaar is vanuit de azure-sdk-for-java BOM, de versie niet handmatig wordt overschreven.
`validateNoDeprecatedMicrosoftLibraryUsed`	waar	Zorgt ervoor dat het project geen gebruik maakt van Azure-bibliotheken van de vorige generatie. Het is onwaarschijnlijk dat het gebruik van de nieuwe en vorige generatie bibliotheken in één project een probleem veroorzaakt, maar resulteert in een suboptimale ontwikkelaarservaring.
`validateNoBetaLibraryUsed`	vals	Sommige Azure SDK voor Java-clientbibliotheken hebben bètaversies, met versietekenreeksen in de vorm `x.y.z-beta.n`. Als u deze functie inschakelt, zorgt u ervoor dat er geen bètabibliotheken worden gebruikt.
`validateNoBetaApiUsed`	waar	Azure SDK voor Java-clientbibliotheken hebben soms GA-releases met methoden die voorzien zijn van de aantekening `@Beta`. Met deze controle wordt gecontroleerd of dergelijke methoden worden gebruikt.
`sendToMicrosoft`	waar	Hiermee geeft u op of het buildrapport naar Microsoft moet worden verzonden voor telemetriedoeleinden. Dit helpt het ontwikkelteam te helpen bij het prioriteren van documentatie, voorbeelden en verbeterde api's voor gemak. Er wordt geen door de gebruiker identificeerbare inhoud verzonden.
`reportFile`	-	(Optioneel) Hiermee geeft u de locatie op waar het buildrapport naar moet worden geschreven, in JSON-indeling. Als dit niet is opgegeven, wordt er geen rapport geschreven en wordt er een samenvatting van de build of de juiste buildfouten weergegeven in de terminal.

Azure SDK voor Java toevoegen aan een bestaand project

Om versiebeheer van afhankelijkheden eenvoudiger te maken, publiceert het Azure SDK voor Java-team de Azure SDK voor Java-client-BOM elke maand. Dit BOM-bestand bevat alle Algemeen beschikbare Azure SDK voor Java-clientpakketten met hun compatibele afhankelijkheidsversie.

Gebruik afhankelijkheidsversies voor een Azure SDK voor Java-clientbibliotheek die in de BOM staat en neem het volgende codefragment op in het projectbestand pom.xml. Vervang de tijdelijke aanduiding {bom_version_to_target} door de nieuwste versie van de Azure SDK voor Java BOM. Vervang de tijdelijke aanduiding {artifactId} door de naam van het Azure Service SDK-pakket.

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

U vindt alle releases van de Azure SDK voor Java-client BOM op azure-sdk-bom. U wordt aangeraden de nieuwste versie te gebruiken om te profiteren van de nieuwste functies van de Azure SDK voor Java-clientbibliotheken.

Door Maven te gebruiken om projectafhankelijkheden te definiëren, kunt u het beheer van uw projecten eenvoudiger maken. Met de Azure SDK BOM en Azure SDK Maven-archetype kunt u uw project versnellen terwijl u meer vertrouwen hebt in uw versiebeheer op de lange termijn. Wij raden aan de BOM te gebruiken om afhankelijkheden op elkaar af te stemmen en up-to-date te houden.

Naast het toevoegen van de Azure SDK BOM, raden we ook aan om het Azure SDK buildtool voor Java toe te voegen. Dit hulpprogramma helpt bij het vaststellen van veel problemen die vaak optreden bij het bouwen van toepassingen, zoals eerder beschreven in dit artikel.

Een pakket opnemen dat niet op de stuklijst staat

De BOM van de Azure SDK voor Java-client bevat alleen algemeen beschikbare (GA)-bibliotheken. Als u afhankelijk wilt zijn van een pakket dat nog in de bèta is of een bibliotheekversie die verschilt van degene die is opgenomen in de BOM, kunt u de Maven-afhankelijkheidsversie opgeven, samen met de groupId en artifactId in de sectie voor afhankelijkheden. U kunt ervoor kiezen om afhankelijkheden te hebben die gebruikmaken van BOM-versies en -afhankelijkheden met overschreven versies in hetzelfde project POM-bestand, zoals wordt weergegeven in het volgende voorbeeld:

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

Als u deze methode gebruikt en versies rechtstreeks in uw project opgeeft, kunnen er conflicten optreden met de versie van afhankelijkheden. Deze conflicten ontstaan omdat verschillende pakketten mogelijk afhankelijk zijn van verschillende versies van algemene afhankelijkheden en deze versies mogelijk niet compatibel zijn met elkaar. Wanneer er conflicten optreden, kunt u ongewenst gedrag ervaren tijdens het compileren of runtime. We raden u aan om te vertrouwen op versies die zich in de Azure SDK-BOM bevinden, tenzij dat nodig is. Zie Problemen met afhankelijkheidsversies oplossenvoor meer informatie over het omgaan met afhankelijkheden wanneer u de Azure SDK voor Java gebruikt.

Een systeemeigen afbeelding bouwen met GraalVM

U kunt GraalVM gebruiken om een naieve afbeelding van een Java-toepassing te maken. GraalVM compileert de Java-code van tevoren in systeemeigen machinecode, wat in bepaalde situaties drastische prestatieverbeteringen kan opleveren. De Azure SDK voor Java biedt de benodigde metadata in elk van zijn clientbibliotheken ter ondersteuning van GraalVM native image compilatie.

Om aan de slag te gaan, moet u GraalVM installeren en uw ontwikkelingssysteem voorbereiden voor het compileren van native afbeeldingen. Het installatieproces voor GraalVM is eenvoudig en de GraalVM-documentatie bevat stapsgewijze instructies voor het installeren van GraalVM en het gebruik van GraalVM om native-image te installeren. Volg de vereisten sectie zorgvuldig om de benodigde systeemeigen compilers voor uw besturingssysteem te installeren.

Het Azure SDK voor Java Maven archetype kan uw build configureren ter ondersteuning van GraalVM systeemeigen afbeelding compilatie, maar u kunt het ook toevoegen aan een bestaande Maven-build. U vindt instructies voor Maven op de website van GraalVM.

Vervolgens kunt u een systeemeigen afbeelding bouwen. U kunt standaard Maven-hulpprogramma's gebruiken om GraalVM native images te gebruiken. Gebruik voor Maven de volgende opdracht:

mvn clean package -Pnative

Nadat u deze opdracht hebt uitgevoerd, voert GraalVM een systeemeigen uitvoerbaar bestand uit voor het platform waarop deze wordt uitgevoerd. Het uitvoerbare bestand wordt weergegeven in de Maven-/target map van uw project. U kunt uw toepassing nu uitvoeren met dit uitvoerbare bestand en moet op dezelfde manier worden uitgevoerd als een standaard Java-toepassing.

Volgende stappen

Aan de slag met Azure-extensies voor IntelliJ en Eclipse

Delen via