使用 Java 下载 Blob

项目
10/15/2024

本文介绍了如何使用适用于 Java 的 Azure 存储客户端库下载 Blob。可以将 Blob 数据下载到各种目标，包括本地文件路径、流或文本字符串。还可以打开 Blob 流并从中读取。

先决条件

Azure 订阅 - 创建试用订阅。
Azure 存储帐户 - 创建存储帐户
Java 开发工具包 (JDK) 8 或更高版本（我们建议使用版本 17 以获得最佳体验）
在本示例中，Apache Maven 用于项目管理

设置你的环境

如果没有现有项目，请查看本部分，其中介绍了如何设置项目来使用适用于 Java 的 Azure Blob 存储客户端库。有关详细信息，请参阅 Azure Blob 存储和 Java 入门。

要使用本文中的代码示例，请按照以下步骤设置项目。

注意

本文使用 Maven 生成工具来生成和运行示例代码。其他生成工具（例如 Gradle）也可与 Azure SDK for Java 一起使用。

安装包

在文本编辑器中打开 pom.xml 文件。通过包括 BOM 文件或包括直接依赖项来安装包。

添加 import 语句

添加以下 import 语句：

import com.azure.storage.blob.*;
import com.azure.storage.common.*;
import com.azure.storage.blob.options.BlobDownloadToFileOptions;
import com.azure.storage.blob.specialized.*;

import java.io.ByteArrayOutputStream;
import java.io.IOException;

授权

授权机制必须具有执行下载操作所需的权限。若要使用 Microsoft Entra ID 进行授权（建议），需有 Azure RBAC 内置角色“存储 Blob 数据读取者”或更高级别的角色。若要了解详细信息，请参阅获取 Blob (REST API) 的授权指南。

创建客户端对象

若要将应用连接到 Blob 存储，请创建 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.chinacloudapi.cn/")
        .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：

下载到文件路径

以下示例将 Blob 下载到本地文件路径：

public void downloadBlobToFile(BlobClient blobClient) {
    blobClient.downloadToFile("filepath/local-file.png");
}

下载到流

以下示例将 Blob 下载到 OutputStream 对象：

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

下载到字符串

以下示例假定 Blob 是文本文件，并将 Blob 下载到 String 对象：

public void downloadBlobToText(BlobClient blobClient) {
    String content = blobClient.downloadContent().toString();
    System.out.printf("Blob contents: %s%n", content);
}

从流下载

以下示例通过打开 BlobInputStream 并从流中读取来下载 Blob：

public void readBlobFromStream(BlobClient blobClient) {
    // Opening a blob input stream allows you to read from a blob through a normal
    // stream interface

    try (BlobInputStream blobStream = blobClient.openInputStream()) {
        blobStream.read();
    } catch (IOException e) {
        e.printStackTrace();
    }
}

使用配置选项下载块 blob

下载 blob 时，可以定义客户端库配置选项。可以对这些选项进行调整，以提高性能和可靠性。以下代码示例演示如何在调用下载方法时使用 BlobDownloadToFileOptions 来定义配置选项。

在下载时指定数据传输选项

可以在 ParallelTransferOptions 中配置值，以提高数据传输操作的性能。可根据应用需求针对下载调整以下值：

blockSize：要为每个请求传输的最大块大小。可以使用 setBlockSizeLong 方法设置此值。
maxConcurrency：在任何给定时间，作为单个并行传输的一部分发出的最大并行请求数量。可以使用 setMaxConcurrency 方法设置此值。

将以下 import 指令添加到你的文件，以便对下载使用 ParallelTransferOptions：

import com.azure.storage.common.*;

下面的代码示例演示如何设置 ParallelTransferOptions 的值，以及如何将选项作为 BlobDownloadToFileOptions 实例的一部分包含在内。此示例中提供的值不作为建议。若要正确优化这些值，需要考虑应用的特定需求。

public void downloadBlobWithTransferOptions(BlobClient blobClient) {
    ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
            .setBlockSizeLong((long) (4 * 1024 * 1024)) // 4 MiB block size
            .setMaxConcurrency(2);

    BlobDownloadToFileOptions options = new BlobDownloadToFileOptions("<localFilePath>");
    options.setParallelTransferOptions(parallelTransferOptions);

    blobClient.downloadToFileWithResponse(options, null, null);
}

若要详细了解如何优化数据传输选项，请参阅优化 Java 的上传和下载性能。

资源

若要详细了解如何使用适用于 Java 的 Azure Blob 存储客户端库来下载 blob，请参阅以下资源。

代码示例

查看本文中的代码示例 (GitHub)

REST API 操作

Azure SDK for Java 包含基于 Azure REST API 而生成的库，允许你通过熟悉的 Java 范例与 REST API 操作进行交互。用于下载 blob 的客户端库方法使用以下 REST API 操作：

获取 Blob (REST API)

客户端库资源

本文是适用于 Java 的 Blob 存储开发人员指南的一部分。若要了解详细信息，请参阅生成 Java 应用中的开发人员指南文章的完整列表。

通过