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-bomBOMリリースへの依存関係により、Azure SDK for Java のすべての依存関係が調整され、可能な限り最高の開発者エクスペリエンスが提供されます。 - GraalVM ネイティブ イメージのコンパイルの組み込みサポート。
- 指定された Azure SDK for Java クライアント ライブラリのセットを使用して、新しいプロジェクトを生成するためのサポート。
- 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 |
(省略可能) Maven 成果物 ID を使用した、Azure SDK for Java ライブラリのコンマ区切りのリスト。 このような成果物 ID の一覧については、「Azure SDK のリリース」を参照してください。 |
enableGraalVM |
(省略可能) GraalVM を使用してアプリケーションをネイティブ イメージにコンパイルするためのサポートを、生成された Maven POM ファイルに含めないことを示す場合は false。それ以外の場合は true。 既定値は true です。 |
javaVersion |
(省略可能) 生成されたプロジェクトをビルドするときにターゲットとする JDK の最小バージョン (8、11、17 など)。 既定値は最新の LTS リリースです (現在は 17)。 最小値は 8 です。 |
junitVersion |
(省略可能) 依存関係として含める JUnit のバージョン。 既定値は 5 です。 有効な値は 4 および 5 です。 |
または、前に示したように、archetype コマンドを呼び出すときにこれらの値を指定することもできます。 この方法は、たとえば、自動化の場合に便利です。 標準的な Maven 構文を使用して、-D をパラメーター名に追加することで、値をパラメーターとして指定できます。次に例を示します。
-DjavaVersion=17
Java バージョンのサポート
ベスト プラクティスとして、運用環境にデプロイするときは Java LTS リリースを使用することをお勧めします。 デフォルトは、Azure SDK Maven アーキタイプが最新の LTS リリースを選択します。現在は、Java 17 ベースラインが設定されています。 ただし、javaVersion パラメーターを設定することで、既定の動作をオーバーライドできます。
Azure SDK for Java ビルド ツールを使用する
Azure SDK for Java プロジェクトには、プロジェクトに含めることができる Maven ビルド ツールが付属しています。 このツールはローカルで実行され、Microsoft にデータは送信されません。 特定の条件が満たされたときにレポートを生成したり、ビルドを失敗させたりするようにツールを構成できるため、次のような多数のベスト プラクティスに準拠するのに役立ちます。
- 最新バージョンの使用や、Azure SDK for Java クライアント ライブラリの依存関係バージョンを定義するための BOM への依存など、
azure-sdk-for-javaBOM の正しい使用を検証します。 詳細については、「既存のプロジェクトに Azure SDK for Java を追加する」セクションを参照してください。 - 新しいバージョンや改善されたバージョンが存在するときに、過去に使用された Azure クライアント ライブラリが使用されていないことを検証します。
このレポートでは、ベータ API の使用状況に関する分析情報も提供されます。
次の例に示すように、プロジェクトの Maven POM ファイルでビルド ツールを構成できます。 {latest_version}プレースホルダーは、必ずオンラインで一覧表示されている最新バージョンに置き換えます。
<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 |
true | 依存関係が azure-sdk-for-java BOM から使用できる場合、バージョンは手動でオーバーライドされません。 |
validateNoDeprecatedMicrosoftLibraryUsed |
true | プロジェクトで前世代の Azure ライブラリが使用されないようにします。 新しいライブラリと前世代のライブラリを 1 つのプロジェクトで使用しても問題が発生する可能性は低いですが、準最適開発者エクスペリエンスを引き起こします。 |
validateNoBetaLibraryUsed |
false | 一部の Azure SDK for Java クライアント ライブラリには、x.y.z-beta.n 形式のバージョン文字列を使用したベータ版があります。 この機能を有効にすると、ベータ ライブラリが使用されなくなります。 |
validateNoBetaApiUsed |
true | Azure SDK for Java クライアント ライブラリには、@Beta の注釈が付けられた GA リリースがある場合があります。 このチェックでは、そのようなメソッドが使用されているかどうかを確認します。 |
sendToMicrosoft |
true | テレメトリの目的でビルド レポートを 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 ファイルに次のスニペットを含めます。 {bom_version_to_target} プレースホルダーを、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 に含まれているものとは別のライブラリ バージョンに依存する場合は、dependency セクションで、groupId および artifactId と共に、Maven の依存関係のバージョンを指定できます。 次の例に示すように、同じプロジェクト POM ファイル内で、BOM バージョン使用する依存関係と、オーバーライドされたバージョンを使用する依存関係を使用することを選択できます。
<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 ビルドにもそれを追加できます。 Mavenの手順については、GraalVM Web サイトを参照してください。
これで、ネイティブ イメージ ビルドを実行する準備ができました。 標準の Maven ツールを使用して、GraalVM ネイティブ イメージを使用できます。 Maven の場合、次のコマンドを使用します。
mvn clean package -Pnative
このコマンドを実行すると、GraalVM は実行されているプラットフォームのネイティブ実行可能ファイルを出力します。 実行可能ファイルは、プロジェクトの Maven /target ディレクトリに表示されます。 これで、この実行可能ファイルを使用してアプリケーションを実行できるようになり、標準の Java アプリケーションと同様に実行されます。