Get started with the Quarkus extension for Azure Blob Storage to manage blobs and containers. In this article, you follow steps to try out example code for basic tasks.

Reference documentation |Library source code |Package (Maven) |Sample

Prerequisites

• Azure account with an active subscription -create an account for free.
• Azure CLI -Install the Azure CLI 2.62.0 or above to run Azure CLI commands.
• Azure Storage account -create a storage account.
• Java Development Kit (JDK) version 17 or above.
• Apache Maven.

Setting up

This section walks you through preparing a project to work with the Quarkus extensions for Azure Blob Storage.

Download the sample application

Thesample application used in this quickstart is a basic Quarkus application.

Usegit to download a copy of the application to your development environment, and navigate to thestorage-blob-quarkus directory.

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

Authenticate to Azure and authorize access to blob data

Application requests to Azure Blob Storage must be authorized. UsingDefaultAzureCredential and the Azure Identity client library is the recommended approach for implementing passwordless connections to Azure services in your code, including Blob Storage. The Quarkus extension for Azure services supports this approach.

DefaultAzureCredential is a credential chain implementation provided by the Azure Identity client library for Java.DefaultAzureCredential supports multiple authentication methods and determines which method to use at runtime. This approach enables your app to use different authentication methods in different environments (local vs. production) without implementing environment-specific code.

The order and locations in whichDefaultAzureCredential looks for credentials can be found in theAzure Identity library overview.

In this quickstart, your app authenticates using your Azure CLI sign-in credentials when running locally. After it's deployed to Azure, your app can then use amanaged identity. This transition between environments doesn't require any code changes.

Assign roles to your Microsoft Entra user account

When developing locally, make sure that the user account that is accessing blob data has the correct permissions. You'll needStorage Blob Data Contributor to read and write blob data. To assign yourself this role, you'll need to be assigned theUser Access Administrator role, or another role that includes theMicrosoft.Authorization/roleAssignments/write action. You can assign Azure RBAC roles to a user using the Azure portal, Azure CLI, or Azure PowerShell. For more information about theStorage Blob Data Contributor role, seeStorage Blob Data Contributor. For more information about the available scopes for role assignments, seeUnderstand scope for Azure RBAC.

In this scenario, you'll assign permissions to your user account, scoped to the storage account, to follow thePrinciple of Least Privilege. This practice gives users only the minimum permissions needed and creates more secure production environments.

The following example will assign theStorage Blob Data Contributor role to your user account, which provides both read and write access to blob data in your storage account.

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>

Sign-in and connect your app code to Azure using DefaultAzureCredential

You can authorize access to data in your storage account using the following steps:

1. Make sure you're authenticated with the same Microsoft Entra account you assigned the role to on your storage account. The following example shows how to authenticate via the Azure CLI:

   az login

2. Make sure you provide the endpoint of your Azure Blob Storage account. The following example shows how to set the endpoint using the environment variableQUARKUS_AZURE_STORAGE_BLOB_ENDPOINT via the Azure CLI. Replace<resource-group-name> and<storage-account-name> with your resource group and storage account names before running the command:

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

Run the sample

The code example performs the following actions:

• Injects a client object that is already authorized for data access viaDefaultAzureCredential using the Quarkus extension for Azure Blob Storage.
• Creates a container in a storage account.
• Uploads a blob to the container.
• Lists the blobs in the container.
• Downloads the blob data to the local file system.
• Deletes the blob and container resources created by the app.
• Deletes the local source and downloaded files.

Run the application in JVM mode by using the following command:

mvn packagejava -jar ./target/quarkus-app/quarkus-run.jar

The output of the app is similar to the following example (UUID values omitted for readability):

Uploading to Blob storage as blob:        https://mystorageacct.blob.core.windows.net/quickstartblobsUUID/quickstartUUID.txtListing blobs...        quickstartUUID.txtDownloading blob to        ./data/quickstartUUIDDOWNLOAD.txtPress the Enter key to begin clean upDeleting blob container...Deleting the local source and downloaded files...Done

Before you begin the cleanup process, check your data folder for the two files. You can compare them and observe that they're identical.

Optionally, you can run the sample in native mode. To do this, you need to have GraalVM installed, or use a builder image to build the native executable. For more information, seeBuilding a Native Executable. This quickstart uses Docker as container runtime to build a Linux native executable. If you haven't installed Docker, you can download it from theDocker website.

Run the following command to build and execute the native executable in a Linux environment:

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

Understand the sample code

Next, you walk through the sample code to understand how it works.

Inject a client object with authorized access

Working with any Azure resource using the SDK begins with creating a client object. The Quarkus extension for Azure Blob Storage automatically injects a client object with authorized access usingDefaultAzureCredential.

To successfully inject a client object, first you need to add the extensionsquarkus-arc andquarkus-azure-storage-blob to yourpom.xml file as dependencies:

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

Thequarkus-arc extension is required to use the@Inject annotation to inject the client object into your application code. Thequarkus-bom andquarkus-azure-services-bom dependencies are used to manage the versions of the Quarkus platform and the Quarkus extension for Azure services.

Next, you can inject the client object into your application code using the@Inject annotation:

@InjectBlobServiceClient blobServiceClient;

That's all you need to code to get a client object using the Quarkus extension for Azure Blob Storage. To make sure the client object is authorized to access your storage account at runtime, you need to follow steps in the previous sectionAuthenticate to Azure and authorize access to blob data before running the application.

Manage blobs and containers

The following code example shows how to create a container, upload a blob, list blobs in a container, and download a blob.

// Create a unique name for the containerString containerName = "quickstartblobs" + java.util.UUID.randomUUID();// Create the container and return a container client objectBlobContainerClient blobContainerClient = blobServiceClient.createBlobContainer(containerName);// Create the ./data/ directory and a file for uploading and downloadingString localPath = "./data/";new File(localPath).mkdirs();String fileName = "quickstart" + java.util.UUID.randomUUID() + ".txt";// Get a reference to a blobBlobClient blobClient = blobContainerClient.getBlobClient(fileName);// Write text to the fileFileWriter 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 blobblobClient.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 purposesString 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 resourcesSystem.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");

These operations are similar to the ones described inQuickstart: Azure Blob Storage client library for Java SE. For more detailed code explanations, see the following sections in that quickstart:

• Create a container
• Upload blobs to a container
• List the blobs in a container
• Download blobs
• Delete a container

Clean up

You can choose to follow the links in theNext steps section to deploy the Quarkus application to Azure. Or you can clean up the storage account by deleting the resource group. For more information, seeAzure Resource Manager resource group and resource deletion.

Next steps