次の方法で共有


Azure Storage Libraries for Java

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

既知の問題の一覧

  1. バッファーの上書きに関する問題 BlobOutputStream
  2. 再試行中にアップロードされた無効なデータ
  3. アップロードが正しく返されない場合、成功した場合IOException
  4. でダウンロードされているデータが正しくありません downloadToFile
  5. 大きなファイルのアップロード中に上書きパラメーターが優先されず、正しくない上書きが発生する
  6. overwrite パラメーターに対して上書き操作が反転され、正しくない上書きが発生する
  7. 可視性のタイムアウトのみが設定されている場合、メッセージ コンテンツが正しく消去されない
  8. CBC モードのセキュリティの脆弱性により、AES-GCM を使用するようにクライアント側暗号化が更新されました
  9. 基になる REST 要求が再試行されるときに downloadToFile() でダウンロードされるデータが正しくない
  10. 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 への更新
  1. 上記の表に従ってクライアント ライブラリのバージョンを更新します。
  2. アプリケーション コードが を呼び出 BlockBlobClient.getBlobOutputStream()しているかどうかを確認します。 見つかると、アプリケーションが影響を受けます。

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

  1. アプリケーションが BLOB のアップロードに を使用 BlobOutputStream しているかどうかを確認します (を介して BlockBlobClient.getBlobOutputStream()取得されます)。 そうでない場合、この問題はアプリケーションに影響しません。 ただし、バージョン 12.22.1 以降を使用するようにアプリケーションをアップグレードすることをお勧めします。
  2. アプリケーションの値を MaxSingleUploadSize 取得します (既定では 256 MiB)。 クラスのメソッドの setMaxSingleUploadSizeLong() コードを ParallelTransferOptions スキャンし、このプロパティに指定した値を取得します。
  3. アプリケーションでこの問題が発生したクライアント ライブラリバージョン (12.0 から 12.10.0) を使用した時間枠を特定する
  4. この時間枠でアップロードされたすべての BLOB を特定します。 PowerShell PowerShellAzure 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 への更新
  1. 上記の表に従ってクライアント ライブラリのバージョンを更新します。

注: 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 の以前の一般公開バージョンにダウングレードして、問題が解決するかどうかを確認することをお勧めします。 問題が解決しない場合、または推奨事項が実現できない場合は、 サポート チケットを開 いてさらにオプションを確認してください。

既知の問題の一覧に戻る