快速入门：适用于 Java SE 的 Azure Blob 存储客户端库

开始使用适用于 Java 的 Azure Blob 存储客户端库来管理 Blob 和容器。

在本文中，你将按照步骤安装软件包，并试用基本任务的示例代码。

提示

对于使用 Azure 存储资源的 Spring 应用，可以考虑 Spring Cloud Azure。该开源项目将 Spring 与 Azure 服务集成。关于 Blob 存储的示例，请参见“上传文件到 Azure 存储 Blob。

API 参考文档 | 库源代码 | 包（Maven） | 样品

先决条件

Azure具有活动订阅的帐户 - 创建试用帐户
Azure 存储帐户 - 创建存储帐户。
Java 开发工具包（JDK）版本 1.8_101 或更高版本
Apache Maven

正在设置

本部分逐步指导如何准备一个项目，使其与适用于 Java 的 Azure Blob 存储客户端库配合使用。

创建项目

创建名为 blob-quickstart 的 Java 应用程序。

在控制台窗口中（例如 PowerShell 或 Bash），使用 Maven 创建名为 blob 快速入门的新控制台应用。键入以下 mvn 命令以创建“Hello world！”Java 项目。

PowerShell
Bash

mvn archetype:generate `
    --define interactiveMode=n `
    --define groupId=com.blobs.quickstart `
    --define artifactId=blob-quickstart `
    --define archetypeArtifactId=maven-archetype-quickstart `
    --define archetypeVersion=1.4

mvn archetype:generate \
    --define interactiveMode=n \
    --define groupId=com.blobs.quickstart \
    --define artifactId=blob-quickstart \
    --define archetypeArtifactId=maven-archetype-quickstart \
    --define archetypeVersion=1.4

回顾项目生成的产出。

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/blobs/quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Project created from Archetype in dir: C:\QuickStarts\blob-quickstart
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  7.056 s
[INFO] Finished at: 2019-10-23T11:09:21-07:00
[INFO] ------------------------------------------------------------------------
    ```

切换到新建的 blob-quickstart 文件夹。
```
cd blob-quickstart
```
在 blob-quickstart 目录内，创建另一个名为 data 的目录。这个文件夹是创建和存储 blob 数据文件的地方。
```
mkdir data
```

安装软件包

在文本编辑器中打开 pom.xml 文件。

添加 azure-sdk-bom 以依赖最新版本的库。在以下代码片段中，将 {bom_version_to_target} 占位符替换为版本号。使用 azure-sdk-bom 时，你不需要指定每个依赖的具体版本。若要了解有关 BOM 的详细信息，请参阅 Azure SDK BOM 自述文件。

<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>

将以下依赖项元素添加到依赖项组。你需要 azure-identity 依赖关系，才能实现无密码连接 Azure 服务。

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

设置应用框架

在项目目录中，按照以下步骤创建应用的基本结构：

导航到 /src/main/java/com/blobs/quickstart 目录
在编辑器中打开 App.java 文件
删除 System.out.println("Hello world!"); 行
添加必要的 import 指令

代码应类似于以下框架：

package com.blobs.quickstart;

/**
 * Azure Blob Storage quickstart
 */
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

对象模型

Azure Blob 存储最适合存储巨量的非结构化数据。非结构化数据并不遵循特定数据模型或定义（如文本或二进制数据）。 Blob 存储提供了三种类型的资源：

存储帐户
存储帐户中的容器
容器中的 blob

以下图示显示了这些资源之间的关系。

图示显示一个包含一个 blob 容器和一个 blob 的存储账户。

使用以下 Java 类与这些资源进行交互：

BlobServiceClient：该BlobServiceClient类管理 Azure 存储资源和 blob 容器。存储帐户为 Blob 服务提供顶级命名空间。
BlobServiceClientBuilder：该 BlobServiceClientBuilder 类提供了一个流畅的 API 来配置和创建 BlobServiceClient 对象。
BlobContainerClient：该BlobContainerClient类管理 Azure 存储容器及其 blob。
BlobClient：BlobClient 类管理 Azure 存储 Blob。
BlobItem：类 BlobItem 表示从 listBlobs 调用返回的各个 blob。

代码示例

这些示例代码片段演示如何使用适用于 Java 的 Azure Blob 存储客户端库执行以下操作：

向 Azure 进行身份验证并授权访问 Blob 数据
创建容器
将 Blob 上传到容器
列出容器中的 Blob
下载 Blob
删除容器

重要

在使用代码示例前，先添加设置中描述的依赖和指令。

向 Azure 进行身份验证并授权访问 Blob 数据

对 Azure Blob 存储的应用程序请求必须获得授权。要在代码中实现与 Azure 服务（包括 Blob 存储）的无密码连接，推荐使用 azure-identity 客户端库提供的 DefaultAzureCredential 类。

你还可以使用帐户访问密钥授权对 Azure Blob 存储的请求。但是，应谨慎使用此方法。开发人员必须尽量避免在不安全的位置公开访问密钥。具有访问密钥的任何人都可以授权针对存储帐户的请求，并且实际上有权访问所有数据。 DefaultAzureCredential 提供比帐户密钥更好的管理和安全优势，来实现无密码身份验证。以下示例演示了这两个选项。

无密码（建议）
连接字符串

DefaultAzureCredential 是适用于 Java 的 Azure 标识客户端库提供的类。 DefaultAzureCredential 支持多种身份验证方法，并确定应在运行时使用哪种方法。通过这种方法，你的应用可在不同环境（本地与生产）中使用不同的身份验证方法，而无需实现特定于环境的代码。

你可以在 DefaultAzureCredential 中找到查找凭据的顺序和位置。

例如，你的应用在本地开发时可以通过使用 Visual Studio Code 登录凭证进行身份验证。部署到 Azure 后，你的应用可以使用托管身份。此转换不需要进行任何代码更改。

将角色分配至 Microsoft Entra 用户帐户

在本地开发时，请确保访问 Blob 数据的用户帐户具有正确的权限。需要具有存储 Blob 数据参与人角色才能读取和写入 Blob 数据。若要为自己分配此角色，您需要被分配 “用户访问管理员” 角色，或其他包含 Microsoft.Authorization/roleAssignments/write 操作的角色。可使用 Azure 门户、Azure CLI 或 Azure PowerShell 向用户分配 Azure RBAC 角色。有关 存储 Blob 数据参与者 角色的详细信息，请参阅存储 Blob 数据参与者。有关角色分配的可用范围的详细信息，请参阅了解 Azure RBAC 的范围。

在此场景中，您将为您的用户帐户分配权限，这些权限限定于存储帐户，以遵循最低权限原则。这种做法仅为用户提供所需的最低权限，并创建更安全的生产环境。

以下示例将“存储 Blob 数据参与者”角色分配给用户帐户，该角色提供对存储帐户中 Blob 数据的读取和写入访问权限。

重要

在大多数情况下，角色分配在 Azure 中传播需要一两分钟的时间，但极少数情况下最多可能需要 8 分钟。如果在首次运行代码时收到身份验证错误，请稍等片刻再试。

Azure 门户
Azure CLI
PowerShell

在 Azure 门户中，使用主搜索栏或左侧导航找到存储帐户。
在存储帐户概述页的左侧菜单中选择“访问控制 (IAM)”。
在“访问控制 (IAM)”页上，选择“角色分配”选项卡。
从顶部菜单中选择“+ 添加”，然后从出现的下拉菜单中选择“添加角色分配”。
使用搜索框将结果筛选为所需角色。在此示例中，搜索 “Storage Blob Data Contributor” 并选择匹配的结果，然后选择 “下一步”。
在“访问权限分配对象”下，选择“用户、组或服务主体”，然后选择“+ 选择成员”。
在对话框中，搜索你的 Microsoft Entra 用户名（通常是你的 user@domain 电子邮件地址），然后在对话框的底部选择“选择”。
选择“查看 + 分配”转到最后一页，然后再次选择“查看 + 分配”完成该过程。

若要使用 Azure CLI 在资源级别分配角色，必须先使用 az storage account show 命令检索资源 ID。可以使用 --query 参数筛选输出属性。

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

复制上述命令的输出 Id。然后，可以使用 Azure CLI 的 az role 命令分配角色。

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

若要使用 Azure PowerShell 在资源级别分配角色，首先必须使用 Get-AzResource 命令检索资源 ID。

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

复制上述命令输出中的 Id 值。然后，可以使用 PowerShell 中的 New-AzRoleAssignment 命令分配角色。

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

请按照以下步骤授权访问您的存储账户中的数据：

通过使用你分配存储账户角色的同一个 Microsoft Entra 账户进行认证。可以使用 Azure CLI、Visual Studio Code 或 Azure PowerShell。
- Azure CLI
- Visual Studio Code
- PowerShell
使用以下命令通过 Azure CLI 登录到 Azure：
```
az login
```
若要通过 Visual Studio Code 使用 DefaultAzureCredential，安装 Azure CLI。

在 Visual Studio Code 的主菜单上，转到 Terminal>New Terminal。

使用以下命令通过 Azure CLI 登录到 Azure：
```
az login
```
使用以下PowerShell命令登录Azure：
```
Connect-AzAccount -Environment AzureChinaCloud
```

使用 DefaultAzureCredential，需将 azure-identity 依赖添加于 pom.xml：

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
</dependency>

将此代码添加到 main 方法中。当代码在你的本地工作站运行时，它会使用你登录的优先级工具的开发凭证来认证Azure，比如Azure CLI或Visual Studio Code。

 /*
  * The default credential first checks environment variables for configuration
  * If environment configuration is incomplete, it will try managed identity
  */
 DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

 // 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(defaultCredential)
         .buildClient();

更新你的 BlobServiceClient 的 URI 中的存储帐户名称。在 Azure 门户的概览页面找到存储账户名称。

注意

部署到 Azure 时，同样的代码可用于授权从 Azure 中运行的应用程序对 Azure 存储的请求。但是，需要在Azure的应用上启用托管标识。然后，配置你的存储帐户以允许该托管标识进行连接。有关在 Azure 服务之间配置此连接的详细说明，请参阅 Azure 托管的应用中的身份验证教程。

连接字符串包括存储帐户访问密钥，并使用它来授权请求。绝不要在不安全的地方暴露钥匙。

注意

要使用存储账户访问密钥授权数据访问，你需要对以下 Azure RBAC 操作获得权限：Microsoft。存储/存储账户/列表键/动作。具有此操作权限的最小特权内置角色是读取者和数据访问，但包含此操作的任何角色都有效。

Azure 门户
Azure CLI
PowerShell

登录到 Azure 门户。
找到自己的存储帐户。
在存储帐户菜单窗格中的“安全性 + 网络”下，选择“访问密钥”。在这里，可以查看帐户访问密钥以及每个密钥的完整连接字符串。
在“访问密钥”窗格中，选择“显示密钥”。
在key1部分中，找到连接字符串值。选择“复制到剪贴板”图标来复制该连接字符串。在下一部分，你要将此连接字符串值添加到某个环境变量。

可以使用 az storage account show-connection-string 命令查看存储帐户的连接字符串。

az storage account show-connection-string --name "<your-storage-account-name>"

可以使用 Get-AzStorageAccount 和 Get-AzStorageAccountKey 命令通过 PowerShell 组装连接字符串。

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.chinacloudapi.cn'

配置存储连接字符串

在复制连接字符串后，请将其写入到运行该应用程序的本地计算机上的新环境变量。若要设置环境变量，请打开控制台窗口，并遵照适用于操作系统的说明。将 <yourconnectionstring> 替换为实际的连接字符串。

Windows：

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

在 Windows 中添加环境变量后，必须启动命令窗口的新实例。

Linux：

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

以下代码从前面创建的环境变量中检索存储帐户的连接字符串，并使用连接字符串构造服务客户端对象。

将此代码添加到 main 方法的末尾：

// Retrieve the connection string for use with the application. 
String connectStr = System.getenv("AZURE_STORAGE_CONNECTION_STRING");

// Create a BlobServiceClient object using a connection string
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
    .connectionString(connectStr)
    .buildClient();

重要

请谨慎使用帐户访问密钥。如果你丢失账户访问密钥或不小心放在不安全的地方，服务就会变得脆弱。任何拥有访问密钥的人都可以授权对存储账户的请求，实际上可以访问所有数据。 DefaultAzureCredential 提供增强的安全功能和优势，是管理 Azure 服务授权的推荐方法。

创建容器

通过在对象上调用 blobServiceClient 方法，在存储帐户中新建容器。在此示例中，代码将 GUID 值追加到容器名称，以确保它是唯一的。

将此代码添加到 main 方法的末尾：

// Create a unique name for the container
String containerName = "quickstartblobs" + java.util.UUID.randomUUID();

// Create the container and return a container client object
BlobContainerClient blobContainerClient = blobServiceClient.createBlobContainer(containerName);

更多信息和示例请参见“用 Java 创建 blob 容器。

重要

容器名称必须为小写。有关命名容器和 Blob 的详细信息，请参阅命名和引用容器、Blob 和元数据。

将 blob 上传到容器中

通过调用 uploadFromFile 方法将 Blob 上传到容器。示例代码将在本地数据目录中创建文本文件以上传到容器。

将此代码添加到 main 方法的末尾：

// Create the ./data/ directory and a file for uploading and downloading
String localPath = "./data/";
new File(localPath).mkdirs();
String fileName = "quickstart" + java.util.UUID.randomUUID() + ".txt";

// Get a reference to a blob
BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

// Write text to the file
FileWriter writer = null;
try
{
    writer = new FileWriter(localPath + fileName, true);
    writer.write("Hello, World!");
    writer.close();
}
catch (IOException ex)
{
    System.out.println(ex.getMessage());
}

System.out.println("\nUploading to Blob storage as blob:\n\t" + blobClient.getBlobUrl());

// Upload the blob
blobClient.uploadFromFile(localPath + fileName);

更多信息和示例请参见“用 Java 上传 blob”。

列出容器中的 Blob 对象

通过调用 listBlobs 方法列出容器中的 Blob。在这种情况下，你只向容器添加了一个blob，所以列表操作只返回了那一个blob。

将此代码添加到 main 方法的末尾：

System.out.println("\nListing blobs...");

// List the blob(s) in the container.
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("\t" + blobItem.getName());
}

更多信息和示例请参见 Java 列表块。

下载 Blob 对象

通过调用 downloadToFile 方法下载以前创建的 Blob。示例代码在文件名后加上后缀， DOWNLOAD 这样你就能在本地文件系统中看到两个文件。

将此代码添加到 main 方法的末尾：

// Download the blob to a local file

// Append the string "DOWNLOAD" before the .txt extension for comparison purposes
String downloadFileName = fileName.replace(".txt", "DOWNLOAD.txt");

System.out.println("\nDownloading blob to\n\t " + localPath + downloadFileName);

blobClient.downloadToFile(localPath + downloadFileName);

更多信息和示例请参见“用 Java 下载一个 blob”。

删除容器

以下代码通过删除方法删除整个容器，清理应用创建的资源。它还会删除由应用创建的本地文件。

在删除 blob、容器和本地文件之前，应用会调用 System.console().readLine() 以暂停并等待用户输入。这个暂停让你有机会确认应用在删除资源之前是否正确创建了资源。

将此代码添加到 main 方法的末尾：

File downloadedFile = new File(localPath + downloadFileName);
File localFile = new File(localPath + fileName);

// Clean up resources
System.out.println("\nPress the Enter key to begin clean up");
System.console().readLine();

System.out.println("Deleting blob container...");
blobContainerClient.delete();

System.out.println("Deleting the local source and downloaded files...");
localFile.delete();
downloadedFile.delete();

System.out.println("Done");

欲了解更多信息和示例，请参见“用 Java 删除并恢复 blob 容器。

运行代码

此应用在本地文件夹中创建测试文件，并将其上传到 Blob 存储。然后，该示例会列出容器中的 blob，并使用新名称下载文件，这样便可对新旧文件进行对比。

按照以下步骤编译、打包并运行代码：

导航到包含 pom.xml 文件的目录，并使用以下 mvn 命令编译该项目：
```
mvn compile
```
以可分发格式打包已编译的代码：
```
mvn package
```

运行以下 mvn 命令以执行应用：

mvn exec:java -D exec.mainClass=com.blobs.quickstart.App -D exec.cleanupDaemonThreads=false

为了简化运行步骤，请将 exec-maven-plugin 添加到 pom.xml 中，并按以下代码所示进行配置：

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <version>1.4.0</version>
  <configuration>
    <mainClass>com.blobs.quickstart.App</mainClass>
    <cleanupDaemonThreads>false</cleanupDaemonThreads>
  </configuration>
</plugin>

使用此配置，使用以下命令运行应用：

mvn exec:java

应用的输出类似于以下示例（为便于阅读，省略了 UUID 值）：

Azure Blob Storage - Java quickstart sample

Uploading to Blob storage as blob:
        https://mystorageacct.blob.core.chinacloudapi.cn/quickstartblobsUUID/quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

在开始清理过程之前，请在“data”文件夹中查看这两个文件。可以将它们对比，然后就会看到它们完全相同。

清理资源

验证文件并完成测试后，按 Enter 删除测试文件以及存储帐户中创建的容器。还可以使用 Azure CLI 删除资源。

下一步

适用于 Java 的 Azure 存储示例和开发人员指南快速入门：Azure Blob 存储的 Quarkus 扩展

Last updated on 2026-09-17

快速入门：适用于 Java SE 的 Azure Blob 存储客户端库

先决条件

正在设置

创建项目

安装软件包

设置应用框架

对象模型

代码示例

向 Azure 进行身份验证并授权访问 Blob 数据

将角色分配至 Microsoft Entra 用户帐户

使用 DefaultAzureCredential 登录并将应用代码连接到 Azure

创建容器

将 blob 上传到容器中

列出容器中的 Blob 对象

下载 Blob 对象

删除容器

运行代码

清理资源

下一步

其他資源