Azure Storage Libraries for Java

[アーティクル]
11/06/2024

Java 用 Azure Storage ライブラリには、自分の Azure ストレージアカウント内のデータとストレージアカウント自体を操作するためのクラスが用意されています。 Azure Storage の詳細については、「Azure Storage の概要」を参照してください。

データアクセス用のクライアントライブラリ

Java 用 Azure Storage クライアントライブラリでは、Blob Storage、Queue Storage、Azure Files、Azure Data Lake Storage Gen2 (プレビューライブラリ) がサポートされています。

パッケージをプロジェクトに追加する

必要に応じて、Maven ファイルに次の依存関係を pom.xml 追加します。

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

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-queue</artifactId>
  <version>12.3.0</version>
</dependency>

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-file-share</artifactId>
  <version>12.2.0</version>
</dependency>

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-file-datalake</artifactId>
  <version>12.0.0-preview.6</version>
</dependency>

Java での依存関係の追加の詳細については、「依存関係の追加」を参照してください。

使用例

次の例では、ストレージコンテナーを作成し、ローカルファイルをストレージコンテナーにアップロードします。

String yourSasToken = "<insert-your-sas-token>";
/* Create a new BlobServiceClient with a SAS Token */
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
    .endpoint("https://your-storage-account-url.storage.windows.net")
    .sasToken(yourSasToken)
    .buildClient();

/* Create a new container client */
try {
    containerClient = blobServiceClient.createBlobContainer("my-container-name");
} catch (BlobStorageException ex) {
    // The container may already exist, so don't throw an error
    if (!ex.getErrorCode().equals(BlobErrorCode.CONTAINER_ALREADY_EXISTS)) {
        throw ex;
    }
}

/* Upload the file to the container */
BlobClient blobClient = containerClient.getBlobClient("my-remote-file.jpg");
blobClient.uploadFromFile("my-local-file.jpg");

その他の例については、「クライアントライブラリ README」を参照してください。

使用可能なパッケージ

次の表では、Java 用ストレージクライアントライブラリの推奨バージョンについて説明します。

ライブラリのバージョン	サポートされているサービス	Maven	リファレンス/ Javadoc	Source、Readme、Examples
バージョン 12	Blob、Queue、File、Data Lake	BLOB Queue File Data Lake	BLOB Queue File Data Lake	BLOB (クイックスタート) Queue File Data Lake
バージョン 8	BLOB、Queue、File、Table	すべてのサービス	バージョン 8 リファレンス	すべてのサービス (クイックスタート)

プレビューパッケージをインストールして使用する方法の詳細については、「 Azure SDK リリース」ページを参照してください。

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

Azure Storage リソースプロバイダーを使用して、ストレージアカウント、アカウントキー、アクセス層などを管理します。リソースプロバイダーライブラリを使用するには、Maven pom.xml ファイルに依存関係を追加します。最新バージョンのリソースプロバイダーライブラリは Maven で入手できます。

リソースプロバイダーライブラリの詳細については、「管理リファレンス」を参照してください。リソースプロバイダーライブラリのソースコードは、 Azure Java SDK リポジトリで入手できます。

次の例では、サブスクリプションに新しいストレージアカウントを作成し、そのアクセスキーを取得します。

StorageAccount storageAccount = azureResourceManager.storageAccounts().define(storageAccountName)
    .withRegion(Region.US_EAST)
    .withNewResourceGroup(rgName)
    .create();

// get a list of storage account keys related to the account
List<StorageAccountKey> storageAccountKeys = storageAccount.getKeys();
for (StorageAccountKey key : storageAccountKeys) {
    System.out.println("Key name: " + key.keyName() + " with value "+ key.value());
}

既知の問題

以前のバージョンの Azure Storage SDK for Java (v12) には、1 つ以上の既知の重大な問題があります。詳細を以下に示します。これらの問題は、Azure Storage アカウントからのデータの書き込みまたは読み取りに影響する可能性があります。古いバージョンのクライアントライブラリを使用している場合は、最新バージョンに更新することをお勧めします。

クライアントライブラリ	影響を受けたバージョン	安全な最小バージョン	推奨アクション
Azure Storage BLOB	12.0 から 12.10.0、12.19.0 から 12.22.0	12.22.1	最新バージョンへの更新
Azure File Data Lake	12.0 から 12.7.0	12.8.0	最新バージョンへの更新
Azure ファイル共有	12.0 から 12.4.1	12.5.0	最新バージョンへの更新
Azure Storage キュー	12.0 から 12.6.0	12.7.0	最新バージョンへの更新
Azure Blob Storage暗号化	12.0 から 12.16.1	12.17.0	最新バージョンへの更新

質問がある場合、または追加のヘルプが必要な場合は、次のオプションを使用してサポートチケットを作成してください。

[問題の種類]: [技術]
サービスの種類: Blob Storage
概要: #JavaSDKv12
問題の種類: 開発
問題のサブタイプ: クライアントライブラリまたは SDK

既知の問題の一覧

バッファーの上書きに関する問題 BlobOutputStream
再試行中にアップロードされた無効なデータ
アップロードが正しく返されない場合、成功した場合IOException
でダウンロードされているデータが正しくありません downloadToFile
大きなファイルのアップロード中に上書きパラメーターが優先されず、正しくない上書きが発生する
overwrite パラメーターに対して上書き操作が反転され、正しくない上書きが発生する
可視性のタイムアウトのみが設定されている場合、メッセージコンテンツが正しく消去されない
CBC モードのセキュリティの脆弱性により、AES-GCM を使用するようにクライアント側暗号化が更新されました
基になる REST 要求が再試行されるときに downloadToFile() でダウンロードされるデータが正しくない
SDK のベータ版を使用する場合の InvalidHeaderValue エラーメッセージ

1. バッファーの上書きに関する問題 `BlobOutputStream`

問題の説明

BLOB のBlobOutputStreamアップロードにオブジェクトを使用する場合、一部のシナリオでは、この使用によって無効なオブジェクトがAzure Blob Storageに書き込まれる可能性があります。 BlobOutputStream オブジェクトは、を使用して BlockBlobClient.getBlobOutputStream()取得できます。

クラスのメソッドを使用write()してのMaxSingleUploadSize値より大きいファイルをBlobOutputStreamアップロードすると、無効なオブジェクトがAzure Blob Storageに書き込まれます。の既定値 MaxSingleUploadSize は 256 MiB です。この値を変更するには、クラスのメソッドをsetMaxSingleUploadSizeLong()ParallelTransferOptions呼び出します。

入力データサイズがをMaxSingleUploadSizewrite()超えた後、BlobOutputStream のメソッドは、入力データのディープコピーを作成する前にを返します。呼び出し元のアプリケーションが、ディープコピーが行われる前に入力データのバイト配列を他のデータで上書きした場合、無効なデータが BLOB に書き込まれる可能性があります。

問題の詳細情報です

クライアントライブラリ	影響を受けたバージョン	安全な最小バージョン	推奨アクション
Azure Storage BLOB	12.0 から 12.10.0	12.10.1	最新バージョンまたは最小 12.22.1 への更新

推奨される手順

上記の表に従ってクライアントライブラリのバージョンを更新します。
アプリケーションコードがを呼び出 BlockBlobClient.getBlobOutputStream()しているかどうかを確認します。見つかると、アプリケーションが影響を受けます。

さらに、Azure Storage アカウントでこの問題が原因で影響を受ける可能性のある BLOB を特定できます。影響を受ける可能性のある BLOB を特定するには、次の手順に従います。

アプリケーションが BLOB のアップロードにを使用 BlobOutputStream しているかどうかを確認します (を介して BlockBlobClient.getBlobOutputStream()取得されます)。そうでない場合、この問題はアプリケーションに影響しません。ただし、バージョン 12.22.1 以降を使用するようにアプリケーションをアップグレードすることをお勧めします。
アプリケーションの値を MaxSingleUploadSize 取得します (既定では 256 MiB)。クラスのメソッドの setMaxSingleUploadSizeLong() コードを ParallelTransferOptions スキャンし、このプロパティに指定した値を取得します。
アプリケーションでこの問題が発生したクライアントライブラリバージョン (12.0 から 12.10.0) を使用した時間枠を特定する
この時間枠でアップロードされたすべての BLOB を特定します。 PowerShell PowerShell、Azure CLI、または別のツールを使用して操作をList Blobs呼び出すことで、BLOB の一覧を取得できます。 BLOB インベントリ機能を活用することもできます。

次の手順に従うと、重大な問題の影響を受ける可能性があり、無効である可能性がある BLOB が示されます。これらの BLOB を調べて、無効な BLOB を特定します。

既知の問題の一覧に戻る

2. 再試行中にアップロードされたデータが無効です

問題の説明

以下に示すクライアントライブラリには、失敗したサービス要求 (HTTP 500 応答による再試行など) の再試行中に正しくないデータをアップロードする可能性があるバグがあります。

問題の詳細情報です

クライアントライブラリ	影響を受けたバージョン	安全な最小バージョン	推奨アクション
Azure Storage BLOB	12.0 から 12.6.1	12.7.0	最新バージョンまたは最小 12.22.1 への更新
Azure File Data Lake	12.0 から 12.1.2	12.2.0	最新バージョンまたは最小 12.8.0 への更新
Azure ファイル共有	12.0 から 12.4.1	12.5.0	最新バージョンまたは最小 12.5.0 への更新

推奨される手順

上記の表に従ってクライアントライブラリのバージョンを更新します。

注: Azure には、誤って書き込まれたオブジェクトを回復する機能がありません。アップロード前に潜在的な影響が発生すると、影響を受けるオブジェクトの有効なコピーが Azure にありません。元のファイルがある場合は、ストレージアカウントに再アップロードできます。

既知の問題の一覧に戻る

3. アップロードが正しく返されない問題が発生した場合`IOException`

問題の説明

とのすべてのオーバーロードは、void BlobClient.upload()void BlobClient.uploadWithResponse()ストレージサービスからのエラー応答を自動的にキャッチします。メソッドは、成功/エラーインジケーターとしてを返すか、スローする必要があります。例外がログに記録され、伝達されるはずの例外は、API の唯一のエラーインジケーターであるにもかかわらず、代わりに標準エラーに直接書き込まれた後、飲み込まれます。そのため、メソッドは正常にを返し、呼び出し元は操作が完了したと見なします。これにより、成功を示すライブラリにもかかわらず、BLOB はストレージに書き込まれません。

問題の詳細情報です

クライアントライブラリ	影響を受けたバージョン	安全な最小バージョン	推奨アクション
Azure Storage BLOB	12.0 から 12.4.0	12.5.0	最新バージョンまたは最小 12.22.1 への更新

推奨される手順

上記の表に従ってクライアントライブラリのバージョンを更新します。

既知の問題の一覧に戻る

4. ダウンロード中のデータが正しくない `downloadToFile`

問題の説明

非同期バッファー書き込みには競合状態があり、ネットワークストリームとファイルストリームの間のバッファーを受信データに再利用してからファイルにフラッシュできます。これにより、ダウンロードしたファイルが破損し、一部のデータが直ちに繰り返され、その場所にある有効なデータが上書きされます。 Storage 内のオブジェクトは引き続き正しいです。

問題の詳細情報です

クライアントライブラリ	影響を受けたバージョン	安全な最小バージョン	推奨アクション
Azure Storage BLOB	12.0 から 12.2.0	12.3.0	最新バージョンまたは最小 12.22.1 への更新

推奨される手順

上記の表に従ってクライアントライブラリのバージョンを更新します。

既知の問題の一覧に戻る

5. 大きなファイルのアップロード中に上書きパラメーターが優先されず、正しくない上書きが発生する

問題の説明

別の並列アップロードジョブが進行中の場合、上書きフラグは受け入れられません。これにより、目的に合って Storage 内のオブジェクトが上書きされません。

問題の詳細情報です

クライアントライブラリ	影響を受けたバージョン	安全な最小バージョン	推奨アクション
Azure Storage BLOB	12.0	12.1.0	最新バージョンまたは最小 12.22.1 への更新

推奨される手順

上記の表に従ってクライアントライブラリのバージョンを更新します。

既知の問題の一覧に戻る

6. overwrite パラメーターの上書き操作が逆になり、正しくない上書きが発生する

問題の説明

と関数では、overwrite パラメーターと overwrite 操作が逆DataLakeFileClient.flush(long)DataLakeFileClient.flush(long, bool)になります。ライブラリの他の動作は、これらのメソッドを呼び出しません。これにより、ユーザーが意図しなかったときに Storage 内のオブジェクトが上書きされ、意図した場合は上書きに失敗します。

問題の詳細情報です

クライアントライブラリ	影響を受けたバージョン	安全な最小バージョン	推奨アクション
Azure File Data Lake	12.0 から 12.7.0	12.8.0	最新バージョンまたは最小 12.8.0 への更新

推奨される手順

上記の表に従ってクライアントライブラリのバージョンを更新します。

既知の問題の一覧に戻る

7. 可視性のタイムアウトのみが設定されている場合、メッセージの内容が正しく消去されない

問題の説明

可視性タイムアウトのみが設定または更新された場合、キューメッセージの内容はエラーで消去されます。

問題の詳細情報です

クライアントライブラリ	影響を受けたバージョン	安全な最小バージョン	推奨アクション
Azure Storage キュー	12.0 から 12.6.0	12.7.0	最新バージョンまたは最小 12.7.0 への更新

推奨される手順

上記の表に従ってクライアントライブラリのバージョンを更新します。

既知の問題の一覧に戻る

8. CBC モードのセキュリティの脆弱性により、AES-GCM を使用するようにクライアント側の暗号化が更新されました

問題の説明

CBC モードで見つかったセキュリティの脆弱性を軽減するために、Java v12 SDK は v2 と呼ばれる新しいバージョンのクライアント側暗号化をリリースしました。これは、CBC モードではなく、クライアント側の暗号化に AES-GCM を使用します。更新された SDK は下位互換性があり、 v1 バージョンで暗号化されたデータの読み取りと書き込みを行うことができます。詳細については、セキュリティの脆弱性に対処するために、SDK でクライアント側暗号化を更新する Azure Storage に関するページを参照してください。ブログ投稿のセクション 2 では、この問題が影響を受けるかどうかを確認するために実行する手順について説明します。

問題の詳細情報です

クライアントライブラリ	影響を受けたバージョン	安全な最小バージョン	推奨アクション
Azure Blob Storage暗号化	12.0 から 12.16.1	12.17.0	最新バージョンへの更新

推奨される手順

上記の表に従ってクライアントライブラリのバージョンを更新します。推奨されるアクションのセキュリティの脆弱性に対処するには、SDK でクライアント側暗号化を更新する Azure Storage に関するページを参照してください。

既知の問題の一覧に戻る

9. 基になる REST 要求の再試行時に downloadToFile() でダウンロードされるデータが正しくない

問題の説明

Azure SDK for Java Storage ライブラリには、基になるストレージ REST 要求の一部で途中でネットワーク障害が発生したときに、メソッドを使用 downloadToFile() してファイルに正しくないデータが書き込まれるバグがありました。このバグは、もともと 2022 年の夏に導入され、以前の動作に戻すことによって 2023 年 5 月に修正プログラムが適用されました。影響を受けたバージョンは 12.19.0 から 12.22.0 です。パッチは 12.22.1 にあります。

問題の詳細情報です

クライアントライブラリ	影響を受けたバージョン	安全な最小バージョン	推奨アクション
Azure Storage BLOB	12.19.0 から 12.22.0	12.22.1	最新バージョンまたは最小 12.22.1 への更新

推奨される手順

上記の表に従ってクライアントライブラリのバージョンを更新します。

既知の問題の一覧に戻る

10. SDK のベータ版を使用する場合の InvalidHeaderValue エラーメッセージ

まれなシナリオでは、最新のベータ版または一般提供バージョンの SDK にアップグレードしたアプリケーションにエラーメッセージが InvalidHeaderValue 表示される場合があります。この問題は、いずれかのストレージライブラリを使用する場合に発生する可能性があります。エラーメッセージは、次の例のようになります。

HTTP/1.1 400 The value for one of the HTTP headers is not in the correct format.
Content-Length: 328
Content-Type: application/xml
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: <REMOVED>
Date: Fri, 19 May 2023 17:10:33 GMT
 
<?xml version="1.0" encoding="utf-8"?><Error><Code>InvalidHeaderValue</Code><Message>The value for one of the HTTP headers is not in the correct format.
RequestId:<REMOVED>
Time:2023-05-19T17:10:34.2972651Z</Message><HeaderName>x-ms-version</HeaderName><HeaderValue>yyyy-mm-dd</HeaderValue></Error>

最新のベータ版または一般公開バージョンの SDK にアップグレードし、このエラーが発生した場合は、SDK の以前の一般公開バージョンにダウングレードして、問題が解決するかどうかを確認することをお勧めします。問題が解決しない場合、または推奨事項が実現できない場合は、サポートチケットを開いてさらにオプションを確認してください。

既知の問題の一覧に戻る

次の方法で共有

Azure Storage Libraries for Java

データ アクセス用のクライアント ライブラリ

パッケージをプロジェクトに追加する

使用例

使用可能なパッケージ

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

既知の問題

既知の問題の一覧

1. バッファーの上書きに関する問題 BlobOutputStream

問題の説明

問題の詳細情報です

推奨される手順

2. 再試行中にアップロードされたデータが無効です

問題の説明

問題の詳細情報です

推奨される手順

3. アップロードが正しく返されない問題が発生した場合IOException

問題の説明

問題の詳細情報です

推奨される手順

4. ダウンロード中のデータが正しくない downloadToFile

問題の説明

問題の詳細情報です

推奨される手順

5. 大きなファイルのアップロード中に上書きパラメーターが優先されず、正しくない上書きが発生する

問題の説明

問題の詳細情報です

推奨される手順

6. overwrite パラメーターの上書き操作が逆になり、正しくない上書きが発生する

問題の説明

問題の詳細情報です

推奨される手順

7. 可視性のタイムアウトのみが設定されている場合、メッセージの内容が正しく消去されない

問題の説明

問題の詳細情報です

推奨される手順

8. CBC モードのセキュリティの脆弱性により、AES-GCM を使用するようにクライアント側の暗号化が更新されました

問題の説明

問題の詳細情報です

推奨される手順

9. 基になる REST 要求の再試行時に downloadToFile() でダウンロードされるデータが正しくない

問題の説明

問題の詳細情報です

推奨される手順

10. SDK のベータ版を使用する場合の InvalidHeaderValue エラー メッセージ

その他のリソース

データアクセス用のクライアントライブラリ

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

1. バッファーの上書きに関する問題 `BlobOutputStream`

3. アップロードが正しく返されない問題が発生した場合`IOException`

4. ダウンロード中のデータが正しくない `downloadToFile`

10. SDK のベータ版を使用する場合の InvalidHeaderValue エラーメッセージ