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

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

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

• 具有活动订阅的 Azure 帐户 - 创建一个用于试用的帐户。
• Azure CLI - 安装 Azure CLI 2.62.0 或更高版本以运行 Azure CLI 命令。
• Azure 存储帐户 - 创建存储帐户。
• Java 开发工具包 （JDK） 版本 17 或更高版本。
• Apache 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 存储的应用程序请求必须获得授权。 建议使用 DefaultAzureCredential 和 Azure 标识客户端库在代码中实现与 Azure 服务（包括 Blob 存储）的无密码连接。 Azure 服务的 Quarkus 扩展支持此方法。

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

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

在本快速入门中，应用在本地运行时使用 Azure CLI 登录凭据进行身份验证。 部署到 Azure 后，应用可以使用 托管标识。 环境之间的这种转换不需要任何代码更改。

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

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

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

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

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

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

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

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

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)
   

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

• 注入一个已通过 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-arc 和 quarkus-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-bom和quarkus-azure-services-bom依赖项用于管理适用于 Azure 服务的 Quarkus 平台和 Quarkus 扩展的版本。

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

@Inject
BlobServiceClient blobServiceClient;

只需编写代码即可使用 Azure Blob 存储的 Quarkus 扩展获取客户端对象。 若要确保客户端对象有权在运行时访问存储帐户，需要按照上一部分中的步骤 向 Azure 进行身份验证，并在运行应用程序之前授权访问 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 存储客户端库中描述的操作类似。 有关更详细的代码说明，请参阅本快速入门中的以下部分：

• 创建容器
• 将 blob 上传到容器中
• 列出容器中的 Blob 对象
• 下载 Blob
• 删除容器

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