Java 用 Azure Storage BLOB クライアントライブラリ - バージョン 12.24.1

[アーティクル]
10/25/2023

Azure Blob Storage は、Microsoft のクラウド用オブジェクトストレージソリューションです。 Blob Storage は、テキストデータやバイナリデータなどの大量の非構造化データを格納するために最適化されています。非構造化データとは、特定のデータモデルや定義に従っていないデータであり、テキストデータやバイナリデータなどがあります。

ソースコード | API リファレンスドキュメント | REST API のドキュメント | 製品ドキュメント | サンプル

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

GA バージョンのライブラリに依存するには、azure-sdk-bom をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

<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>azure-storage-blob</artifactId>
  </dependency>
</dependencies>

直接依存関係を含める

BOM に存在しない特定のバージョンのライブラリに依存する場合は、次のように直接依存関係をプロジェクトに追加します。

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

ストレージアカウントを作成する

ストレージアカウントを作成するには、 Azure Portal または Azure CLI を使用できます。

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

ストレージアカウントの URL (後でとして <your-storage-account-url>識別されます) は、次のように書式設定されます。 http(s)://<storage-account-name>.blob.core.windows.net

クライアントを認証する

ストレージサービス (Blob、Queue、Message、MessageId、File) と対話するには、Service Client クラスのインスタンスを作成する必要があります。これを可能にするには、ストレージアカウントのアカウント SAS (共有アクセス署名) 文字列が必要です。詳細については、 SAS トークンに関するページを参照してください。

資格情報の取得

SAS トークン

a. 次の Azure CLI スニペットを使用して、ストレージアカウントから SAS トークンを取得します。

az storage blob generate-sas \
    --account-name {Storage Account name} \
    --container-name {container name} \
    --name {blob name} \
    --permissions {permissions to grant} \
    --expiry {datetime to expire the SAS token} \
    --services {storage services the SAS allows} \
    --resource-types {resource types the SAS allows}

例:

CONNECTION_STRING=<connection-string>

az storage blob generate-sas \
    --account-name MyStorageAccount \
    --container-name MyContainer \
    --name MyBlob \
    --permissions racdw \
    --expiry 2020-06-15

b. または、Azure Portal からアカウント SAS トークンを取得します。

ストレージアカウントに移動する
左側のメニューから選択 Shared access signature します
(セットアップ後) をクリックしますGenerate SAS and connection string

共有キーの資格情報

a. [アカウント名] と [アカウントキー] を使用します。アカウント名はストレージアカウント名です。

ストレージアカウントに移動する
左側のメニューから選択 Access keys します
[copy the contents of the field]\(フィールドの内容をコピーする\) の下key1/key2Key

または

b. 接続文字列を使用します。

ストレージアカウントに移動する
左側のメニューから選択 Access keys します
[copy the contents of the field]\(フィールドの内容をコピーする\) の下key1/key2Connection string

主要な概念

Blob Storage は、次の目的で設計されています。

画像またはドキュメントをブラウザーに直接配信する
分散アクセス用のファイルの格納
ビデオやオーディオのストリーミング
ログファイルへの書き込み
バックアップと復元、ディザスターリカバリー、アーカイブのためのデータの格納
オンプレミスサービスまたは Azure ホステッドサービスによる分析のためのデータの格納

URL 形式

BLOB は、次の URL 形式を使用してアドレス指定できます。次の URL は BLOB をアドレス指定します。

https://myaccount.blob.core.windows.net/mycontainer/myblob

リソースの URI の構文

ストレージアカウントの場合、BLOB 操作のベース URI にはアカウントの名前のみが含まれます。

https://myaccount.blob.core.windows.net

コンテナーの場合、キュー操作のベース URI にはアカウントの名前とコンテナーの名前が含まれます。

https://myaccount.blob.core.windows.net/mycontainer

BLOB の場合、ベース URI には、アカウントの名前、コンテナーの名前、BLOB の名前が含まれます。

https://myaccount.blob.core.windows.net/mycontainer/myblob

上記の URI は、カスタムドメイン名などのより高度なシナリオでは保持されない場合があることに注意してください。

例

次のセクションでは、次のような最も一般的な Azure Storage BLOB タスクをカバーするいくつかのコードスニペットを示します。

を作成する BlobServiceClient
を作成する BlobContainerClient
を作成する BlobClient
コンテナーの作成
BLOB にデータをアップロードする
ストリームから BLOB をアップロードする
ローカルパスから BLOB をアップロードする
BLOB がまだ存在しない場合はアップロードする
BLOB をアップロードし、既に存在する場合は上書きする
を使用して BLOB をアップロードする OutputStream
BLOB からデータをダウンロードする
BLOB をストリームにダウンロードする
BLOB をローカルパスにダウンロードする
を使用して BLOB を読み取る InputStream
BLOB を列挙する
BLOB をコピーする
SAS トークンを生成する
Azure Identity を使用して認証する
クライアントのビルド時にプロキシを設定する

認証要求の処理に使用する `BlobServiceClient`

上記で BlobServiceClient 生成したを使用してを sasToken 作成します。

BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .buildClient();

または

// Only one "?" is needed here. If the SAS token starts with "?", please removing one "?".
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
    .endpoint("<your-storage-account-url>" + "?" + "<your-sasToken>")
    .buildClient();

認証要求の処理に使用する `BlobContainerClient`

を使用してを BlobContainerClient 作成します BlobServiceClient。

BlobContainerClient blobContainerClient = blobServiceClient.getBlobContainerClient("mycontainer");

上で BlobContainerClient 生成したビルダーからを作成します sasToken 。

BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .containerName("mycontainer")
    .buildClient();

または

// Only one "?" is needed here. If the SAS token starts with "?", please removing one "?".
BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "mycontainer" + "?" + "<your-sasToken>")
    .buildClient();

認証要求の処理に使用する `BlobClient`

を使用してを BlobClient 作成します BlobContainerClient。

BlobClient blobClient = blobContainerClient.getBlobClient("myblob");

または

上で BlobClient 生成したビルダーからを作成します sasToken 。

BlobClient blobClient = new BlobClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .containerName("mycontainer")
    .blobName("myblob")
    .buildClient();

または

// Only one "?" is needed here. If the SAS token starts with "?", please removing one "?".
BlobClient blobClient = new BlobClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "mycontainer" + "/" + "myblob" + "?" + "<your-sasToken>")
    .buildClient();

コンテナーを作成する

を使用してコンテナーを BlobServiceClient作成します。

blobServiceClient.createBlobContainer("mycontainer");

または

を使用してコンテナーを BlobContainerClient作成します。

blobContainerClient.create();

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

から生成されたを使用して BlobClient BLOB にアップロードBinaryDataしますBlobContainerClient。

BlobClient blobClient = blobContainerClient.getBlobClient("myblockblob");
String dataSample = "samples";
blobClient.upload(BinaryData.fromString(dataSample));

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

から生成されたを InputStream 使用して、 BlockBlobClient から BLOB にアップロードします BlobContainerClient。

BlockBlobClient blockBlobClient = blobContainerClient.getBlobClient("myblockblob").getBlockBlobClient();
String dataSample = "samples";
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blockBlobClient.upload(dataStream, dataSample.length());
} catch (IOException e) {
    e.printStackTrace();
}

ローカルパスから BLOB をアップロードする

から生成されたを使用して BlobClient 、BLOB にファイルを BlobContainerClientアップロードします。

BlobClient blobClient = blobContainerClient.getBlobClient("myblockblob");
blobClient.uploadFromFile("local-file.jpg");

BLOB がまだ存在しない場合はアップロードする

BLOB にデータをアップロードし、既に存在する場合は失敗します。

/*
 * Rather than use an if block conditioned on an exists call, there are three ways to upload-if-not-exists using
 * one network call instead of two. Equivalent options are present on all upload methods.
 */
// 1. The minimal upload method defaults to no overwriting
String dataSample = "samples";
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blobClient.upload(dataStream, dataSample.length());
} catch (IOException e) {
    e.printStackTrace();
}

// 2. The overwrite flag can explicitly be set to false to make intention clear
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blobClient.upload(dataStream, dataSample.length(), false /* overwrite */);
} catch (IOException e) {
    e.printStackTrace();
}

// 3. If the max overload is needed, access conditions must be used to prevent overwriting
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    BlobParallelUploadOptions options =
        new BlobParallelUploadOptions(dataStream, dataSample.length());
    // Setting IfNoneMatch="*" ensures the upload will fail if there is already a blob at the destination.
    options.setRequestConditions(new BlobRequestConditions().setIfNoneMatch("*"));
    blobClient.uploadWithResponse(options, null, Context.NONE);
} catch (IOException e) {
    e.printStackTrace();
}

BLOB をアップロードし、既に存在する場合は上書きする

BLOB にデータをアップロードし、コピー先の既存のデータを上書きします。

/*
 * Rather than use an if block conditioned on an exists call, there are three ways to upload-if-exists in one
 * network call instead of two. Equivalent options are present on all upload methods.
 */
String dataSample = "samples";

// 1. The overwrite flag can explicitly be set to true. This will succeed as a create and overwrite.
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blobClient.upload(dataStream, dataSample.length(), true /* overwrite */);
} catch (IOException e) {
    e.printStackTrace();
}

/*
 * 2. If the max overload is needed and no access conditions are passed, the upload will succeed as both a
 * create and overwrite.
 */
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    BlobParallelUploadOptions options =
        new BlobParallelUploadOptions(dataStream, dataSample.length());
    blobClient.uploadWithResponse(options, null, Context.NONE);
} catch (IOException e) {
    e.printStackTrace();
}

/*
 * 3. If the max overload is needed, access conditions may be used to assert that the upload is an overwrite and
 * not simply a create.
 */
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    BlobParallelUploadOptions options =
        new BlobParallelUploadOptions(dataStream, dataSample.length());
    // Setting IfMatch="*" ensures the upload will succeed only if there is already a blob at the destination.
    options.setRequestConditions(new BlobRequestConditions().setIfMatch("*"));
    blobClient.uploadWithResponse(options, null, Context.NONE);
} catch (IOException e) {
    e.printStackTrace();
}

を使用して BLOB をアップロードする `OutputStream`

を開 BlobOutputStream き、標準ストリーム API を介して書き込んで BLOB をアップロードします。

/*
 * Opening a blob input stream allows you to write to a blob through a normal stream interface. It will not be
 * committed until the stream is closed.
 * This option is convenient when the length of the data is unknown.
 * This can only be done for block blobs. If the target blob already exists as another type of blob, it will
 * fail.
 */
try (BlobOutputStream blobOS = blobClient.getBlockBlobClient().getBlobOutputStream()) {
    blobOS.write(new byte[0]);
} catch (IOException e) {
    e.printStackTrace();
}

BLOB からデータをダウンロードする

を使用して BLOB をに OutputStream ダウンロードします BlobClient。

BinaryData content = blobClient.downloadContent();

BLOB をストリームにダウンロードする

を使用して BLOB をに OutputStream ダウンロードします BlobClient。

try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
    blobClient.downloadStream(outputStream);
} catch (IOException e) {
    e.printStackTrace();
}

BLOB をローカルパスにダウンロードする

を使用して BLOB をローカルファイルにダウンロードします BlobClient。

blobClient.downloadToFile("downloaded-file.jpg");

を使用して BLOB を読み取る `InputStream`

を開 BlobInputStream き、標準ストリーム API から読み取って BLOB をダウンロードします。

/*
 * Opening a blob input stream allows you to read from a blob through a normal stream interface. It is also
 * mark-able.
*/
try (BlobInputStream blobIS = blobClient.openInputStream()) {
    blobIS.read();
} catch (IOException e) {
    e.printStackTrace();
}

BLOB を列挙する

を使用して BlobContainerClientすべての BLOB を列挙します。

for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("This is the blob name: " + blobItem.getName());
}

または

すべての BLOB を列挙し、項目を指す新しいクライアントを作成します。

for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    BlobClient blobClient;
    if (blobItem.getSnapshot() != null) {
        blobClient = blobContainerClient.getBlobClient(blobItem.getName(), blobItem.getSnapshot());
    } else {
        blobClient = blobContainerClient.getBlobClient(blobItem.getName());
    }
    System.out.println("This is the new blob uri: " + blobClient.getBlobUrl());
}

BLOB をコピーする

BLOB のコピー。コピーソースとその認証に関する要件の詳細については、これらの各方法の javadocs を参照してください。

SyncPoller<BlobCopyInfo, Void> poller = blobClient.beginCopy("<url-to-blob>", Duration.ofSeconds(1));
poller.waitForCompletion();

または

blobClient.copyFromUrl("url-to-blob");

SAS トークンを生成する

クライアントのインスタンスを使用して、新しい SAS トークンを生成します。

/*
 * Generate an account sas. Other samples in this file will demonstrate how to create a client with the sas
 * token.
 */
// Configure the sas parameters. This is the minimal set.
OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);
AccountSasPermission accountSasPermission = new AccountSasPermission().setReadPermission(true);
AccountSasService services = new AccountSasService().setBlobAccess(true);
AccountSasResourceType resourceTypes = new AccountSasResourceType().setObject(true);

// Generate the account sas.
AccountSasSignatureValues accountSasValues =
    new AccountSasSignatureValues(expiryTime, accountSasPermission, services, resourceTypes);
String sasToken = blobServiceClient.generateAccountSas(accountSasValues);

// Generate a sas using a container client
BlobContainerSasPermission containerSasPermission = new BlobContainerSasPermission().setCreatePermission(true);
BlobServiceSasSignatureValues serviceSasValues =
    new BlobServiceSasSignatureValues(expiryTime, containerSasPermission);
blobContainerClient.generateSas(serviceSasValues);

// Generate a sas using a blob client
BlobSasPermission blobSasPermission = new BlobSasPermission().setReadPermission(true);
serviceSasValues = new BlobServiceSasSignatureValues(expiryTime, blobSasPermission);
blobClient.generateSas(serviceSasValues);

Azure Identity を使用して認証する

Azure Identity ライブラリは、Azure Storage を使用した認証のための Azure Active Directory サポートを提供します。

BlobServiceClient blobStorageClient = new BlobServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

クライアントのビルド時にプロキシを設定する

ProxyOptions options = new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 888));
BlobServiceClient client = new BlobServiceClientBuilder()
    .httpClient(new NettyAsyncHttpClientBuilder().proxy(options).build())
    .buildClient();

または

クライアントビルダーが使用する型を HttpClient 決定し、渡された構成で構築できるようにします。

HttpClientOptions clientOptions = new HttpClientOptions()
    .setProxyOptions(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 888)));
BlobServiceClient client = new BlobServiceClientBuilder()
    .clientOptions(clientOptions)
    .buildClient();

トラブルシューティング

この Java クライアントライブラリを使用して BLOB を操作する場合、サービスによって返されるエラーは、 REST API 要求に対して返されるのと同じ HTTP 状態コードに対応します。たとえば、ストレージアカウントに存在しないコンテナーまたは BLOB を取得しようとすると、 404 を示す Not Foundエラーが返されます。

既定の HTTP クライアント

すべてのクライアントライブラリでは、Netty HTTP クライアントが既定で使用されます。前述の依存関係を追加すると、Netty HTTP クライアントを使用するようにクライアントライブラリが自動的に構成されます。 HTTP クライアントの構成と変更については、HTTP クライアントの Wiki で詳しく説明されています。

既定の SSL ライブラリ

すべてのクライアントライブラリは、Tomcat ネイティブの Boring SSL ライブラリを既定で使用して、SSL 操作にネイティブレベルのパフォーマンスを実現しています。 Boring SSL ライブラリは、Linux、macOS、Windows のネイティブライブラリを含んだ uber jar であり、JDK 内の既定の SSL 実装よりも優れたパフォーマンスを備えています。依存関係のサイズを縮小する方法など、詳細については、Wiki の「パフォーマンスチューニング」セクションを参照してください。

次の手順

SDK の GitHub リポジトリでは、いくつかのストレージ BLOB Java SDK サンプルを使用できます。これらのサンプルでは、Key Vaultの操作中に一般的に発生するその他のシナリオのコード例を示します。

次の手順のサンプル

サンプルについては、こちらを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

Java 用 Azure Storage BLOB クライアント ライブラリ - バージョン 12.24.1