クイックスタート: Azure Blob Storage 用の Quarkus 拡張機能

Azure Blob Storage の Quarkus 拡張機能を使用して、BLOB とコンテナーを管理します。この記事では、基本的なタスクのコード例を試す手順に従います。

リファレンスドキュメント | ライブラリのソースコード | パッケージ (Maven) | 見本

[前提条件]

アクティブなサブスクリプションを持つ Azure アカウント - アカウントを無料で作成します。
Azure CLI - Azure CLI 2.62.0 以降をインストールして、Azure CLI コマンドを実行します。
Azure Storage アカウント - ストレージアカウントを作成します。
Java Development Kit (JDK) バージョン 17 以降。
Apache Maven。

セットアップ中

このセクションでは、Azure Blob Storage 用の Quarkus 拡張機能を使用するプロジェクトを準備する手順について説明します。

サンプルアプリケーションをダウンロードする

このクイックスタートで使用するサンプルアプリケーションは、基本的な Quarkus アプリケーションです。

git を使用してアプリケーションのコピーを開発環境にダウンロードし、storage-blob-quarkus ディレクトリに移動します。

git clone https://github.com/Azure-Samples/quarkus-azure.git
cd quarkus-azure
git checkout 2025-01-20
cd storage-blob-quarkus

Azure に対する認証と BLOB データへのアクセスの承認

Azure Blob Storage へのアプリケーション要求が承認されている必要があります。 Blob Storage など、コード内の Azure サービスへのパスワードレス接続を実装するには、 DefaultAzureCredential と Azure ID クライアントライブラリを使用することをお勧めします。 Azure サービス用の Quarkus 拡張機能では、このアプローチがサポートされています。

DefaultAzureCredential は、Java 用 Azure Identity クライアントライブラリによって提供される資格情報チェーンの実装です。 DefaultAzureCredential は複数の認証方法をサポートしており、実行時に使用する方法が決定されます。この方法を使用すると、環境固有のコードを実装することなく、アプリで異なる環境 (ローカルと運用環境) で異なる認証方法を使用できます。

DefaultAzureCredentialが資格情報を検索する順序と場所については、Azure ID ライブラリの概要を参照してください。

このクイックスタートでは、ローカルで実行するときに、Azure CLI サインイン資格情報を使用してアプリを認証します。 Azure にデプロイされた後、アプリでマネージド ID を使用できるようになります。この環境間の遷移では、コードを変更する必要はありません。

Microsoft Entra ユーザーアカウントにロールを割り当てる

ローカルで開発する場合は、BLOB データにアクセスしているユーザーアカウントに適切なアクセス許可があることを確認します。 BLOB データの読み取りと書き込みを行うには、 ストレージ BLOB データ共同作成者 が必要です。このロールを自分に割り当てるには、ユーザーアクセス管理者ロール、または Microsoft.Authorization/roleAssignments/write アクションを含む別のロールに割り当てられている必要があります。 Azure portal、Azure CLI、または Azure PowerShell を使用して、ユーザーに Azure RBAC ロールを割り当てることができます。 ストレージ BLOB データ共同作成者ロールの詳細については、「ストレージ BLOB データ共同作成者」を参照してください。ロールの割り当てに使用できるスコープの詳細については、「 Azure RBAC のスコープについて」を参照してください。

このシナリオでは、ストレージアカウントをスコープとするアクセス許可をユーザーアカウントに割り当てて、最小限の特権の原則に従います。この方法を使って、ユーザーに必要最小限のアクセス許可のみを与え、より安全な運用環境を作成します。

次の例では、 ストレージ BLOB データ共同作成者 ロールをユーザーアカウントに割り当てます。これによって、ストレージアカウント内の BLOB データへの読み取りと書き込みの両方のアクセスが提供されます。

Important

ほとんどの場合、ロールの割り当てが Azure に反映されるまでの時間は 1 分から 2 分ですが、まれに 8 分程度までかかる場合があります。初めてコードを実行したときに認証エラーを受け取る場合は、しばらく待ってから再試行してください。

Azure portal で、メインの検索バーまたは左側のナビゲーションを使ってストレージアカウントを見つけます。
ストレージアカウントの概要ページで、左側のメニューから [アクセス制御 (IAM)] を選択します。
[アクセス制御 (IAM)] ページで、[ロールの割り当て] タブを選びます。
上部のメニューから [+ 追加] を選択し、結果のドロップダウンメニューから ロールの割り当てを追加 します。
検索ボックスを使って、結果を目的のロールに絞り込みます。この例では、 ストレージ BLOB データ共同作成者 を検索し、一致する結果を選択し、[ 次へ] を選択します。
[アクセスの割り当て先] で、[ユーザー、グループ、またはサービスプリンシパル] を選び、[+ メンバーの選択] を選びます。
ダイアログで、自分の Microsoft Entra ユーザー名 (通常は user@domain メールアドレス) を検索し、ダイアログの下部にある [選択] を選びます。
[レビューと割り当て] を選んで最終ページに移動し、もう一度 [レビューと割り当て] を行ってプロセスを完了します。

Azure CLI を使用してリソースレベルでロールを割り当てるには、最初に az storage account show コマンドを使用してリソース ID を取得する必要があります。 --query パラメーターを使って、出力プロパティをフィルター処理することができます。

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

前のコマンドからの出力 Id をコピーします。これで、Azure CLI の az role コマンドを使ってロールを割り当てることができます。

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

Azure PowerShell を使ってリソースレベルでロールを割り当てるには、まず Get-AzResource コマンドを使ってリソース ID を取得する必要があります。

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

前のコマンドの出力から Id の値をコピーします。これで、PowerShell の New-AzRoleAssignment コマンドを使ってロールを割り当てることができます。

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

次の手順を使用して、ストレージアカウント内のデータへのアクセスを承認できます。

ストレージアカウントでロールを割り当てたのと同じ Microsoft Entra アカウントで認証されていることを確認します。次の例は、Azure CLI を使用して認証する方法を示しています。
```
az login
```
Azure Blob Storage アカウントのエンドポイントを指定してください。次の例は、Azure CLI を使用して QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT 環境変数を使用してエンドポイントを設定する方法を示しています。コマンドを実行する前に、 <resource-group-name> と <storage-account-name> をリソースグループとストレージアカウントの名前に置き換えます。
```
export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --query 'primaryEndpoints.blob' \
    --output tsv)
```

注

Azure にデプロイする場合は、アプリでマネージド ID を有効にし、そのマネージド ID が接続できるようにストレージアカウントを構成する必要があります。 Azure サービス間のこの接続の構成の詳細については、「 Azure でホストされる Java アプリケーションの認証」を参照してください。

サンプルを実行する

このコード例では、次のアクションを実行します。

Azure Blob Storage の Quarkus 拡張機能を使用して、 DefaultAzureCredential 経由で既にデータアクセスが承認されているクライアントオブジェクトを挿入します。
ストレージアカウントにコンテナーを作成します。
BLOB をコンテナーにアップロードします。
コンテナー内の BLOB を一覧表示します。
BLOB データをローカルファイルシステムにダウンロードします。
アプリによって作成された BLOB リソースとコンテナーリソースを削除します。
ローカルソースとダウンロードしたファイルを削除します。

次のコマンドを使用して、JVM モードでアプリケーションを実行します。

mvn package
java -jar ./target/quarkus-app/quarkus-run.jar

アプリの出力は次の例のようになります (読みやすくするために UUID 値は省略されています)。

Uploading to Blob storage as blob:
        https://mystorageacct.blob.core.windows.net/quickstartblobsUUID/quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

クリーンアッププロセスを開始する前に、データフォルダーに 2 つのファイルがあるかどうかを確認します。それらを比較し、それらが同じであることを確認できます。

必要に応じて、ネイティブモードでサンプルを実行できます。これを行うには、GraalVM をインストールするか、ビルダーイメージを使用してネイティブ実行可能ファイルをビルドする必要があります。詳細については、「ネイティブ実行可能ファイルのビルド」を参照してください。このクイックスタートでは、コンテナーランタイムとして Docker を使用して Linux ネイティブ実行可能ファイルを構築します。 Docker をインストールしていない場合は、 Docker Web サイトからダウンロードできます。

次のコマンドを実行して、Linux 環境でネイティブ実行可能ファイルをビルドして実行します。

mvn package -Dnative -Dquarkus.native.container-build
./target/storage-blob-1.0.0-SNAPSHOT-runner

サンプルコードを理解する

次に、サンプルコードについて説明し、そのしくみを理解します。

承認されたアクセス権を持つクライアントオブジェクトを挿入する

SDK を使用して Azure リソースを操作するには、まずクライアントオブジェクトを作成します。 Azure Blob Storage の Quarkus 拡張機能は、 DefaultAzureCredentialを使用して、承認されたアクセス権を持つクライアントオブジェクトを自動的に挿入します。

クライアントオブジェクトを正常に挿入するには、最初に拡張機能quarkus-arcとquarkus-azure-storage-blobを依存関係としてpom.xmlファイルに追加する必要があります。

<properties>
    <quarkus.platform.version>3.17.7</quarkus.platform.version>
    <quarkus.azure.services.version>1.1.1</quarkus.azure.services.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>io.quarkiverse.azureservices</groupId>
            <artifactId>quarkus-azure-services-bom</artifactId>
            <version>${quarkus.azure.services.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.azureservices</groupId>
        <artifactId>quarkus-azure-storage-blob</artifactId>
    </dependency>
</dependencies>

quarkus-arc拡張機能は、@Inject注釈を使用してクライアントオブジェクトをアプリケーションコードに挿入するために必要です。 quarkus-bomとquarkus-azure-services-bomの依存関係は、Azure サービスの Quarkus プラットフォームと Quarkus 拡張機能のバージョンを管理するために使用されます。

次に、 @Inject 注釈を使用して、クライアントオブジェクトをアプリケーションコードに挿入できます。

@Inject
BlobServiceClient blobServiceClient;

Azure Blob Storage の Quarkus 拡張機能を使用してクライアントオブジェクトを取得するためにコーディングする必要があるのは、これですべてです。クライアントオブジェクトが実行時にストレージアカウントにアクセスする権限を持っていることを確認するには、前のセクション「Azure への認証」の手順に従い、アプリケーションを実行する前に BLOB データへのアクセスを承認する必要があります。

BLOB とコンテナーを管理する

次のコード例は、コンテナーの作成、BLOB のアップロード、コンテナー内の BLOB の一覧表示、BLOB のダウンロードを行う方法を示しています。

注

ローカルファイルシステムへの書き込みは、クラウドネイティブアプリケーションでは不適切なプラクティスと見なされます。ただし、この例ではローカルファイルシステムを使用して、ユーザーが簡単に検証できる方法で BLOB ストレージの使用を示しています。アプリケーションを運用環境に移行するときは、ストレージオプションを確認し、ニーズに最適なオプションを選択します。詳細については、「ストレージオプションを確認する」を参照してください。

// Create a unique name for the container
String containerName = "quickstartblobs" + java.util.UUID.randomUUID();

// Create the container and return a container client object
BlobContainerClient blobContainerClient = blobServiceClient.createBlobContainer(containerName);

// Create the ./data/ directory and a file for uploading and downloading
String localPath = "./data/";
new File(localPath).mkdirs();
String fileName = "quickstart" + java.util.UUID.randomUUID() + ".txt";

// Get a reference to a blob
BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

// Write text to the file
FileWriter writer = null;
try
{
    writer = new FileWriter(localPath + fileName, true);
    writer.write("Hello, World!");
    writer.close();
}
catch (IOException ex)
{
    System.out.println(ex.getMessage());
}

System.out.println("\nUploading to Blob storage as blob:\n\t" + blobClient.getBlobUrl());

// Upload the blob
blobClient.uploadFromFile(localPath + fileName);

System.out.println("\nListing blobs...");

// List the blob(s) in the container.
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("\t" + blobItem.getName());
}

// Download the blob to a local file

// Append the string "DOWNLOAD" before the .txt extension for comparison purposes
String downloadFileName = fileName.replace(".txt", "DOWNLOAD.txt");

System.out.println("\nDownloading blob to\n\t " + localPath + downloadFileName);

blobClient.downloadToFile(localPath + downloadFileName);

File downloadedFile = new File(localPath + downloadFileName);
File localFile = new File(localPath + fileName);

// Clean up resources
System.out.println("\nPress the Enter key to begin clean up");
System.console().readLine();

System.out.println("Deleting blob container...");
blobContainerClient.delete();

System.out.println("Deleting the local source and downloaded files...");
localFile.delete();
downloadedFile.delete();

System.out.println("Done");

これらの操作は、「クイックスタート: Java SE 用 Azure Blob Storage クライアントライブラリ」で説明されている操作に似ています。コードの詳細については、そのクイックスタートの次のセクションを参照してください。

クリーンアップ

[ 次の手順 ] セクションのリンクに従って、Quarkus アプリケーションを Azure にデプロイすることができます。または、リソースグループを削除してストレージアカウントをクリーンアップすることもできます。詳細については、「 Azure Resource Manager リソースグループとリソースの削除」を参照してください。

次のステップ

Java 用 Azure Storage のサンプルと開発者ガイド: Azure Kubernetes Service クラスターに Quarkus を使用して Java アプリケーションをデプロイする Azure Container Apps に Quarkus を使用して Java アプリケーションをデプロイする

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-09

次の方法で共有

クイック スタート: Azure Blob Storage 用の Quarkus 拡張機能

[前提条件]

セットアップ中

サンプル アプリケーションをダウンロードする

Azure に対する認証と BLOB データへのアクセスの承認

Microsoft Entra ユーザー アカウントにロールを割り当てる

DefaultAzureCredential を使用して Azure にサインインしてアプリ コードを接続する