快速入門：適用於 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 資料

對 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 中傳播只需要一兩分鐘，但在罕見情況下，可能需要長達八分鐘。如果您第一次執行程式碼時收到驗證錯誤，請稍候片刻再試一次。

在 Azure 入口網站中，使用主要搜尋列或左側導覽找出您的儲存體帳戶。
在儲存體帳戶概觀頁面上，從左側功能表中選取 [存取控制（IAM）]。
在 [存取控制 (IAM)] 頁面上，選取 [角色指派] 索引標籤。
從頂端功能表中選取 [+ 新增 ]，然後從產生的下拉式功能表中選取 [ 新增角色指派 ]。
使用搜尋方塊，從結果篩選出所需的角色。在此範例中，搜尋 Storage Blob Data Contributor 並選取相符的結果，然後選擇 [下一步]。
在 [存取權指派對象為] 下，選取 [使用者、群組或服務主體]，然後選擇 [+ 選取成員]。
在對話方塊中，搜尋 Microsoft Entra 使用者名稱 (通常是您的 user@domain 電子郵件地址)，然後在對話方塊底部選擇 [選取]。
選取 [檢閱 + 指派] 以移至最終頁面，然後再次選取 [檢閱 + 指派] 以完成此程序。

若要使用 Azure CLI 在資源層級指派角色，您必須先使用命令 az storage account show 擷取資源識別碼。您可以使用 --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 命令擷取資源識別碼。

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 進行驗證：
```
az login
```
請務必提供 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 應用程式。

執行範例程式

程式碼範例會執行下列動作：

使用 Azure Blob 儲存體的 Quarkus 延伸模組透過DefaultAzureCredential 插入已獲授權存取資料的用戶端物件。
在儲存體帳戶中建立容器。
將 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.windows.net/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 資源，首先要建立用戶端物件。 Azure Blob Storage 的 Quarkus 擴充功能會使用 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-bomquarkus-azure-services-bom相依性用於管理 Quarkus 平台的版本，以及 Azure 服務的 Quarkus 擴充功能。

接下來，您可以使用註釋將 @Inject 客戶端物件插入應用程式程式碼中：

@Inject
BlobServiceClient blobServiceClient;

這就是使用 Azure Blob Storage 的 Quarkus 擴充功能取得用戶端物件所需的全部程式碼。若要確定用戶端物件已獲授權在執行階段存取您的儲存體帳戶，您必須遵循上一節向 Azure 驗證，並在執行應用程式之前授權存取 Blob 資料中的步驟。

管理 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 Resource Manager 資源群組和資源刪除。

後續步驟

Java 的 Azure 儲存體範例和開發人員指南在 Azure Kubernetes Service 叢集上使用 Quarkus 部署 Java 應用程式在 Azure 容器應用程式上使用 Quarkus 部署 Java 應用程式

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-09