Erste Schritte mit Azure SDK und Apache Maven

  • Artikel

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 für Java ausgerichtet sind, und bietet Ihnen die bestmögliche Entwicklererfahrung.
  • Integrierte Unterstützung für die native GraalVM-Imagekompilierung.
  • Unterstützung für das Generieren eines neuen Projekts mit einer bestimmten Gruppe von Azure SDK für Java-Clientbibliotheken.
  • Integration in das Azure SDK für Java-Buildtools, die eine Buildzeitanalyse Ihres Projekts ermöglicht, um sicherzustellen, dass viele bewährte Methoden befolgt werden.

Voraussetzungen

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) Die Maven groupId , die in der POM-Datei verwendet werden soll, die für das generierte Projekt erstellt wurde.
artifactId (Erforderlich) Die Maven artifactId , die in der POM-Datei verwendet werden soll, die für das generierte Projekt erstellt wurde.
package (Optional) Der Paketname, in den der generierte Code eingefügt werden soll. Abgeleitet von dem groupId , wenn er nicht angegeben ist.
azureLibraries (Optional) Eine durch Trennzeichen getrennte Liste des Azure SDK für Java-Bibliotheken mit ihren Maven-Artefakt-IDs. Eine Liste dieser Artefakt-IDs finden Sie unter Azure SDK-Versionen.
enableGraalVM (Optional) false , um anzugeben, dass die generierte Maven POM-Datei keine Unterstützung für die Kompilierung Ihrer Anwendung auf ein systemeigenes Bild mit GraalVM enthalten sollte; andernfalls "true". Der Standardwert lautet true.
javaVersion (Optional) Die Mindestversion des JDK, das 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 Mindestwert ist 8.
junitVersion (Optional) Die Version von JUnit, die als Abhängigkeit eingeschlossen 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 Maven-Standardsyntax des Anfügens -D an den Parameternamen verwenden, z. B.:

-DjavaVersion=17

Unterstützung von Java-Versionen

Als bewährte Methode sollten Sie beim Bereitstellen in der Produktion eine Java LTS-Version verwenden. Standardmäßig wählt der Azure SDK Maven Archetype die neueste LTS-Version aus, die derzeit einen Java 17-Basisplan festlegt. Sie können das Standardverhalten jedoch überschreiben, indem Sie den javaVersion Parameter festlegen.

Verwenden des Azure SDK für Java-Buildtools

Das Azure SDK für Java-Projekt enthält ein Maven-Buildtool, 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:

  • Überprüfung der richtigen Verwendung der azure-sdk-for-java BOM, einschließlich der Verwendung der neuesten Version, und verwenden Sie sie, um Abhängigkeitsversionen von Azure SDK für Java-Clientbibliotheken zu definieren. Weitere Informationen finden Sie im Abschnitt zum Hinzufügen von Azure SDK für Java zu einem vorhandenen Projektabschnitt .
  • Ü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. Achten Sie darauf, den {latest_version} Platzhalter durch die neueste Onlineversion zu 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 das Tool aufrufen mvn compile azure:run. Abhängig von der bereitgestellten Konfiguration können Sie davon ausgehen, dass Buildfehler oder generierte Dateien gemeldet werden, die Sie über potenzielle Probleme informieren können, bevor sie schwerwiegender werden. Es wird empfohlen, dieses Tool als Teil Ihrer CI/CD-Pipeline auszuführen. Während sich das Buildtool weiterentwickelt, veröffentlichen wir neue Versionen, und es wird empfohlen, dass Entwickler häufig nach neuen Versionen suchen und entsprechend 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 Konfiguration, die nicht explizit Erwähnung ed ist, verwendet den in der Tabelle angegebenen Standardwert.

Name der Eigenschaft Standardwert Beschreibung
validateAzureSdkBomUsed true Stellt sicher, dass das Projekt über das azure-sdk-for-java BOM verfügt, auf das entsprechend verwiesen wird, damit Azure SDK für Java-Clientbibliotheksabhängigkeiten ihre Versionen von der BOM übernehmen können.
validateLatestBomVersionUsed true Stellt sicher, dass Abhängigkeiten auf dem neuesten Stand gehalten werden, indem sie den Build zurückmelden (oder fehlschlagen), wenn ein neuerer azure-sdk-for-java BOM vorhanden ist. Sie finden immer die neueste Version online.
validateBomVersionsAreUsed true Stellt sicher, dass, wenn eine Abhängigkeit aus dem azure-sdk-for-java BOM verfügbar ist, die Version nicht manuell außer Kraft gesetzt 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 im Formular x.y.z-beta.n. Durch aktivieren dieses Feature wird sichergestellt, dass keine Betabibliotheken verwendet werden.
validateNoBetaApiUsed true Azure SDK für Java-Clientbibliotheken verfügen manchmal über GA-Versionen mit Methoden, die mit @BetaAnmerkungen versehen 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, in den der Buildbericht im JSON-Format geschrieben werden soll. Wenn nicht angegeben, wird kein Bericht geschrieben, und eine Zusammenfassung des Builds oder die entsprechenden Buildfehler werden im Terminal 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 jeden Monat das Azure SDK für Java-Client-BOM . Diese BOM-Datei enthält alle allgemein verfügbaren Azure SDK für Java-Clientpakete mit ihrer kompatiblen Abhängigkeitsversion.

Wenn Sie Abhängigkeitsversionen für ein Azure SDK für Java-Clientbibliothek verwenden möchten, die sich in der BOM befindet, fügen Sie den folgenden Codeausschnitt in die Datei "project pom.xml " ein. Ersetzen Sie den {bom_version_to_target} Platzhalter durch die neueste Version des Azure SDK für Java BOM. Ersetzen Sie den {artifactId} Platzhalter durch den Namen des Azure Service SDK-Pakets.

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

Alle Versionen des Azure SDK für Java-Client-BOM finden Sie 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 dem Azure SDK BOM und dem Azure SDK Maven Archetype können Sie Ihr Projekt beschleunigen und gleichzeitig auf die langfristige Versionsverwaltung ihrer Abhängigkeit vertrauen. Es wird empfohlen, die BOM zu verwenden, um Abhängigkeiten auf dem neuesten Stand zu halten.

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

Einschließen eines Pakets, 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 Betaversion oder in einer Bibliotheksversion befindet, die nicht in der BOM enthalten ist, können Sie die Maven-Abhängigkeitsversion zusammen mit dem groupId Und artifactId im Abhängigkeitsabschnitt angeben. Sie können abhängigkeiten haben, die BOM-Versionen und Abhängigkeiten mit überschriebenen Versionen in derselben PROJEKT-POM-Datei verwenden, 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 Versionen direkt in Ihrem Projekt angeben, erhalten Sie möglicherweise Abhängigkeitsversionskonflikte. 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, können Bei der Kompilierungszeit oder Laufzeit unerwünschtes Verhalten auftreten. 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.

Erstellen eines nativen Images mit GraalVM

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 einfach, und die GraalVM-Dokumentation enthält schrittweise Anleitungen für die Installation von GraalVM und die Verwendung von GraalVM zum Installieren von nativem Image. Befolgen Sie den Abschnitt "Voraussetzungen " sorgfältig, um die erforderlichen systemeigenen Compiler für Ihr Betriebssystem zu installieren.

Das Azure SDK für Java Maven Archetype kann Ihren Build so konfigurieren, dass die native Imagekompilierung von GraalVM unterstützt wird, Sie können ihn aber auch zu einem vorhandenen Maven-Build hinzufügen. Anweisungen für Maven finden Sie auf der GraalVM-Website.

Als Nächstes können Sie einen nativen Imagebuild ausführen. Sie können standardmäßige Maven-Tools verwenden, um graalVM natives 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 systemeigene ausführbare Datei für die Plattform aus, auf der sie ausgeführt wird. Die ausführbare Datei wird im Maven /target-Verzeichnis 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