你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

用于 Java 的 Azure 存储库

项目
11/11/2024

适用于 Java 的 Azure 存储库提供用于处理 Azure 存储帐户和存储帐户本身中的数据的类。有关 Azure 存储的详细信息，请参阅 Azure 存储简介。

用于数据访问的客户端库

适用于 Java 的 Azure 存储客户端库支持 Blob 存储、队列存储、Azure 文件存储和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");

有关更多示例，请查看客户端库自述文件。

可用包

下表介绍了适用于 Java 的存储客户端库的建议版本。

库版本	支持的服务	Maven	Reference / Javadoc	源、自述文件、示例
版本 12	Blob、队列、文件和数据湖	Blob 队列文件 Data Lake	Blob 队列文件 Data Lake	Blob (快速入门) 队列文件 Data Lake
版本 8	Blob、队列、文件和表	所有服务	版本 8 参考	所有服务 (快速入门)

有关如何安装和使用预览包的详细信息，请参阅 Azure SDK 版本页。

用于资源管理的客户端库

使用 Azure 存储资源提供程序管理存储帐户、帐户密钥、访问层等。若要使用资源提供程序库，请将依赖项添加到 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());
}

已知问题

适用于 Java 的 Azure 存储 SDK (v12) 的较旧版本存在一个或多个已知的关键问题，详见下面。这些问题可能会影响从 Azure 存储帐户写入或读取数据。如果使用旧版客户端库，建议更新到最新版本。

客户端库	受影响的版本	最低安全版本	建议的操作
Azure 存储 Blob	12.0 到 12.10.0、12.19.0 到 12.22.0	12.22.1	更新到最新版本
Azure 文件 Data Lake	12.0 到 12.7.0	12.8.0	更新到最新版本
Azure 文件共享	12.0 到 12.4.1	12.5.0	更新到最新版本
Azure 存储队列	12.0 到 12.6.0	12.7.0	更新到最新版本
Azure Blob 存储加密	12.0 到 12.16.1	12.17.0	更新到最新版本

如果有疑问或需要其他帮助，请使用以下选项创建支持票证：

问题类型：技术
服务类型：Blob 存储
摘要：#JavaSDKv12
问题类型：开发
问题子类型：客户端库或 SDK

已知问题列表

缓冲区覆盖问题 BlobOutputStream
重试期间上传的数据无效
发生时 IOException 上传错误返回为成功
下载的数据不正确 downloadToFile
上传大型文件时不遵循 Overwrite 参数，导致不正确的覆盖
覆盖参数的覆盖操作被反转，导致不正确的覆盖
仅设置可见性超时时，消息内容被错误擦除
由于 CBC 模式下的安全漏洞，客户端加密已更新为使用 AES-GCM
重试基础 REST 请求时，使用 downloadToFile () 下载不正确的数据
使用 SDK Beta 版本时出现 InvalidHeaderValue 错误消息

1. 缓冲区覆盖问题 `BlobOutputStream`

问题说明

BlobOutputStream如果使用对象上传 blob，在某些情况下，此用法可能会导致将无效对象写入Azure Blob 存储。 BlobOutputStream 对象可以通过获取 BlockBlobClient.getBlobOutputStream()。

使用 write() 类的方法BlobOutputStream上传大于值MaxSingleUploadSize的文件会导致将无效对象写入Azure Blob 存储。的 MaxSingleUploadSize 默认值为 256 MiB。可以通过调用 setMaxSingleUploadSizeLong() 类的 ParallelTransferOptions 方法更改此值。

输入数据大小越过后 MaxSingleUploadSize， write() BlobOutputStream 的方法将返回，然后再对输入数据进行深度复制。如果调用应用程序在进行深层复制之前用其他数据覆盖输入数据字节数组，则可能会将无效数据写入 Blob。

问题详细信息

客户端库	受影响的版本	最低安全版本	建议的操作
Azure 存储 Blob	12.0 到 12.10.0	12.10.1	更新到最新版本或最低版本 12.22.1

建议的步骤

根据上表更新客户端库版本。
检查应用程序代码是否正在调用 BlockBlobClient.getBlobOutputStream()。如果找到它，则应用程序会受到影响。

此外，还可以在 Azure 存储帐户中识别由于此问题而可能受到影响的任何 Blob。按照以下步骤识别可能受影响的 Blob：

检查应用程序是否正在使用 BlobOutputStream 上传 (通过 BlockBlobClient.getBlobOutputStream()) 获取的 blob。如果没有，则此问题不会影响应用程序。但是，我们仍建议将应用程序升级为使用版本 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. 重试期间上传的数据无效

问题说明

下面列出的客户端库有一个 bug，在失败的服务请求 (（例如，HTTP 500 响应) 导致的重试）期间，可能会上传不正确的数据。

问题详细信息

客户端库	受影响的版本	最低安全版本	建议的操作
Azure 存储 Blob	12.0 到 12.6.1	12.7.0	更新到最新版本或最低版本 12.22.1
Azure 文件 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.uploadWithResponse() 的所有重载void BlobClient.upload()都以无提示方式捕获来自存储服务的错误响应。方法应返回或引发作为其成功/错误指示符。应记录并传播的异常将改为直接写入标准错误，然后被吞没，尽管引发是 API 的唯一故障指示器。因此，方法成功返回，使调用方认为操作已完成。这会导致 Blob 未写入存储，尽管库指示成功。

问题详细信息

客户端库	受影响的版本	最低安全版本	建议的操作
Azure 存储 Blob	12.0 到 12.4.0	12.5.0	更新到最新版本或最低版本 12.22.1

建议的步骤

根据上表更新客户端库版本。

返回到已知问题列表

4. 下载的数据不正确 `downloadToFile`

问题说明

异步缓冲区写入具有争用条件，即在刷新到文件之前，可以将网络流和文件流之间的缓冲区重新用于传入数据。这会导致下载的文件损坏，其中某些数据会立即重复，从而覆盖其位置中的有效数据。存储中的对象仍然正确。

问题详细信息

客户端库	受影响的版本	最低安全版本	建议的操作
Azure 存储 Blob	12.0 到 12.2.0	12.3.0	更新到最新版本或最低版本 12.22.1

建议的步骤

根据上表更新客户端库版本。

返回到已知问题列表

5. 上传大型文件时不遵循 Overwrite 参数，导致不正确的覆盖

问题说明

如果正在进行另一个并行上传作业，则不遵循覆盖标志。这会导致在预期情况下不覆盖存储中的对象。

问题详细信息

客户端库	受影响的版本	最低安全版本	建议的操作
Azure 存储 Blob	12.0	12.1.0	更新到最新版本或最低版本 12.22.1

建议的步骤

根据上表更新客户端库版本。

返回到已知问题列表

6. 覆盖参数的覆盖操作被反转，导致不正确的覆盖

问题说明

覆盖参数和覆盖操作在和 DataLakeFileClient.flush(long, bool) 函数中DataLakeFileClient.flush(long)被反转。库的其他行为不会调用这些方法。这会导致在用户不打算时覆盖存储中的对象，并且无法按预期覆盖。

问题详细信息

客户端库	受影响的版本	最低安全版本	建议的操作
Azure 文件 Data Lake	12.0 到 12.7.0	12.8.0	更新到最新版本或最低版本 12.8.0

建议的步骤

根据上表更新客户端库版本。

返回到已知问题列表

7. 仅设置可见性超时时消息内容被错误擦除

问题说明

仅设置或更新可见性超时时，队列消息内容会以错误的方式擦除。

问题详细信息

客户端库	受影响的版本	最低安全版本	建议的操作
Azure 存储队列	12.0 到 12.6.0	12.7.0	更新到最新版本或最低版本 12.7.0

建议的步骤

根据上表更新客户端库版本。

返回到已知问题列表

8. 由于 CBC 模式下的安全漏洞，客户端加密已更新为使用 AES-GCM

问题说明

为了缓解在 CBC 模式下发现的安全漏洞，Java v12 SDK 发布了名为 v2 的新版客户端加密，该版本使用 AES-GCM 进行客户端加密，而不是 CBC 模式。更新后的 SDK 是向后兼容的，并且能够读取和写入使用 v1 版本加密的数据。有关完整详细信息，请阅读 Azure 存储更新 SDK 中的客户端加密以解决安全漏洞。博客文章的第 2 部分概述了查看此问题是否会影响你的步骤。

问题详细信息

客户端库	受影响的版本	最低安全版本	建议的操作
Azure Blob 存储加密	12.0 到 12.16.1	12.17.0	更新到最新版本

建议的步骤

根据上表更新客户端库版本。有关建议的操作，请阅读 Azure 存储更新 SDK 中的客户端加密以解决安全漏洞。

返回到已知问题列表

9. 重试基础 REST 请求时，使用 downloadToFile () 下载的数据不正确

问题说明

Azure SDK for Java 存储库存在一个 bug，即当某些基础存储 REST 请求中途遇到网络故障时，可能会使用 downloadToFile() 方法将不正确的数据写入文件。此 bug 最初在 2022 年夏天引入，并在 2023 年 5 月通过返回到以前的行为进行修补。受影响的版本为 12.19.0 到 12.22.0。修补程序在 12.22.1 中。

问题详细信息

客户端库	受影响的版本	最低安全版本	建议的操作
Azure 存储 Blob	12.19.0 到 12.22.0	12.22.1	更新到最新版本或最低版本 12.22.1

建议的步骤

根据上表更新客户端库版本。

返回到已知问题列表

10. 使用 SDK beta 版本时出现 InvalidHeaderValue 错误消息

在极少数情况下，已升级到 SDK 的最新 beta 版本或正式发布版本的应用程序可能会收到 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>

如果已升级到最新的 beta 版或正式版 SDK，但遇到此错误，建议降级到以前正式发布的 SDK 版本，以查看问题是否得到解决。如果问题仍然存在，或者如果建议不可行，请开具支持票证以探索更多选项。

返回到已知问题列表

通过

用于 Java 的 Azure 存储库

用于数据访问的客户端库

将包添加到项目

用法示例

可用包

用于资源管理的客户端库

已知问题

已知问题列表

1. 缓冲区覆盖问题 BlobOutputStream

问题说明

问题详细信息

建议的步骤

2. 重试期间上传的数据无效

问题说明

问题详细信息

建议的步骤

3. 上传错误返回，当发生时 IOException 返回成功

问题说明

问题详细信息

建议的步骤

4. 下载的数据不正确 downloadToFile

问题说明

问题详细信息

建议的步骤

5. 上传大型文件时不遵循 Overwrite 参数，导致不正确的覆盖

问题说明

问题详细信息

建议的步骤

6. 覆盖参数的覆盖操作被反转，导致不正确的覆盖

问题说明

问题详细信息

建议的步骤

7. 仅设置可见性超时时消息内容被错误擦除

问题说明

问题详细信息

建议的步骤

8. 由于 CBC 模式下的安全漏洞，客户端加密已更新为使用 AES-GCM

问题说明

问题详细信息

建议的步骤

9. 重试基础 REST 请求时，使用 downloadToFile () 下载的数据不正确

问题说明

问题详细信息

建议的步骤

10. 使用 SDK beta 版本时出现 InvalidHeaderValue 错误消息

其他资源

1. 缓冲区覆盖问题 `BlobOutputStream`

3. 上传错误返回，当发生时 `IOException` 返回成功

4. 下载的数据不正确 `downloadToFile`