Erste Schritte mit Azure SDK und Apache Maven

Artikel
01/22/2025

In diesem Artikel erfahren Sie, wie Sie Apache Maven zum Erstellen von Anwendungen mit dem Azure SDK für Java verwenden. In diesem Artikel richten Sie ein neues Projekt mit Maven ein, erstellen Projekte mit Maven und verwenden die nativen GraalVM-Imagetools, um plattformspezifische native Binärdateien zu erstellen.

Das Azure SDK für Java-Projekt enthält einen Maven-Archetyp, der das Bootstrapping eines neuen Projekts beschleunigen kann. Das Azure SDK für Java Maven Archetype erstellt eine neue Anwendung mit Dateien und einer Verzeichnisstruktur, die bewährte Methoden befolgt. Insbesondere erstellt das Azure SDK für Java Maven Archetype ein neues Maven-Projekt mit den folgenden Features:

Eine Abhängigkeit von der neuesten azure-sdk-bom-BOM-Version, die sicherstellt, dass alle Abhängigkeiten für Azure SDK for Java aufeinander abgestimmt sind, und Ihnen die bestmögliche Erfahrung für Entwickler bietet.
Integrierte Unterstützung für die Kompilierung nativer Images von GraalVM.
Unterstützung für das Generieren eines neuen Projekts mit einer bestimmten Gruppe von Azure SDK für Java-Clientbibliotheken.
Integration mit dem Azure SDK für Java-Build-Tools, die eine Analyse Ihres Projekts zur Buildzeit ermöglicht, um sicherzustellen, dass viele bewährte Methoden eingehalten werden.

Voraussetzungen

Java Developer Kit, Version 8 oder höher. Wir empfehlen Version 17, um die beste Erfahrung zu erzielen.
Apache Maven

Erstellen eines neuen Maven-Projekts

Das Azure SDK für Java Maven Archetype wird in Maven Central veröffentlicht. Das bedeutet, dass Sie den Archetyp direkt verwenden können, um eine neue Anwendung mit dem folgenden Befehl zu bootstrapieren:

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

Nachdem Sie diesen Befehl eingegeben haben, werden in einer Reihe von Eingabeaufforderungen Details zu Ihrem Projekt angefordert, damit der Archetyp die richtige Ausgabe für Sie generieren kann. In der folgenden Tabelle werden die Eigenschaften beschrieben, für die Sie Werte bereitstellen müssen:

Name	Beschreibung
`groupId`	(Erforderlich) Das Maven `groupId`, das in der für das generierte Projekt erstellten POM-Datei verwendet werden soll.
`artifactId`	(Erforderlich) Das Maven `artifactId`, das in der für das generierte Projekt erstellten POM-Datei verwendet werden soll.
`package`	(Optional) Der Paketname, in den der generierte Code eingefügt werden soll. Wird von `groupId` abgeleitet, wenn nicht angegeben.
`azureLibraries`	(Optional) Eine durch Komma getrennte Liste von Azure SDK for Java-Bibliotheken unter Verwendung ihrer Maven Artefakt-IDs. Eine Liste solcher Artefakt-IDs finden Sie unter Azure SDK Releases.
`enableGraalVM`	(Optional) `false` um anzugeben, dass die generierte Maven POM-Datei keine Unterstützung für die Kompilierung Ihrer Anwendung in ein natives Image mit GraalVM enthalten soll; andernfalls `true`. Der Standardwert ist `true`.
`javaVersion`	(Optional) Die Mindestversion des JDK, die beim Erstellen des generierten Projekts als Ziel festgelegt werden soll, z. B. `8`, `11`oder `17`. Der Standardwert ist die neueste LTS-Version (derzeit `17`). Der Minimalwert ist `8`.
`junitVersion`	(Optional) Die Version von JUnit, die als Abhängigkeit eingebunden werden soll. Der Standardwert ist `5`. Gültige Werte `4` und `5`.

Alternativ können Sie diese Werte angeben, wenn Sie den zuvor gezeigten Archetypbefehl aufrufen. Dieser Ansatz ist z. B. für Automatisierungszwecke nützlich. Sie können die Werte als Parameter angeben, indem Sie die standardmäßige Maven-Syntax verwenden, um -D an den Parameternamen anzufügen, z. B.:

-DjavaVersion=17

Unterstützung für Java-Versionen

Als bewährte Praxis sollten Sie beim Bereitstellen in der Produktionsumgebung eine Java LTS-Version verwenden. Standardmäßig wählt der Azure SDK Maven Archetyp die neueste LTS-Version aus, die derzeit einen Java 17-Standard festlegt. Sie können das Standardverhalten jedoch außer Kraft setzen, indem Sie den javaVersion-Parameter festlegen.

Verwenden des Azure SDK für Java-Buildtools

Das Azure SDK für das Java-Projekt bietet das Build-Tool Maven, das Sie in Ihre Projekte einbeziehen können. Dieses Tool wird lokal ausgeführt und überträgt keine Daten an Microsoft. Sie können das Tool so konfigurieren, dass ein Bericht generiert wird oder der Build fehlschlägt, wenn bestimmte Bedingungen erfüllt sind. Dies ist nützlich, um die Einhaltung zahlreicher bewährter Methoden wie die folgenden Methoden sicherzustellen:

Validierung der korrekten Verwendung der azure-sdk-for-java-BOM, einschließlich der Verwendung der neuesten Version und der Festlegung von Abhängigkeitsversionen auf Azure SDK für Java Client-Bibliotheken. Weitere Informationen finden Sie im Abschnitt Hinzufügen von Azure SDK für Java zu einem vorhandenen Projekt.
Überprüfung, dass historische Azure-Clientbibliotheken nicht verwendet werden, wenn neuere und verbesserte Versionen vorhanden sind.

Der Bericht bietet auch Einblicke in die Verwendung von Beta-APIs.

Sie können das Buildtool in einer Maven POM-Projektdatei konfigurieren, wie im folgenden Beispiel gezeigt. Stellen Sie sicher, dass Sie den {latest_version}-Platzhalter durch die neueste online aufgelistete Version ersetzen.

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

Nachdem Sie das Buildtool zu einem Maven-Projekt hinzugefügt haben, können Sie das Tool ausführen, indem Sie mvn compile azure:runaufrufen. Abhängig von der bereitgestellten Konfiguration können Sie damit rechnen, dass entweder Buildfehler auftreten oder Berichtsdateien generiert werden, die Sie über potenzielle Probleme informieren können, bevor diese gravierender werden. Wir empfehlen, dass Sie dieses Tool als Element Ihrer CI/CD-Pipeline ausführen. Da das Tool weiterentwickelt wird, werden wir neue Versionen veröffentlichen. Wir empfehlen Entwicklern, häufig nach neuen Versionen zu suchen und ggf. zu aktualisieren.

Es ist möglich, das Buildtool so zu konfigurieren, dass bestimmte Features aktiviert oder deaktiviert werden. Fügen Sie für diese Konfiguration einen configuration Abschnitt im zuvor gezeigten XML-Code hinzu. Konfigurieren Sie in diesem Abschnitt die einstellungen, die in der folgenden Tabelle angezeigt werden. Jede nicht explizit erwähnte Konfiguration verwendet den in der Tabelle angegebenen Standardwert.

Eigenschaftenname	Standardwert	Beschreibung
`validateAzureSdkBomUsed`	true	Stellt sicher, dass das Projekt die azure-sdk-for-java-BOM entsprechend referenziert, sodass Azure SDK for Java Client-Bibliotheksabhängigkeiten ihre Versionen aus der BOM beziehen können.
`validateLatestBomVersionUsed`	true	Stellt sicher, dass die Abhängigkeiten auf dem neuesten Stand gehalten werden, indem es zurückmeldet (oder den Build fehlschlägt), wenn eine neuere azure-sdk-for-java-BOM existiert. Sie können die neueste Version immer online finden.
`validateBomVersionsAreUsed`	true	Stellt sicher, dass in Fällen, in denen eine Abhängigkeit von der azure-sdk-for-java BOM verfügbar ist, die Version nicht manuell überschrieben wird.
`validateNoDeprecatedMicrosoftLibraryUsed`	true	Stellt sicher, dass das Projekt keine Azure-Bibliotheken der vorherigen Generation verwendet. Die Verwendung der bibliotheken der neuen und der vorherigen Generation in einem einzigen Projekt ist unwahrscheinlich, dass sie ein Problem verursachen, führt jedoch zu einer suboptimalen Entwicklererfahrung.
`validateNoBetaLibraryUsed`	false	Einige Azure SDK für Java-Clientbibliotheken verfügen über Betaversionen mit Versionszeichenfolgen in form `x.y.z-beta.n`. Durch aktivieren dieses Feature wird sichergestellt, dass keine Betabibliotheken verwendet werden.
`validateNoBetaApiUsed`	true	Azure SDK für Java Client-Bibliotheken haben manchmal AV-Versionen mit Methoden, die mit `@Beta` angemerkt sind. Bei dieser Überprüfung wird überprüft, ob solche Methoden verwendet werden.
`sendToMicrosoft`	true	Gibt an, ob der Buildbericht zu Telemetriezwecken an Microsoft gesendet werden soll. Auf diese Weise können Sie das Entwicklungsteam bei der Priorisierung von Dokumentation, Beispielen und verbesserten Komfort-APIs unterstützen. Es werden keine benutzeridentifizierbaren Inhalte übermittelt.
`reportFile`	-	(Optional) Gibt den Speicherort an, an den der Build-Bericht im JSON-Format geliefert werden soll. Wenn nicht angegeben, wird kein Bericht geschrieben, und im Terminal wird eine Zusammenfassung des Builds oder der entsprechenden Buildfehler angezeigt.

Hinzufügen des Azure SDK für Java zu einem vorhandenen Projekt

Um die Verwaltung von Abhängigkeitsversionen zu vereinfachen, veröffentlicht das Azure SDK für Java-Team das Azure SDK für Java-Client-BOM jeden Monat. Diese BOM-Datei enthält alle allgemein verfügbaren (GA) Azure SDK for Java Client-Pakete mit ihrer kompatiblen Abhängigkeitsversion.

Wenn Sie Abhängigkeitsversionen für eine Azure SDK für Java-Clientbibliothek verwenden möchten, die sich im BOM befindet, fügen Sie den folgenden Codeausschnitt in die Projektdatei pom.xml ein. Ersetzen Sie den {bom_version_to_target}-Platzhalter durch die neueste Version der Azure SDK for Java-BOM. Ersetzen Sie den {artifactId} Platzhalter durch den Azure-Service-SDK-Paketnamen.

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

Sie finden alle Versionen der Azure SDK for Java Client-BOM unter azure-sdk-bom. Es wird empfohlen, die neueste Version zu verwenden, um die neuesten Features des Azure SDK für Java-Clientbibliotheken zu nutzen.

Die Verwendung von Maven zum Definieren von Projektabhängigkeiten kann die Verwaltung Ihrer Projekte vereinfachen. Mit der Azure SDK-BOM und dem Azure SDK Maven-Archetyp können Sie Ihr Projekt beschleunigen und sich gleichzeitig langfristig auf die Versionsverwaltung Ihrer Abhängigkeiten verlassen. Wir empfehlen die Verwendung der BOM, um die Abhängigkeiten aufeinander abzustimmen und auf dem neuesten Stand zu halten.

Zusätzlich zum Hinzufügen der Azure SDK-BOM empfehlen wir, auch das Azure SDK for Java Build-Tool einzubeziehen. Dieses Tool hilft ihnen, viele Probleme zu diagnostizieren, die beim Erstellen von Anwendungen häufig auftreten, wie zuvor in diesem Artikel beschrieben.

Ein Paket einbeziehen, das nicht in der BOM enthalten ist

Das Azure SDK für Java-Client-BOM enthält nur Allgemein verfügbare (GA)-Bibliotheken. Wenn Sie von einem Paket abhängig sein möchten, das sich noch in der Beta-Phase befindet, oder von einer Bibliotheksversion, die sich von der in der BOM enthaltenen Version unterscheidet, können Sie die Maven-Abhängigkeitsversion zusammen mit groupId und artifactId im Abhängigkeitsabschnitt angeben. Sie können wählen, ob Sie Abhängigkeiten, die BOM-Versionen verwenden, und Abhängigkeiten mit überschriebenen Versionen in der gleichen Projekt-POM-Datei haben möchten, wie im folgenden Beispiel gezeigt:

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

Wenn Sie diesen Ansatz verwenden und die Versionen direkt in Ihrem Projekt angeben, kann es zu Versionskonflikten in den Abhängigkeiten kommen. Diese Konflikte treten auf, da unterschiedliche Pakete möglicherweise von verschiedenen Versionen gemeinsamer Abhängigkeiten abhängen, und diese Versionen sind möglicherweise nicht miteinander kompatibel. Wenn Konflikte auftreten, kann es zu unerwünschtem Verhalten bei der Kompilierung oder zur Laufzeit kommen. Es wird empfohlen, dass Sie sich auf Versionen verlassen, die sich im Azure SDK-BOM befinden, es sei denn, dies ist erforderlich. Weitere Informationen zum Umgang mit Abhängigkeiten bei Verwendung des Azure SDK für Java finden Sie unter Problembehandlung bei Abhängigkeitsversionskonflikten.

Ein natives Image mit GraalVM erstellen

Sie können GraalVM verwenden, um ein systemeigenes Image einer Java-Anwendung zu erstellen. GraalVM kompiliert den Java-Code vorab in systemeigenen Computercode, was zu drastischen Leistungsgewinnen in bestimmten Situationen führen kann. Das Azure SDK für Java stellt die erforderlichen Metadaten in den einzelnen Clientbibliotheken zur Unterstützung der nativen GraalVM-Imagekompilierung bereit.

Um zu beginnen, müssen Sie GraalVM installieren und Ihr Entwicklungssystem für die Kompilierung nativer Images vorbereiten. Der Installationsprozess für GraalVM ist unkompliziert und die GraalVM-Dokumentation bietet eine schrittweise Anleitung für die Installation von GraalVM und die Verwendung von GraalVM zur Installation von Native-Image. Befolgen Sie den Abschnitt Voraussetzungen sorgfältig, um die notwendigen nativen Compiler für Ihr Betriebssystem zu installieren.

Mit dem Azure SDK für Java Maven-Archetyp können Sie Ihren Build so konfigurieren, dass er die native Image-Kompilierung von GraalVM unterstützt, aber Sie können ihn auch zu einem bestehenden Maven-Build hinzufügen. Anweisungen zu Maven finden Sie auf der GraalVM-Website.

Als nächstes sind Sie bereit, einen nativen Image-Build auszuführen. Sie können standardmäßige Maven-Tools verwenden, um GraalVM Native Image zu verwenden. Verwenden Sie für Maven den folgenden Befehl:

mvn clean package -Pnative

Nachdem Sie diesen Befehl ausgeführt haben, gibt GraalVM eine native ausführbare Datei für die Plattform aus, auf der es ausgeführt wird. Die ausführbare Datei wird im Verzeichnis "Maven /target" Ihres Projekts angezeigt. Sie können Ihre Anwendung jetzt mit dieser ausführbaren Datei ausführen, und sie sollte ähnlich wie eine Standard-Java-Anwendung ausgeführt werden.

Nächste Schritte

Erste Schritte mit Azure-Erweiterungen für IntelliJ und Eclipse

Freigeben über