Java を使用してブロック BLOB をアップロードする

この記事では、Java 用の Azure Storage クライアント ライブラリを使用してブロック BLOB をアップロードする方法について説明します。 ファイル パス、ストリーム、バイナリ オブジェクト、またはテキスト文字列からブロック BLOB にデータをアップロードできます。 インデックス タグを使用して BLOB をアップロードすることもできます。

前提条件

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

環境を設定する

既存のプロジェクトがない場合、Java 用 Azure Blob Storage クライアント ライブラリを操作するためにプロジェクトをセットアップする方法について、このセクションで説明します。 詳細については、「Azure Blob Storage と Java での作業開始」を参照してください。

この記事のコード例を使用するには、次の手順に従ってプロジェクトを設定します。

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

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

import ステートメントを追加する

次の import ステートメントを追加します。

import com.azure.core.http.rest.*;
import com.azure.core.util.BinaryData;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.options.BlobUploadFromFileOptions;
import com.azure.storage.blob.specialized.*;

import java.io.ByteArrayInputStream;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.time.Duration;
import java.util.*;

承認

認可メカニズムには、BLOB をアップロードするために必要なアクセス許可が必要です。 Microsoft Entra ID を使用した認可 (推奨) には、Azure RBAC 組み込みロールの Storage BLOB データ共同作成者以上が必要です。 詳細については、「Put BLOB (REST API)」と「Put Block (REST API)」の認可ガイダンスを参照してください。

クライアント オブジェクトの作成

アプリを Blob Storage に接続するには、 BlobServiceClientのインスタンスを作成します。

次の例では、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>");

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

ブロック BLOB にデータをアップロードする

ストリームまたはバイナリ オブジェクトからブロック BLOB をアップロードするには、次のメソッドを使用します。

• upload

ファイル パスからブロック BLOB をアップロードするには、次のメソッドを使用します。

• uploadFromFile

これらの各メソッドは、BlobClient オブジェクトまたは BlockBlobClient オブジェクトを使用して呼び出すことができます。

ローカル ファイル パスからブロック BLOB をアップロードする

次の例では、BlobClient オブジェクトを使用してブロック BLOB にファイルをアップロードします。

public void uploadBlobFromFile(BlobContainerClient blobContainerClient) {
    BlobClient blobClient = blobContainerClient.getBlobClient("sampleBlob.txt");

    try {
        blobClient.uploadFromFile("filepath/local-file.png");
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

ストリームからブロック BLOB をアップロードする

次の例では、ByteArrayInputStream オブジェクトを作成し、そのストリーム オブジェクトをアップロードすることによって、ブロック BLOB をアップロードします。

public void uploadBlobFromStream(BlobContainerClient blobContainerClient) {
    BlockBlobClient blockBlobClient = blobContainerClient.getBlobClient("sampleBlob.txt").getBlockBlobClient();
    String sampleData = "Sample data for blob";
    try (ByteArrayInputStream dataStream = new ByteArrayInputStream(sampleData.getBytes())) {
        blockBlobClient.upload(dataStream, sampleData.length());
    } catch (IOException ex) {
        ex.printStackTrace();
    }
}

BinaryData オブジェクトからブロック BLOB をアップロードする

次の例では、BlobClient オブジェクトを使用して BinaryData をブロック BLOB にアップロードします。

public void uploadDataToBlob(BlobContainerClient blobContainerClient) {
    // Create a BlobClient object from BlobContainerClient
    BlobClient blobClient = blobContainerClient.getBlobClient("sampleBlob.txt");
    String sampleData = "Sample data for blob";
    blobClient.upload(BinaryData.fromString(sampleData));
}

構成オプションを使用したブロック BLOB のアップロード

BLOB をアップロードするときに、クライアント ライブラリの構成オプションを定義できます。 これらのオプションは、パフォーマンスを向上させたり、信頼性を高めたり、コストを最適化したりするために調整できます。 次のコード例は、アップロード メソッドを呼び出すときに BlobUploadFromFileOptions を使用して構成オプションを定義する方法を示しています。 ファイルからアップロードしない場合は、アップロード メソッドで BlobParallelUploadOptions を使用して同様のオプションを設定できます。

アップロード時のデータ転送オプションの指定

ParallelTransferOptions で値を構成し、データ転送操作のパフォーマンスを向上させることができます。 次の値は、アプリのニーズに基づいてアップロード用に調整できます。

• blockSize: 各要求で転送する最大ブロック サイズ。 この値は、setBlockSizeLong メソッドを使用して設定できます。
• maxSingleUploadSize: データのサイズがこの値以下の場合は、チャンクに分割されるのではなく、1 つの put でアップロードされます。 データが 1 回のショットでアップロードされた場合、ブロック サイズは無視されます。 この値は、setMaxSingleUploadSizeLong メソッドを使用して設定できます。
• maxConcurrency: 1 回の並列転送の一部として、任意の時点で発行される並列要求の最大数。 この値は、setMaxConcurrency メソッドを使用して設定できます。

アップロードに ParallelTransferOptions を使用する場合、次の import ディレクティブがあることを確認します。

import com.azure.storage.blob.models.*;

次のコード例は、ParallelTransferOptions の値を設定し、そのオプションを BlobUploadFromFileOptions インスタンスの一部として含める方法を示しています。 このサンプルで提供される値は、推奨を意図したものではありません。 これらの値を適切にチューニングするには、アプリの特定のニーズを考慮する必要があります。

public void uploadBlockBlobWithTransferOptions(BlobContainerClient blobContainerClient, Path filePath) {
    String fileName = filePath.getFileName().toString();
    BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

    ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
            .setBlockSizeLong((long) (4 * 1024 * 1024)) // 4 MiB block size
            .setMaxConcurrency(2)
            .setMaxSingleUploadSizeLong((long) 8 * 1024 * 1024); // 8 MiB max size for single request upload

    BlobUploadFromFileOptions options = new BlobUploadFromFileOptions(filePath.toString());
    options.setParallelTransferOptions(parallelTransferOptions);

    try {
        Response<BlockBlobItem> blockBlob = blobClient.uploadFromFileWithResponse(options, null, null);
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

データ転送オプションのチューニングの詳細については、「Java を使用したアップロードとダウンロードのパフォーマンス チューニング」を参照してください。

インデックス タグ付きのブロック BLOB をアップロードする

キーと値のタグ属性を使用して、BLOB インデックス タグによってストレージ アカウント内のデータが分類されます。 これらのタグには自動的にインデックスが付けられ、検索可能な多次元インデックスとして公開されるため、データを簡単に見つけることができます。

次の例では、BlobUploadFromFileOptions を使用してインデックス タグが設定されたブロック BLOB をアップロードします。

public void uploadBlockBlobWithIndexTags(BlobContainerClient blobContainerClient, Path filePath) {
    String fileName = filePath.getFileName().toString();
    BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

    Map<String, String> tags = new HashMap<String, String>();
    tags.put("Content", "image");
    tags.put("Date", "2022-01-01");

    Duration timeout = Duration.ofSeconds(10);

    BlobUploadFromFileOptions options = new BlobUploadFromFileOptions(filePath.toString());
    options.setTags(tags);

    try {
        // Create a new block blob, or update the content of an existing blob
        Response<BlockBlobItem> blockBlob = blobClient.uploadFromFileWithResponse(options, timeout, null);
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

アップロード時に BLOB のアクセス層を設定する

BlobUploadFromFileOptions クラスを使用して、アップロード時に BLOB のアクセス層を設定できます。 次のコード例は、BLOB をアップロードするときにアクセス層を設定する方法を示しています。

public void uploadBlobWithAccessTier(BlobContainerClient blobContainerClient, Path filePath) {
    String fileName = filePath.getFileName().toString();
    BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

    BlobUploadFromFileOptions options = new BlobUploadFromFileOptions(filePath.toString())
            .setTier(AccessTier.COOL);

    try {
        Response<BlockBlobItem> blockBlob = blobClient.uploadFromFileWithResponse(options, null, null);
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

アクセス層の設定はブロック BLOB でのみ許可されています。 ブロック BLOB のアクセス層は、Hot、Cool、Cold、または Archive に設定できます。 アクセス層を Cold に設定するには、最小クライアント ライブラリ バージョン 12.21.0 を使用する必要があります。

アクセス層の詳細については、「アクセス層の概要」を参照してください。

ブロックのステージングとコミットによってブロック BLOB をアップロードする

個々のデータ ブロックを手動でステージングすることによって、アップロードをブロックに分割する方法をより細かく制御できます。 BLOB を構成するすべてのブロックがステージングされたら、それらを Blob Storage にコミットできます。 この方法を使用してブロックを並列でアップロードすることにより、パフォーマンスを向上させることができます。

public void uploadBlocks(BlobContainerClient blobContainerClient, Path filePath, int blockSize) throws IOException {
    String fileName = filePath.getFileName().toString();
    BlockBlobClient blobClient = blobContainerClient.getBlobClient(fileName).getBlockBlobClient();

    FileInputStream fileStream = new FileInputStream(filePath.toString());
    List<String> blockIDArrayList = new ArrayList<>();
    byte[] buffer = new byte[blockSize];
    int bytesRead;

    while ((bytesRead = fileStream.read(buffer, 0, blockSize)) != -1) {

        try (ByteArrayInputStream stream = new ByteArrayInputStream(buffer)) {
            String blockID = Base64.getEncoder().encodeToString(UUID.randomUUID().toString().getBytes(StandardCharsets.UTF_8));

            blockIDArrayList.add(blockID);
            blobClient.stageBlock(blockID, stream, buffer.length);
        }
    }

    blobClient.commitBlockList(blockIDArrayList);

    fileStream.close();
}

リソース

Java 用 Azure Blob Storage クライアント ライブラリを使用した BLOB のアップロードの詳細については、次のリソースを参照してください。

コード サンプル

• この記事のコード サンプルを表示する (GitHub)

REST API の操作

Azure SDK for Java には Azure REST API に基づき構築されたライブラリが含まれるため、使い慣れた Java パラダイムを通じて REST API 操作を実施できます。 BLOB をアップロードするためのクライアント ライブラリ メソッドでは、次の REST API 操作を使用します。

• Put Blob (REST API)
• Put Block (REST API)

クライアント ライブラリのリソース

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

関連項目

• BLOB インデックス タグを使用して Azure BLOB データを管理および検索する
• BLOB インデックス タグを使用して Azure Blob Storage でデータを管理および検索する

関連するコンテンツ

• この記事は、Java の Blob Storage 開発者ガイドの一部です。 詳しくは、Java アプリの構築に関するセクションにある開発者ガイド記事の完全な一覧をご覧ください。