Azure Blob Storage と Java での作業開始

• .NET
• Java
• JavaScript
• Python
• Go

この記事では、Java 用 Azure Blob Storage クライアント ライブラリを使用して、Azure Blob Storage に接続する方法について説明します。 接続されると、コードは、Blob Storage サービスのコンテナー、BLOB、機能を使って動作できます。

API リファレンス | パッケージ (Maven) | ライブラリのソース コード | サンプル | フィードバックを送信する

前提条件

• Azure サブスクリプション - 無料アカウントを作成する
• Azure Storage アカウント - ストレージ アカウントの作成
• Java Development Kit (JDK) バージョン 8 以降
• この例では、Apache Maven をプロジェクト管理に使用します

プロジェクトの設定

注意

この記事では Maven ビルド ツールを使用して、サンプル コードをビルドして実行します。 Gradle などの他のビルド ツールも、Azure SDK for Java で動作します。

Maven を使用して新しいコンソール アプリを作成するか、既存のプロジェクトを開きます。 パッケージをインストールし、必要な import ディレクティブを追加するには、次の手順に従います。

パッケージをインストールする

テキスト エディターで pom.xml ファイルを開きます。 BOM ファイルを含めるか、直接依存関係を含めることで、パッケージをインストールします。

BOM ファイルを含める

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-storage-common</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

直接依存関係を含める

特定のバージョンのライブラリに依存関係を持たせるには、プロジェクトに直接依存関係を追加します。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>{package_version_to_target}</version>
</dependency>
<dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-storage-common</artifactId>
      <version>{package_version_to_target}</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>{package_version_to_target}</version>
</dependency>

インポート ディレクティブを含める

次に、コード ファイルを開き、必要な import ディレクティブを追加します。 この例では、"App.java" ファイルに次のディレクティブを追加します。

import com.azure.core.credential.*;
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.specialized.*;
import com.azure.storage.common.*;

BLOB クライアント ライブラリ情報:

• com.azure.storage.blob: サービス、コンテナー、BLOB を操作するために使用できるプライマリ クラス ("クライアント オブジェクト") が含まれています。
• com.azure.storage.blob.models: ユーティリティ クラス、構造体、列挙型が含まれています。
• com.azure.storage.blob.specialized: BLOB の種類 (例: 追加 BLOB) に固有の操作を実行するために使用できるクラスが含まれています。

Blob Storage へのアクセスを承認して接続する

アプリを BLOB Storage に接続するには、BlobServiceClient クラスのインスタンスを作成します。 非同期プログラミングには BlobServiceAsyncClient クラスを使用することもできます。 このオブジェクトは、ストレージ アカウント レベルでデータ リソースを操作するための開始点となります。 それを使って、ストレージ アカウントとそのコンテナーを操作できます。 また、操作する必要があるリソースに応じて、サービス クライアントを使用してコンテナー クライアントまたは BLOB クライアントを作成することもできます。

クライアント オブジェクトの作成と管理の詳細については、「データ リソースを操作するクライアント オブジェクトを作成および管理する」を参照してください。

Microsoft Entra 認可トークン、アカウント アクセス キー、または Shared Access Signature (SAS) を使用して、BlobServiceClient オブジェクトを認可できます。 最適なセキュリティのため、Microsoft では、可能な限り、Microsoft Entra ID とマネージド ID を使って、BLOB データに対する要求を認可することをお勧めします。 詳しくは、Microsoft Entra ID を使用した BLOB へのアクセスの認可に関する記事をご覧ください。

Microsoft Entra ID (推奨)

Microsoft Entra ID を使用して認可するには、セキュリティ プリンシパルを使用する必要があります。 必要なセキュリティ プリンシパルの種類は、アプリが実行される場所によって異なります。 次の表をガイドとして使用します。

アプリが実行される場所	セキュリティ プリンシパル	ガイダンス
ローカル コンピューター (開発とテスト)	サービス プリンシパル	アプリの登録、Microsoft Entra グループの設定、ロールの割り当て、環境変数の構成の方法を確認するには、開発者サービス プリンシパルを使用してアクセスを認可する方法に関する記事を参照してください。
ローカル コンピューター (開発とテスト)	ユーザー ID	Microsoft Entra グループを設定し、ロールを割り当て、Azure にサインインする方法については、開発者資格情報を使用してアクセスを認可する方法に関する記事を参照してください。
Azure でホスト	マネージド ID	マネージド ID を有効にしてロールを割り当てる方法については、マネージド ID を使用して Azure でホストされるアプリからのアクセスを承認する方法に関する記事を参照してください。
Azure の外部でホストされる (オンプレミス アプリなど)	サービス プリンシパル	アプリを登録し、ロールを割り当て、環境変数を構成する方法については、アプリケーション サービス プリンシパルを使用してオンプレミス アプリからのアクセスを承認する方法に関する記事を参照してください

DefaultAzureCredential を使用してアクセスを承認する

Blob Storage へのアクセスを承認して接続する最も簡単で安全な方法は、DefaultAzureCredential インスタンスを作成して OAuth トークンを取得することです。 その後、その資格情報を使用して BlobServiceClient オブジェクトを作成できます。

「プロジェクトの設定」の説明どおりに、pom.xml に正しい依存関係と、必要なディレクティブがあることを確認してください。

次の例では、BlobServiceClientBuilder を使用して DefaultAzureCredential を使用する BlobServiceClient オブジェクトをビルドし、必要に応じてコンテナーおよび BLOB のクライアントを作成する方法を示します。

// 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(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

SAS トークン

BlobServiceClientBuilder を使用し、SAS トークンを使用して BlobServiceClient オブジェクトをビルドします。

public static BlobServiceClient GetBlobServiceClientSAS(String sasToken) {
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .sasToken(sasToken)
            .buildClient();

    return blobServiceClient;
}

SAS トークンの生成と管理の詳細については、次の記事を参照してください。

• 共有アクセス署名 (SAS) を使用して Azure Storage リソースへの制限付きアクセスを許可する
• Java を使用してアカウント SAS を作成する
• Java を使用してサービス SAS を作成する
• Java を使用してユーザー委任 SAS を作成する

Note

Microsoft では、Shared Access Signature (SAS) を使うシナリオにはユーザー委任 SAS を使うことをお勧めします。 ユーザー委任 SAS は、アカウント キーの代わりに Microsoft Entra 資格情報で保護されます。

アカウント キー

ストレージ アカウント名とアカウント キーを使って、StorageSharedKeyCredential を作成します。 次に、そのオブジェクトを使用して BlobServiceClient を初期化します。

public static BlobServiceClient GetBlobServiceClientAccountKey(String accountName, String accountKey) {
    StorageSharedKeyCredential credential = new StorageSharedKeyCredential(accountName, accountKey);

    // Azure SDK client builders accept the credential as a parameter
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint(String.format("https://%s.blob.core.windows.net/", accountName))
            .credential(credential)
            .buildClient();

    return blobServiceClient;        
}

接続文字列を使用して BlobServiceClient オブジェクトを作成することもできます。

public static BlobServiceClient GetBlobServiceClientConnectionString(String connectionString) {
    // 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/")
            .connectionString(connectionString)
            .buildClient();

    return blobServiceClient;        
}

アカウント キーの取得方法と、キーを適切に管理して保護するためのベスト プラクティス ガイドラインについては、「ストレージ アカウント アクセス キーを管理する」をご覧ください。

重要

アカウント アクセス キーは慎重に使用する必要があります。 アカウント アクセス キーを紛失した場合、または誤ってセキュリティで保護されていない場所に置いた場合には、サービスが脆弱になる可能性があります。 アクセス キーを持つすべてのユーザーは、ストレージ アカウントに対する要求を承認でき、実質的にすべてのデータにアクセスできます。 DefaultAzureCredential はセキュリティ機能と利点が強化されており、Azure サービスに対する認可を管理するために推奨されるアプローチです。

DNS 名の検索用に JVM TTL を構成する

Java 仮想マシン (JVM) は、成功した DNS 名検索からの応答を、Time to Live (TTL) という指定された期間キャッシュします。 多くの JVM の既定の TTL 値は -1 です。これは、JVM が応答を無期限に、または JVM が再起動されるまでキャッシュすることを意味します。

Azure リソースは変更される可能性のある DNS 名エントリを使用するため、JVM TTL 値は 10 秒に設定することをお勧めします。 この構成により、リソースの更新された IP アドレスが次の DNS クエリで返されるようになります。

JVM を使用するすべてのアプリケーションの TTL 値をグローバルに変更するには、java.security ファイルで networkaddress.cache.ttl プロパティを設定します。

networkaddress.cache.ttl=10

Java 8 の場合、java.security ファイルは $JAVA_HOME/jre/lib/security ディレクトリにあります。 Java 11 以降の場合、ファイルは $JAVA_HOME/conf/security ディレクトリにあります。

アプリの構築

Azure Blob Storage のデータ リソースを操作するアプリを構築する際、コードでは主に、ストレージ アカウント、コンテナー、BLOB という 3 つのリソースの種類と対話します。 これらのリソースの種類、リソースの相互関係、およびアプリがリソースと対話する方法について詳しくは、「アプリが Blob Storage データ リソースと対話する方法を理解する」を参照してください。

以下のガイドでは、Java 用の Azure Storage クライアント ライブラリを使用してデータにアクセスし、特定のアクションを実行する方法について説明します。

ガイド	説明
再試行ポリシーを構成する	クライアント操作の再試行ポリシーを実装します。
BLOB をコピーする	ある場所から別の場所に BLOB をコピーします。
コンテナーの作成	BLOB コンテナーを作成します。
ユーザーの委任 SAS の作成	コンテナーまたは BLOB 用のユーザー委任 SAS を作成します。
BLOB のリースを作成および管理する	BLOB に対するロックを確立して管理します。
コンテナーのリースを作成および管理する	コンテナーに対するロックを確立して管理します。
BLOB の削除と復元	BLOB を削除し、論理的な削除が有効になっている場合は、削除された BLOB を復元します。
コンテナーを削除して復元する	コンテナーを削除し、論理的な削除が有効になっている場合は、削除されたコンテナーを復元します。
BLOB をダウンロードする	文字列、ストリーム、ファイル パスを使って BLOB をダウンロードします。
タグを使って BLOB を検索する	タグの設定と取得を行い、タグを使って BLOB を検索します。
BLOB をリストする	さまざまな方法で BLOB の一覧を表示します。
コンテナーをリストする	アカウントのコンテナーの一覧を表示し、さまざまなオプションを使って一覧をカスタマイズします。
プロパティとメタデータの管理 (BLOB)	BLOB のプロパティとメタデータを取得および設定します。
プロパティとメタデータの管理 (コンテナー)	コンテナーのプロパティとメタデータを取得および設定します。
データ転送のパフォーマンス チューニング	データ転送操作のパフォーマンスを最適化します。
BLOB のアクセス層を設定または変更する	ブロック BLOB のアクセス層を設定または変更します。
BLOB をアップロードする	文字列、ストリーム、ファイル パス、その他の方法を使って BLOB をアップロードする方法について説明します。