快速入门:适用于 Azure Blob 存储的 Quarkus 扩展

开始使用 Azure Blob 存储的 Quarkus 扩展来管理 Blob 和容器。 本文将按照步骤试用基本任务的示例代码。

参考文档 | 库源代码 | 包 (Maven) | 样本

先决条件

设置

本部分将指导你准备一个项目,以便使用适用于 Azure Blob 存储的 Quarkus 扩展。

下载示例应用程序

本快速入门中使用的 示例应用程序 是一个基本的 Quarkus 应用程序。

使用 git 将应用程序的副本下载到开发环境,并导航到 storage-blob-quarkus 目录。

git clone https://github.com/Azure-Samples/quarkus-azure.git
cd quarkus-azure
git checkout 2025-01-20
cd storage-blob-quarkus

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

对 Azure Blob 存储的应用程序请求必须获得授权。 建议使用 DefaultAzureCredential 和 Azure 标识客户端库在代码中实现与 Azure 服务(包括 Blob 存储)的无密码连接。 Azure 服务的 Quarkus 扩展支持此方法。

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

关于DefaultAzureCredential查找凭据的顺序和位置,可以在Azure 标识库概述中找到。

在本快速入门中,应用在本地运行时使用 Azure CLI 登录凭据进行身份验证。 部署到 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 分钟。 如果在首次运行代码时收到身份验证错误,请稍等片刻再试。

  1. 在 Azure 门户中,使用主搜索栏或左侧导航找到存储帐户。

  2. 在存储帐户概述页的左侧菜单中选择“访问控制 (IAM)”。

  3. 在“访问控制 (IAM)”页上,选择“角色分配”选项卡。

  4. 从顶部菜单中选择“+ 添加”,然后从出现的下拉菜单中选择“添加角色分配”。

    显示如何分配角色的屏幕截图。

  5. 使用搜索框将结果筛选为所需角色。 在此示例中,搜索存储 Blob 数据参与者并选择匹配的结果,然后选择下一步

  6. 在“访问权限分配对象”下,选择“用户、组或服务主体”,然后选择“+ 选择成员”。

  7. 在对话框中,搜索你的 Microsoft Entra 用户名(通常是你的 user@domain 电子邮件地址),然后在对话框的底部选择“选择”。

  8. 选择“审核 + 指派”转到最后一页,然后再次选择“审核 + 指派”以完成该过程。

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

可按照以下步骤授权访问存储帐户中的数据:

  1. 确保使用在存储帐户上分配角色时所使用的同一 Microsoft Entra 帐户进行身份验证。 以下示例演示了如何通过 Azure CLI 进行身份验证:

    az login
    
  2. 确保提供 Azure Blob 存储帐户的终结点。 以下示例演示如何通过 Azure CLI 使用环境变量 QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT 设置终结点。 在运行命令之前,请将<resource-group-name>替换为资源组名称,将<storage-account-name>替换为存储帐户名称:

    export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
        --resource-group <resource-group-name> \
        --name <storage-account-name> \
        --query 'primaryEndpoints.blob' \
        --output tsv)
    

注释

部署到 Azure 时,需要在应用上启用托管标识,并将存储帐户配置为允许该托管标识进行连接。 有关在 Azure 服务之间配置此连接的详细信息,请参阅 对 Azure 托管的 Java 应用程序进行身份验证

运行示例

该代码示例执行以下操作:

  • 注入一个已通过 DefaultAzureCredential 授权用于数据访问的客户端对象,该对象使用 Quarkus 扩展以访问 Azure Blob 存储。
  • 在存储帐户中创建容器。
  • 将 Blob 上传到容器。
  • 列出容器中的 Blob。
  • 将 blob 数据下载到本地文件系统。
  • 删除应用创建的 Blob 和容器资源。
  • 删除本地源和下载的文件。

使用以下命令在 JVM 模式下运行应用程序:

mvn package
java -jar ./target/quarkus-app/quarkus-run.jar

应用的输出类似于以下示例(为便于阅读,省略了 UUID 值):

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

在开始清理过程之前,请检查数据文件夹是否有两个文件。 可以将它们对比,然后就会看到它们完全相同。

也可以选择在本机模式下运行示例。 为此,需要安装 GraalVM,或使用构建器镜像构建本机可执行文件。 有关详细信息,请参阅 生成原生可执行文件。 本快速入门使用 Docker 作为容器运行时来生成 Linux 本机可执行文件。 如果尚未安装 Docker,可以从 Docker 网站下载它。

运行以下命令,在 Linux 环境中生成和执行本机可执行文件:

mvn package -Dnative -Dquarkus.native.container-build
./target/storage-blob-1.0.0-SNAPSHOT-runner

了解示例代码

接下来,你将演练示例代码,以了解其工作原理。

注入具有授权访问权限的客户端对象

使用 SDK 处理任何 Azure 资源首先创建客户端对象。 Quarkus Azure Blob 存储扩展自动使用 DefaultAzureCredential 注入具有授权访问权限的客户端对象。

若要成功注入客户端对象,首先需要将扩展 quarkus-arcquarkus-azure-storage-blob 添加到您的pom.xml 文件中作为依赖项。

<properties>
    <quarkus.platform.version>3.17.7</quarkus.platform.version>
    <quarkus.azure.services.version>1.1.1</quarkus.azure.services.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>io.quarkiverse.azureservices</groupId>
            <artifactId>quarkus-azure-services-bom</artifactId>
            <version>${quarkus.azure.services.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.azureservices</groupId>
        <artifactId>quarkus-azure-storage-blob</artifactId>
    </dependency>
</dependencies>

需要 quarkus-arc 扩展才能使用 @Inject 注释将客户端对象注入到应用程序代码中。 quarkus-bomquarkus-azure-services-bom依赖项用于管理适用于 Azure 服务的 Quarkus 平台和 Quarkus 扩展的版本。

接下来,可以使用 @Inject 注释将客户端对象注入应用程序代码:

@Inject
BlobServiceClient blobServiceClient;

只需编写代码即可使用 Azure Blob 存储的 Quarkus 扩展获取客户端对象。 若要确保客户端对象有权在运行时访问存储帐户,需要按照上一部分中的步骤 向 Azure 进行身份验证,并在运行应用程序之前授权访问 Blob 数据

管理数据块和容器

下面的代码示例演示如何创建容器、上传 Blob、列出容器中的 Blob 以及下载 Blob。

注释

写入本地文件系统被认为是云本机应用程序中的不良做法。 但是,此示例使用本地文件系统来说明 Blob 存储的使用方式,方便用户验证。 将应用程序带到生产环境时,请查看存储选项,并根据需要选择最佳选项。 有关详细信息,请参阅 “查看存储选项”。

// 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);

// 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);

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

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

// 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);

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 SE 的 Azure Blob 存储客户端库中描述的操作类似。 有关更详细的代码说明,请参阅本快速入门中的以下部分:

清理

可以选择按照 “后续步骤 ”部分中的链接将 Quarkus 应用程序部署到 Azure。 或者,可以通过删除资源组来清理存储帐户。 有关详细信息,请参阅 Azure 资源管理器资源组和资源删除

后续步骤