クイック スタート: Java SE 用 Azure Blob Storage クライアント ライブラリ

注

「 Build from Leader 」オプションでは、プロジェクトの作成、パッケージのインストール、コードの作成、基本的なコンソールアプリの実行を案内します。 このオプションを選択して、Azure Blob Storageに接続するアプリの作成方法を理解してください。 デプロイメントの自動化と完了したプロジェクトで始めるには、 テンプレートからスタートを選択してください。

注

テンプレートで始めるオプションは、Azure Developer CLIを使ってデプロイ作業を自動化し、プロジェクトが完了した状態を提供します。 このオプションを選択して、セットアップ作業を完了せずにコードを探索してください。 アプリを構築するためのステップバイステップの手順は、「 Build from Scratch」を選択してください。

Java 用の Azure Blob Storage クライアント ライブラリの使用を開始して、BLOB とコンテナーを管理します。

この記事では、手順に従ってパッケージをインストールし、基本タスクのコード例を試してみます。

この記事では、Azure Developer CLI を使って Azure リソースをデプロイし、いくつかのコマンドで完成したコンソール アプリを実行します。

ヒント

Azure Storageリソースを使うSpringアプリケーションには、Spring Cloud Azureを検討してください。 このオープンソースプロジェクトは、SpringとAzureサービスを統合しています。 Blob Storageの例については、「Upload a file to an Azure Storage Blob」を参照してください。

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

前提条件

セットアップ

このセクションでは、Java 用 Azure Blob Storage クライアント ライブラリを操作するためのプロジェクトの準備について説明します。

プロジェクトの作成

blob-quickstart という名前の Java アプリケーションを作成します。

  1. コンソール ウィンドウ (PowerShell、Bash など) で、Maven を使用し、blob-quickstart という名前で新しいコンソール アプリを作成します。 次の mvn コマンドを入力して "Hello world!" Java プロジェクトを作成します。

    mvn archetype:generate `
    --define interactiveMode=n `
    --define groupId=com.blobs.quickstart `
    --define artifactId=blob-quickstart `
    --define archetypeArtifactId=maven-archetype-quickstart `
    --define archetypeVersion=1.4

  2. プロジェクト生成の成果物を見直しましょう。

    [INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/blobs/quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Project created from Archetype in dir: C:\QuickStarts\blob-quickstart
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  7.056 s
[INFO] Finished at: 2019-10-23T11:09:21-07:00
[INFO] ------------------------------------------------------------------------
    ```

  3. 新しく作成された blob-quickstart フォルダーに切り替えます。

    cd blob-quickstart

  4. blob-quickstartディレクトリ内に、dataという別のディレクトリを作成します。 このフォルダは、blobデータファイルが作成されて保存される場所です。

    mkdir data

パッケージのインストール

テキスト エディターで pom.xml ファイルを開きます。

azure-sdk-bom を追加して、最新バージョンのライブラリへの依存関係を設定します。 次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 azure-sdk-bomを使うことで、それぞれの依存関係のバージョンを指定する必要はありません。 BOM の詳細については、AZURE SDK BOM に関するページを参照してください。

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

その後、依存関係のグループに、次の dependency 要素を追加します。 Azureサービスへのパスワードレス接続にはazure-identity依存関係が必要です。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

アプリのフレームワークを設定する

プロジェクト ディレクトリから、次の手順に従ってアプリの基本的な構造を作成します。

  1. /src/main/java/com/blobs/quickstart ディレクトリに移動します
  2. エディターで App.java ファイルを開きます
  3. System.out.println("Hello world!"); 行を削除します
  4. 必要な import ディレクティブを追加します

コードは次のフレームワークのようになります。

package com.blobs.quickstart;

/**
 * Azure Blob Storage quickstart
 */
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

Azure Developer CLIを使えば、ストレージアカウントを作成し、数コマンドでサンプルコードを実行できます。 プロジェクトはローカルの開発環境でも DevContainerでも実行できます。

Azure Developer CLI テンプレートを初期化し、リソースをデプロイする

空のディレクトリから以下の手順に従って、azd テンプレートを初期化し、Azure リソースをプロビジョニングし、コードでの作業を開始します。

  • GitHub からクイックスタート リポジトリ資産をクローンして、テンプレートをローカルで初期化します。

    azd init --template blob-storage-quickstart-java

    次の情報の入力を求められます。

    • Environment name: Azure Developer CLI では、作成するすべてのAzure リソースのプレフィックスとしてこの値が使用されます。 名前は、すべてのAzureサブスクリプションで一意であり、3 ~ 24 文字の長さにする必要があります。 名前には、数字と小文字のみを含めることができます。

  • Azure にサインインします。

    azd auth login

  • リソースをプロビジョニングして Azure にデプロイします。

    azd up

    次の情報の入力を求められます。

    • サブスクリプション:リソースをデプロイするためのAzureサブスクリプションです。
    • 所在地:リソースをデプロイするためのAzureリージョン。

    デプロイが完了するまでに数分かかることがあります。 azd up コマンドからの出力には、新しく作成されたストレージ アカウントの名前が含まれています。この名前は、後でコードを実行するために必要になります。

サンプル コードを実行します。

この時点で、リソースが Azure にデプロイされ、コードを実行する準備がほぼ整います。 以下の手順に従って、コード内のストレージ アカウントの名前を更新し、サンプル コンソール アプリを実行します:

  • ストレージ アカウント名のを更新する:
    1. ローカル ディレクトリで、blob-quickstart/src/main/java/com/blobs/quickstart ディレクトリに移動します。
    2. エディターで App.java という名前のファイルを開きます。 <storage-account-name> プレースホルダーを見つけて、azd up コマンドで作成されたストレージ アカウントの実際の名前に置き換えます。
    3. 変更を保存します。
  • プロジェクトを実行する:
    1. ファイルを含む pom.xml ディレクトリに移動します。 次の mvn コマンドを使用してプロジェクトをコンパイルします: 
      mvn compile
    2. コンパイルされたコードを再頒布可能な形式でパッケージ化します。
      mvn package
    3. 次の mvn コマンドを実行して、アプリを実行します。
      mvn exec:java
  • 出力を確認する: このアプリは、ローカルの data フォルダーにテスト ファイルを作成し、ストレージ アカウントのコンテナーにアップロードします。 次に、コンテナー内の BLOB を一覧表示し、ファイルを新しい名前でダウンロードして、古いファイルと新しいファイルを比較できるようにします。

サンプル コードがどのように機能するかの詳細については、コード例を参照してください。

コードのテストが完了したら、「リソースのクリーンアップ」セクションを参照して、azd up コマンドによって作成されたリソースを削除します。

オブジェクト モデル

Azure Blob Storage は、大量の非構造化データを格納するために最適化されています。 非構造化データとは、テキスト データやバイナリ データなど、特定のデータ モデルや定義に従っていないものです。 Blob Storage には、3 種類のリソースがあります。

  • ストレージ アカウント
  • ストレージ アカウント内のコンテナー
  • コンテナー内の BLOB

次の図に、これらのリソースの関係を示します。

BLOB コンテナーと BLOB を含むストレージ アカウントを示す図。

これらのリソースとやり取りするには、以下の Java クラスを使用します。

  • BlobServiceClient:BlobServiceClientクラスはAzure Storageリソースとblobコンテナを管理します。 ストレージ アカウントでは、Blob service に対して最上位の名前空間が提供されます。
  • BlobServiceClientBuilder: BlobServiceClientBuilder クラスは、 BlobServiceClient オブジェクトの設定や作成のための流暢なAPIを提供します。
  • BlobContainerClient:BlobContainerClientクラスはAzure Storageコンテナとそのブロブを管理します。
  • BlobClient:BlobClientクラスはAzure Storageブロブを管理します。
  • BlobItem:BlobItem クラスは、listBlobs の呼び出しから返された個々の BLOB を表します。

コード例

これらのコード例のスニペットは、Java 用 Azure Blob Storage クライアント ライブラリを使用して次のアクションを実行する方法を示します。

重要

コードサンプルを使う前に 、設定 で説明されている依存関係や指示を追加してください。

注

Azure Developer CLI テンプレートには、サンプル コードが既に配置されているファイルが含まれています。 次の例では、サンプル コードの各部分について詳しく説明します。 このテンプレートは、Azure への認証に関するセクションで説明されているように、推奨されるパスワードレスの認証方法を実装します。 接続文字列メソッドは代替手段として示されていますが、テンプレートでは使われず、運用環境コードには推奨されません。

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

Azure Blob Storage に対するアプリケーション要求は、認可されている必要があります。 Azure Identity クライアント ライブラリによって提供される DefaultAzureCredential クラスを使用することは、Blob Storage などのコード内の Azure サービスへのパスワードレス接続を実装するための推奨される方法です。

アカウント アクセス キーを使用して、Azure Blob Storage への要求を認可することもできます。 ただし、この方法は慎重に使用する必要があります。 開発者は、セキュリティで保護されていない場所にアクセス・キーを公開しないように注意する必要があります。 アクセス キーを持つすべてのユーザーは、ストレージ アカウントに対する要求を承認でき、実質的にすべてのデータにアクセスできます。 DefaultAzureCredential はアカウント・キーよりも管理しやすく、セキュリティが優れており、パスワードレス認証が可能になります。 両方のオプションの例を次に示します。

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

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

例えば、ローカル開発時にVisual Studio Codeのサインイン認証情報を使って認証できます。 その後、Azureへのデプロイ後に管理されたアイデンティティを使用できます。 この移行のためにコードを変更する必要はありません。

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

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

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

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

重要

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

  1. Azure portal で、メインの検索バーまたは左側のナビゲーションを使ってストレージ アカウントを見つけます。

  2. ストレージ アカウントの概要ページで、左側のメニューから [アクセス制御 (IAM)] を選びます。

  3. [アクセス制御 (IAM)] ページで、[ロールの割り当て] タブを選びます。

  4. 上部のメニューから [+ 追加] を選択し、次に結果のドロップダウン メニューから [ロールの割り当ての追加] を選択します。

    ロールを割り当てる方法を示すスクリーンショット。

  5. 検索ボックスを使って、結果を目的のロールに絞り込みます。 この例では、ストレージ BLOB データ共同作成者を検索し、一致する結果を選び、[次へ] を選びます。

  6. [アクセスの割り当て先] で、[ユーザー、グループ、またはサービス プリンシパル] を選び、[+ メンバーの選択] を選びます。

  7. ダイアログで、自分の Microsoft Entra ユーザー名 (通常は user@domain メール アドレス) を検索し、ダイアログの下部にある [選択] を選びます。

  8. [レビューと割り当て] を選んで最終ページに移動し、もう一度 [レビューと割り当て] を行ってプロセスを完了します。

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

以下の手順に従って、ストレージアカウントのデータへのアクセスを許可してください:

  1. ストレージアカウントの役割を割り当てたのと同じMicrosoft Entraアカウントで認証してください。 Azure CLI、Visual Studio Code、またはAzure PowerShellを使いましょう。

    次のコマンドを使用して、Azure CLI を使用して Azure にサインインします。

    az login

  2. DefaultAzureCredentialを使うには、azure-identity dependencyをpom.xmlに追加します:

    <dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
</dependency>

  3. main メソッドにこのコードを追加します。 ローカルワークステーションでコードが実行されると、サインインしている優先ツールの開発者認証情報(Azure CLIやVisual Studio Codeなど)を使ってAzure認証を行います。

    /*
 * The default credential first checks environment variables for configuration
 * If environment configuration is incomplete, it will try managed identity
 */
DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(defaultCredential)
        .buildClient();

  4. BlobServiceClientのURI内のストレージアカウント名を更新してください。 ストレージアカウント名はAzureポータルの概要ページで見つけてください。

    ストレージ アカウント名の確認方法を示すスクリーンショット。

    注

    Azure にデプロイした場合は、この同じコードを使用して、Azure で実行されているアプリケーションから Azure Storage への要求を認可できます。 ただし、Azureでアプリでマネージド ID を有効にする必要があります。 次に、そのマネージド ID が接続できるようにストレージ アカウントを構成します。 この Azure サービス間の接続を構成する詳細な手順については、Azure ホステッド アプリからの認証に関するチュートリアルを参照してください。

コンテナーの作成

オブジェクト上で blobServiceClient メソッドを呼び出して、ストレージ アカウントに新しいコンテナーを作成します。 この例のコードでは、確実に一意になるように、コンテナー名に GUID 値を追加します。

main メソッドの末尾に次のコードを追加します。

// 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);

詳細や例については、「Javaでブロブコンテナを作成」をご覧ください。

重要

コンテナーの名前は小文字にする必要があります。 コンテナーと BLOB の名前付けの詳細については、「Naming and Referencing Containers, Blobs, and Metadata (コンテナー、BLOB、メタデータの名前付けと参照)」を参照してください。

コンテナーに BLOB をアップロードする

uploadFromFile メソッドを呼び出して、BLOB をコンテナーにアップロードします。 このコード例では、コンテナーにアップロードするローカルの data ディレクトリにテキスト ファイルを作成します。

main メソッドの末尾に次のコードを追加します。

// 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);

詳細や例については、「Javaでブロブをアップロードする」をご覧ください。

コンテナー内の BLOB を一覧表示する

listBlobs メソッドを呼び出して、コンテナー内の BLOB を一覧表示します。 この場合、コンテナに追加したブロブは1つだけなので、リスト操作はその1つのブロブだけを返します。

main メソッドの末尾に次のコードを追加します。

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

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

詳細や例については、JavaのList blobsをご覧ください。

BLOB をダウンロードする

downloadToFile メソッドを呼び出して、以前に作成した BLOB をダウンロードします。 例コードではファイル名に DOWNLOAD の接尾辞を付けており、ローカルファイルシステム内で両方のファイルを確認できます。

main メソッドの末尾に次のコードを追加します。

// 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);

詳細や例については、「Javaでブロブをダウンロードする」をご覧ください。

コンテナーを削除する

以下のコードは 、削除 メソッドを使ってコンテナ全体を削除してアプリが作成したリソースを整理します。 また、アプリによって作成されたローカル ファイルも削除します。

アプリでは、BLOB、コンテナー、およびローカル ファイルを削除する前に、System.console().readLine() を呼び出すことで、ユーザーの入力を一時停止します。 この一時停止により、アプリがリソースを正しく作成したことを、それらが削除される前に確認できます。

main メソッドの末尾に次のコードを追加します。

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 を使用して BLOB コンテナーを削除および復元する」をご覧ください。

コードの実行

このアプリでは、ローカル フォルダーにテスト ファイルが作成され、BLOB ストレージにアップロードされます。 次に、コンテナー内の BLOB を一覧表示し、ファイルを新しい名前でダウンロードして、古いファイルと新しいファイルを比較できるようにします。

コードをコンパイル、パッケージ化、実行するには以下の手順に従ってください:

  1. pom.xml ファイルが格納されているディレクトリに移動し、次の mvn コマンドを使用してプロジェクトをコンパイルします。
    mvn compile
  2. コンパイルされたコードを再頒布可能な形式でパッケージ化します。
    mvn package
  3. 次の mvn コマンドを実行して、アプリを実行します。
    mvn exec:java -D exec.mainClass=com.blobs.quickstart.App -D exec.cleanupDaemonThreads=false
    実行ステップを簡素化するために、 exec-maven-plugin を pom.xml に追加し、以下のコードのように設定します。 
    <plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <version>1.4.0</version>
  <configuration>
    <mainClass>com.blobs.quickstart.App</mainClass>
    <cleanupDaemonThreads>false</cleanupDaemonThreads>
  </configuration>
</plugin>
    この設定で、次のコマンドでアプリを実行します: 
    mvn exec:java

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

Azure Blob Storage - Java quickstart sample

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

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

リソースをクリーンアップする

ファイルを確認してテストを完了したら、 Enter キー を押して、ストレージ アカウントで作成したコンテナーと共にテスト ファイルを削除します。 Azure CLI を使用して、リソースを削除することもできます。

クイック スタートが完了したら、次のコマンドを実行して作成したリソースをクリーンアップします。

azd down

リソースの削除を確認するプロンプトが表示されます。 確認するには「y」と入力します。

次のステップ

Java 向け Azure Storage のサンプルと開発者ガイドクイックスタート: Azure Blob Storage 用 Quarkus 拡張機能Spring Boot を使用して Azure Blob Storage にファイルをアップロードする

  • Last updated on