次の方法で共有


Azure SDK と Apache Maven の概要

この記事では、Apache Maven を使用して Azure SDK for Java を使用してアプリケーションをビルドする方法について説明します。 この記事では、Maven を使用して新しいプロジェクトを設定し、Maven でプロジェクトをビルドし、GraalVM ネイティブ イメージ ツールを使用してプラットフォーム固有のネイティブ バイナリを作成します。

Azure SDK for Java プロジェクトには、新しいプロジェクトのブートストラップを高速化できる Maven アーキタイプが含まれています。 Azure SDK for Java Maven アーキタイプは、ベスト プラクティスに従うファイルとディレクトリ構造を使用して、新しいアプリケーションを作成します。 特に、Azure SDK for Java Maven アーキタイプは、次の機能を備えた新しい Maven プロジェクトを作成します。

  • 最新の azure-sdk-bom BOM リリースへの依存関係。これにより、Azure SDK for Java のすべての依存関係が確実に調整され、開発者エクスペリエンスが可能な限り最高になります。
  • GraalVM ネイティブ イメージ コンパイルの組み込みサポート。
  • Java 用 Azure SDK クライアント ライブラリの指定したセットを使用して新しいプロジェクトを生成するためのサポート。
  • Azure SDK for Java ビルド ツールとの統合。これにより、プロジェクトのビルド時分析を行い、多くのベスト プラクティスに従うことができます。

前提 条件

  • Java Developer Kit、バージョン 8 以降。 最適なエクスペリエンスを得るためのバージョン 17 をお勧めします。
  • Apache Maven

新しい Maven プロジェクトを作成する

Azure SDK for Java Maven アーキタイプは Maven Central に発行されます。 つまり、アーキタイプを直接使用して、次のコマンドを使用して新しいアプリケーションをブートストラップできます。

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

このコマンドを入力すると、アーキタイプが適切な出力を生成できるように、プロジェクトに関する詳細を求める一連のプロンプトが表示されます。 次の表では、値を指定する必要があるプロパティについて説明します。

名前 説明
groupId (必須) 生成されるプロジェクトに対して作成される POM ファイルで使用する Maven groupId
artifactId (必須) 生成されるプロジェクトに対して作成される POM ファイルで使用する Maven artifactId
package (省略可能)生成されたコードを格納するパッケージ名。 指定されていない場合は、groupId から推論されます。
azureLibraries (省略可能) Azure SDK for Java のライブラリを Maven アーティファクト ID で示したコンマ区切りのリスト。 このような成果物 ID の一覧については、Azure SDK リリースを参照してください。
enableGraalVM (省略可能) 生成された Maven POM ファイルに GraalVM を使用したネイティブ イメージへのアプリケーションのコンパイルのサポートを含めてはならないことを示す false。それ以外の場合は、trueします。 既定値は trueです。
javaVersion (省略可能)生成されたプロジェクトをビルドするときにターゲットとする JDK の最小バージョン (81117など)。 既定値は、最新の LTS リリース (現在 17) です。 最小値は 8です。
junitVersion (省略可能)依存関係として含める JUnit のバージョン。 既定値は 5です。 有効な値 45

または、前に示した archetype コマンドを呼び出すときに、これらの値を指定することもできます。 この方法は、たとえば自動化の目的で役立ちます。 パラメーター名に -D を追加する標準の Maven 構文を使用して、パラメーターとして値を指定できます。次に例を示します。

-DjavaVersion=17

Java バージョンのサポート

ベスト プラクティスとして、運用環境にデプロイするときは Java LTS リリースを使用する必要があります。 既定では、Azure SDK Maven アーキタイプは、現在 Java 17 ベースラインを設定している最新の LTS リリースを選択します。 ただし、javaVersion パラメーターを設定することで、既定の動作をオーバーライドできます。

Azure SDK for Java ビルド ツールを使用する

Azure SDK for Java プロジェクトには、プロジェクトに含めることができる Maven ビルド ツールが付属しています。 このツールはローカルで実行され、Microsoft にデータを送信しません。 特定の条件が満たされたときにレポートを生成したりビルドを失敗させたりするようにツールを構成できます。これは、次のような多くのベスト プラクティスに確実に準拠するのに役立ちます。

  • 最新バージョンの使用や、Azure SDK for Java クライアント ライブラリでの依存関係バージョンの定義に依存するなど、azure-sdk-for-java BOM の正しい使用の検証。 詳細については、「Azure SDK for Java を既存のプロジェクト に追加する」セクションを参照してください。
  • 新しいバージョンと改善されたバージョンが存在する場合に、履歴の Azure クライアント ライブラリが使用されていないことを検証します。

このレポートでは、ベータ API の使用状況に関する分析情報も提供されます。

次の例に示すように、プロジェクト Maven POM ファイルでビルド ツールを構成できます。 プレースホルダーは、オンラインに記載されている最新バージョン に置き換えてください。

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

ビルド ツールを Maven プロジェクトに追加した後、mvn compile azure:runを呼び出してツールを実行できます。 提供される構成に応じて、ビルドエラーや生成されたレポート ファイルが表示され、潜在的な問題が深刻になる前に通知される可能性があります。 このツールは、CI/CD パイプラインの一部として実行することをお勧めします。 ビルド ツールが進化するにつれて、新しいリリースが公開されます。開発者は、新しいリリース を頻繁に確認し、必要に応じて更新することをお勧めします。

ビルド ツールを構成して、特定の機能を有効または無効にすることができます。 この構成では、前に示した XML に configuration セクションを追加します。 そのセクション内で、次の表に示す設定を構成します。 明示的に説明されていない構成は、テーブルで指定された既定値を受け取ります。

プロパティ名 既定値 説明
validateAzureSdkBomUsed true プロジェクトに azure-sdk-for-java BOM が適切に参照されていることを確認します。これにより、Azure SDK for Java クライアント ライブラリの依存関係が BOM からバージョンを取得できるようになります。
validateLatestBomVersionUsed true 新しい azure-sdk-for-java BOM が存在する場合は、レポートバック (またはビルドの失敗) によって依存関係が最新の状態に保たれるようにします。 あなたはいつでもの最新バージョンをオンラインで見つけることができます
validateBomVersionsAreUsed 本当 azure-sdk-for-java BOMから依存関係を使用できる場合、バージョンが手動でオーバーライドされていないことを確認します。
validateNoDeprecatedMicrosoftLibraryUsed true プロジェクトで前世代の Azure ライブラリが使用されないようにします。 新旧のライブラリを 1 つのプロジェクトで使用しても問題が発生する可能性は低いですが、開発者エクスペリエンスは最適とは言えない結果になります。
validateNoBetaLibraryUsed 偽り 一部の Azure SDK for Java クライアント ライブラリにはベータ リリースがあり、バージョン文字列は x.y.z-beta.n形式です。 この機能を有効にすると、ベータ ライブラリが使用されなくなります。
validateNoBetaApiUsed true Azure SDK for Java クライアント ライブラリには、@Betaで注釈が付けられたメソッドを含む GA リリースがある場合があります。 このチェックでは、そのようなメソッドが使用されているかどうかを確認します。
sendToMicrosoft 本当 テレメトリの目的でビルド レポートを Microsoft に送信するかどうかを指定します。 これは、ドキュメント、サンプル、および便利な API の改善に優先順位を付ける場所について開発チームをガイドするのに役立ちます。 ユーザーを特定できるコンテンツは送信されません。
reportFile - (省略可能)ビルド レポートの書き込み先の場所を JSON 形式で指定します。 指定しない場合、レポートは書き込まれず、ビルドの概要または適切なビルドエラーがターミナルに表示されます。

Azure SDK for Java を既存のプロジェクトに追加する

依存関係のバージョン管理を簡単にするために、Azure SDK for Java チームは、Azure SDK for Java クライアント BOM 毎月発行します。 この BOM ファイルには、互換性のある依存関係バージョンを持つすべての一般公開 (GA) Azure SDK for Java クライアント パッケージが含まれています。

BOM 内にある Azure SDK for Java クライアント ライブラリの依存関係バージョンを使用するには、プロジェクト pom.xml ファイルに次のスニペットを含めます。 プレースホルダーを、Azure SDK for Java BOMの最新リリース に置き換えます。 {artifactId} プレースホルダーを Azure サービス SDK パッケージ名に置き換えます。

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

Azure SDK for Java クライアント BOM のすべてのリリースを azure-sdk-bom で見つけることができます。 最新バージョンを使用して、Azure SDK for Java クライアント ライブラリの最新の機能を利用することをお勧めします。

Maven を使用してプロジェクトの依存関係を定義すると、プロジェクトの管理が簡単になります。 Azure SDK BOM と Azure SDK Maven アーキタイプを使用すると、長期的に依存関係のバージョン管理について自信を持ちながら、プロジェクトを加速できます。 BOM を使用して、依存関係を最新の状態に保つことをお勧めします。

Azure SDK BOM を追加するだけでなく、Azure SDK for Java ビルド ツールも含めてお勧めします。 このツールは、この記事で前述したように、アプリケーションのビルド時に一般的に発生する多くの問題を診断するのに役立ちます。

BOM に含まれていないパッケージを含める

Azure SDK for Java クライアント BOM には、一般公開 (GA) ライブラリのみが含まれています。 ベータ版のパッケージ、または BOM に含まれているバージョンとは異なるライブラリ バージョンに依存する場合は、依存関係セクションの groupIdartifactId と共に Maven 依存関係バージョンを指定できます。 次の例に示すように、BOM バージョンを使用する依存関係と、オーバーライドされたバージョンを持つ依存関係を同じプロジェクト POM ファイルに含めることができます。

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

この方法を使用し、プロジェクトでバージョンを直接指定すると、依存関係のバージョンの競合が発生する可能性があります。 これらの競合は、異なるパッケージが一般的な依存関係の異なるバージョンに依存する可能性があり、これらのバージョンが互いに互換性がない可能性があるために発生します。 競合が発生すると、コンパイル時または実行時に望ましくない動作が発生する可能性があります。 必要な場合を除き、Azure SDK BOM に含まれるバージョンに依存することをお勧めします。 Azure SDK for Java を使用する場合の依存関係の処理の詳細については、「依存関係バージョンの競合のトラブルシューティング」を参照してください。

GraalVM を使用してネイティブ イメージを構築する

GraalVM を使用して、Java アプリケーションのネイティブ イメージを作成できます。 GraalVM は、Java コードを事前にネイティブ コンピューター コードにコンパイルします。これにより、特定の状況でパフォーマンスが大幅に向上する可能性があります。 Azure SDK for Java では、GraalVM ネイティブ イメージのコンパイルをサポートするために、各クライアント ライブラリに必要なメタデータが提供されます。

開始するには、GraalVM をインストールし、ネイティブ イメージをコンパイルするための開発システムを準備する必要があります。 GraalVMのインストールプロセスは簡単で、GraalVMのドキュメントには、GraalVMのインストール とGraalVMを使用したネイティブイメージのインストールの手順が段階的に説明されています。 の前提条件 セクションに注意して従って、オペレーティング システムに必要なネイティブ コンパイラをインストールします。

Azure SDK for Java Maven アーキタイプ では、GraalVM ネイティブ イメージのコンパイルをサポートするようにビルドを構成できますが、既存の Maven ビルドに追加することもできます。 GraalVM ウェブサイトで Maven の手順を見つけることができます。

次に、ネイティブ イメージ ビルドを実行する準備ができました。 標準の Maven ツールを使用して GraalVM ネイティブ イメージを使用できます。 Maven の場合は、次のコマンドを使用します。

mvn clean package -Pnative

このコマンドを実行すると、GraalVM は実行されているプラットフォームのネイティブ実行可能ファイルを出力します。 実行可能ファイルは、プロジェクトの Maven /target ディレクトリに表示されます。 これで、この実行可能ファイルを使用してアプリケーションを実行できるようになり、標準の Java アプリケーションと同様に実行されます。

次の手順