Skip to content

Commit f70c8a2

Browse files
JillGrant615JillGrant615
authored
Merge pull request #293058 from majguo/dd-2275862
Quickstart: Quarkus extension for Azure Blob Storage
2 parents 270e6cd + 7e12cb5 commit f70c8a2

File tree

5 files changed

+292
-6
lines changed

5 files changed

+292
-6
lines changed

‎articles/storage/blobs/TOC.yml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,12 @@ items:
3434
href: storage-quickstart-blobs-dotnet.md
3535
- name: Java
3636
items:
37-
- name: Java
37+
- name: Java SE
3838
href: storage-quickstart-blobs-java.md
39-
- name: Spring
39+
- name: Spring Boot
4040
href: /azure/developer/java/spring-framework/configure-spring-boot-starter-java-app-with-azure-storage?toc=/azure/storage/blobs/toc.json
41+
- name: Quarkus
42+
href: storage-quickstart-blobs-java-quarkus.md
4143
- name: Python
4244
href: storage-quickstart-blobs-python.md
4345
- name: JavaScript

‎articles/storage/blobs/index.yml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -104,10 +104,12 @@ landingContent:
104104
links:
105105
- text: Azure Blob Storage for .NET
106106
url: storage-quickstart-blobs-dotnet.md
107-
- text: Azure Blob Storage for Java
107+
- text: Azure Blob Storage for Java SE
108108
url: storage-quickstart-blobs-java.md
109-
- text: Azure Blob Storage for Spring
109+
- text: Azure Blob Storage for Spring Boot
110110
url: /azure/developer/java/spring-framework/configure-spring-boot-starter-java-app-with-azure-storage?toc=/azure/storage/blobs/toc.json
111+
- text: Azure Blob Storage for Quarkus
112+
url: storage-quickstart-blobs-java-quarkus.md
111113
- text: Azure Blob Storage for Python
112114
url: storage-quickstart-blobs-python.md
113115
- text: Azure Blob Storage for JavaScript using Node.js

‎articles/storage/blobs/storage-quickstart-blobs-java-quarkus.md

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
---
2+
title: "Quickstart: Quarkus Extension for Azure Blob Storage"
3+
description: In this quickstart, you learn how to use the Quarkus extension for Azure Blob Storage to create a container and a blob in Blob (object) storage. Next, you learn how to download the blob to your local computer, and how to list all of the blobs in a container.
4+
author: KarlErickson
5+
ms.author: karler
6+
ms.reviewer: jiangma
7+
ms.custom: devx-track-java, mode-api, passwordless-java, devx-track-extended-azdevcli, devx-track-javaee-quarkus, devx-track-javaee-quarkus-storage-blob
8+
ms.date: 03/18/2025
9+
ms.service: azure-blob-storage
10+
ms.topic: quickstart
11+
ms.devlang: java
12+
---
13+
14+
# Quickstart: Quarkus extension for Azure Blob Storage
15+
16+
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.
17+
18+
[Reference documentation](https://docs.quarkiverse.io/quarkus-azure-services/dev/quarkus-azure-storage-blob.html) | [Library source code](https://github.com/quarkiverse/quarkus-azure-services/tree/main/services/azure-storage-blob) | [Package (Maven)](https://mvnrepository.com/artifact/io.quarkiverse.azureservices/quarkus-azure-storage-blob) | [Sample](https://github.com/quarkiverse/quarkus-azure-services/tree/main/integration-tests/azure-storage-blob)
19+
20+
## Prerequisites
21+
22+
- Azure account with an active subscription - [create an account for free](https://azure.microsoft.com/free/?ref=microsoft.com&utm_source=microsoft.com&utm_medium=docs&utm_campaign=visualstudio).
23+
- Azure CLI - [Install the Azure CLI](/cli/azure/install-azure-cli) 2.62.0 or above to run Azure CLI commands.
24+
- Azure Storage account - [create a storage account](../common/storage-account-create.md).
25+
- [Java Development Kit (JDK)](/java/azure/jdk/) version 17 or above.
26+
- [Apache Maven](https://maven.apache.org/download.cgi).
27+
28+
## Setting up
29+
30+
This section walks you through preparing a project to work with the Quarkus extensions for Azure Blob Storage.
31+
32+
### Download the sample application
33+
34+
The [sample application](https://github.com/Azure-Samples/quarkus-azure/tree/2025-01-20/storage-blob-quarkus) used in this quickstart is a basic Quarkus application.
35+
36+
Use [git](https://git-scm.com/) to download a copy of the application to your development environment, and navigate to the `storage-blob-quarkus` directory.
37+
38+
```bash
39+
git clone https://github.com/Azure-Samples/quarkus-azure.git
40+
cd quarkus-azure
41+
git checkout 2025-01-20
42+
cd storage-blob-quarkus
43+
```
44+
45+
## Authenticate to Azure and authorize access to blob data
46+
47+
Application requests to Azure Blob Storage must be authorized. Using `DefaultAzureCredential` 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.
48+
49+
`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.
50+
51+
The order and locations in which `DefaultAzureCredential` looks for credentials can be found in the [Azure Identity library overview](/java/api/overview/azure/identity-readme#defaultazurecredential).
52+
53+
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 a [managed identity](../../active-directory/managed-identities-azure-resources/overview.md). This transition between environments doesn't require any code changes.
54+
55+
### Assign roles to your Microsoft Entra user account
56+
57+
[!INCLUDE [assign-roles](../../../includes/assign-roles.md)]
58+
59+
### Sign-in and connect your app code to Azure using DefaultAzureCredential
60+
61+
You can authorize access to data in your storage account using the following steps:
62+
63+
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:
64+
65+
```azurecli
66+
az login
67+
```
68+
69+
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 variable `QUARKUS_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:
70+
71+
```azurecli
72+
export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
73+
--resource-group <resource-group-name> \
74+
--name <storage-account-name> \
75+
--query 'primaryEndpoints.blob' \
76+
--output tsv)
77+
```
78+
79+
> [!NOTE]
80+
> When deployed to Azure, you need to enable managed identity on your app, and configure your storage account to allow that managed identity to connect. For more information on configuring this connection between Azure services, see [Authenticate Azure-hosted Java applications](/azure/developer/java/sdk/identity-azure-hosted-auth).
81+
82+
## Run the sample
83+
84+
The code example performs the following actions:
85+
86+
- Injects a client object that is already authorized for data access via `DefaultAzureCredential` using the Quarkus extension for Azure Blob Storage.
87+
- Creates a container in a storage account.
88+
- Uploads a blob to the container.
89+
- Lists the blobs in the container.
90+
- Downloads the blob data to the local file system.
91+
- Deletes the blob and container resources created by the app.
92+
- Deletes the local source and downloaded files.
93+
94+
Run the application in JVM mode by using the following command:
95+
96+
```bash
97+
mvn package
98+
java -jar ./target/quarkus-app/quarkus-run.jar
99+
```
100+
101+
The output of the app is similar to the following example (UUID values omitted for readability):
102+
103+
```output
104+
Uploading to Blob storage as blob:
105+
https://mystorageacct.blob.core.windows.net/quickstartblobsUUID/quickstartUUID.txt
106+
107+
Listing blobs...
108+
quickstartUUID.txt
109+
110+
Downloading blob to
111+
./data/quickstartUUIDDOWNLOAD.txt
112+
113+
Press the Enter key to begin clean up
114+
115+
Deleting blob container...
116+
Deleting the local source and downloaded files...
117+
Done
118+
```
119+
120+
Before you begin the cleanup process, check your data folder for the two files. You can compare them and observe that they're identical.
121+
122+
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, see [Building a Native Executable](https://quarkus.io/guides/building-native-image). This quickstart uses Docker as container runtime to build a Linux native executable. If you haven't installed Docker, you can download it from the [Docker website](https://www.docker.com/products/docker-desktop).
123+
124+
Run the following command to build and execute the native executable in a Linux environment:
125+
126+
```bash
127+
mvn package -Dnative -Dquarkus.native.container-build
128+
./target/storage-blob-1.0.0-SNAPSHOT-runner
129+
```
130+
131+
## Understand the sample code
132+
133+
Next, you walk through the sample code to understand how it works.
134+
135+
### Inject a client object with authorized access
136+
137+
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 using `DefaultAzureCredential`.
138+
139+
To successfully inject a client object, first you need to add the extensions `quarkus-arc` and `quarkus-azure-storage-blob` to your **pom.xml** file as dependencies:
140+
141+
```xml
142+
<properties>
143+
<quarkus.platform.version>3.17.7</quarkus.platform.version>
144+
<quarkus.azure.services.version>1.1.1</quarkus.azure.services.version>
145+
</properties>
146+
147+
<dependencyManagement>
148+
<dependencies>
149+
<dependency>
150+
<groupId>io.quarkus.platform</groupId>
151+
<artifactId>quarkus-bom</artifactId>
152+
<version>${quarkus.platform.version}</version>
153+
<type>pom</type>
154+
<scope>import</scope>
155+
</dependency>
156+
<dependency>
157+
<groupId>io.quarkiverse.azureservices</groupId>
158+
<artifactId>quarkus-azure-services-bom</artifactId>
159+
<version>${quarkus.azure.services.version}</version>
160+
<type>pom</type>
161+
<scope>import</scope>
162+
</dependency>
163+
</dependencies>
164+
</dependencyManagement>
165+
166+
<dependencies>
167+
<dependency>
168+
<groupId>io.quarkus</groupId>
169+
<artifactId>quarkus-arc</artifactId>
170+
</dependency>
171+
<dependency>
172+
<groupId>io.quarkiverse.azureservices</groupId>
173+
<artifactId>quarkus-azure-storage-blob</artifactId>
174+
</dependency>
175+
</dependencies>
176+
```
177+
178+
The `quarkus-arc` extension is required to use the `@Inject` annotation to inject the client object into your application code. The `quarkus-bom` and `quarkus-azure-services-bom` dependencies are used to manage the versions of the Quarkus platform and the Quarkus extension for Azure services.
179+
180+
Next, you can inject the client object into your application code using the `@Inject` annotation:
181+
182+
```java
183+
@Inject
184+
BlobServiceClient blobServiceClient;
185+
```
186+
187+
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 section [Authenticate to Azure and authorize access to blob data](#authenticate-to-azure-and-authorize-access-to-blob-data) before running the application.
188+
189+
### Manage blobs and containers
190+
191+
The following code example shows how to create a container, upload a blob, list blobs in a container, and download a blob.
192+
193+
> [!NOTE]
194+
> Writing to the local filesystem is considered a bad practice in cloud native applications. However, the example uses the local filesystem to illustrate the use of blob storage in a way that is easy to for the user to verify. When you take an application to production, review your storage options and choose the best option for your needs. For more information, see [Review your storage options](/azure/architecture/guide/technology-choices/storage-options).
195+
196+
```java
197+
// Create a unique name for the container
198+
String containerName = "quickstartblobs" + java.util.UUID.randomUUID();
199+
200+
// Create the container and return a container client object
201+
BlobContainerClient blobContainerClient = blobServiceClient.createBlobContainer(containerName);
202+
203+
// Create the ./data/ directory and a file for uploading and downloading
204+
String localPath = "./data/";
205+
new File(localPath).mkdirs();
206+
String fileName = "quickstart" + java.util.UUID.randomUUID() + ".txt";
207+
208+
// Get a reference to a blob
209+
BlobClient blobClient = blobContainerClient.getBlobClient(fileName);
210+
211+
// Write text to the file
212+
FileWriter writer = null;
213+
try
214+
{
215+
writer = new FileWriter(localPath + fileName, true);
216+
writer.write("Hello, World!");
217+
writer.close();
218+
}
219+
catch (IOException ex)
220+
{
221+
System.out.println(ex.getMessage());
222+
}
223+
224+
System.out.println("\nUploading to Blob storage as blob:\n\t" + blobClient.getBlobUrl());
225+
226+
// Upload the blob
227+
blobClient.uploadFromFile(localPath + fileName);
228+
229+
System.out.println("\nListing blobs...");
230+
231+
// List the blob(s) in the container.
232+
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
233+
System.out.println("\t" + blobItem.getName());
234+
}
235+
236+
// Download the blob to a local file
237+
238+
// Append the string "DOWNLOAD" before the .txt extension for comparison purposes
239+
String downloadFileName = fileName.replace(".txt", "DOWNLOAD.txt");
240+
241+
System.out.println("\nDownloading blob to\n\t " + localPath + downloadFileName);
242+
243+
blobClient.downloadToFile(localPath + downloadFileName);
244+
245+
File downloadedFile = new File(localPath + downloadFileName);
246+
File localFile = new File(localPath + fileName);
247+
248+
// Clean up resources
249+
System.out.println("\nPress the Enter key to begin clean up");
250+
System.console().readLine();
251+
252+
System.out.println("Deleting blob container...");
253+
blobContainerClient.delete();
254+
255+
System.out.println("Deleting the local source and downloaded files...");
256+
localFile.delete();
257+
downloadedFile.delete();
258+
259+
System.out.println("Done");
260+
```
261+
262+
These operations are similar to the ones described in [Quickstart: Azure Blob Storage client library for Java SE](storage-quickstart-blobs-java.md). For more detailed code explanations, see the following sections in that quickstart:
263+
264+
- [Create a container](storage-quickstart-blobs-java.md#create-a-container)
265+
- [Upload blobs to a container](storage-quickstart-blobs-java.md#upload-blobs-to-a-container)
266+
- [List the blobs in a container](storage-quickstart-blobs-java.md#list-the-blobs-in-a-container)
267+
- [Download blobs](storage-quickstart-blobs-java.md#download-blobs)
268+
- [Delete a container](storage-quickstart-blobs-java.md#delete-a-container)
269+
270+
## Clean up
271+
272+
You can choose to follow the links in the **Next 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, see [Azure Resource Manager resource group and resource deletion](/azure/azure-resource-manager/management/delete-resource-group).
273+
274+
## Next steps
275+
276+
> [!div class="nextstepaction"]
277+
> [Azure Storage samples and developer guides for Java](../common/storage-samples-java.md?toc=/azure/storage/blobs/toc.json)
278+
> [Deploy a Java application with Quarkus on an Azure Kubernetes Service cluster](/azure/aks/howto-deploy-java-quarkus-app)
279+
> [Deploy a Java application with Quarkus on Azure Container Apps](/azure/developer/java/ee/deploy-java-quarkus-app)

‎articles/storage/blobs/storage-quickstart-blobs-java.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ ms.devlang: java
1111
zone_pivot_groups: azure-blob-storage-quickstart-options
1212
---
1313

14-
# Quickstart: Azure Blob Storage client library for Java
14+
# Quickstart: Azure Blob Storage client library for Java SE
1515

1616
::: zone pivot="blob-storage-quickstart-scratch"
1717

@@ -612,3 +612,6 @@ You'll be prompted to confirm the deletion of the resources. Enter `y` to confir
612612

613613
> [!div class="nextstepaction"]
614614
> [Azure Storage samples and developer guides for Java](../common/storage-samples-java.md?toc=/azure/storage/blobs/toc.json)
615+
> [Azure Storage samples and developer guides for Java](../common/storage-samples-java.md?toc=/azure/storage/blobs/toc.json)
616+
> [Quickstart: Quarkus extension for Azure Blob Storage](storage-quickstart-blobs-java-quarkus.md)
617+
> [Use Spring Boot to upload a file to Azure Blob Storage](/azure/developer/java/spring-framework/configure-spring-boot-starter-java-app-with-azure-storage?toc=/azure/storage/blobs/toc.json)

‎includes/assign-roles.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ ms.author: alexwolf
1010
ms.custom: include file
1111
---
1212

13-
When developing locally, make sure that the user account that is accessing blob data has the correct permissions. You'll need **Storage Blob Data Contributor** to read and write blob data. To assign yourself this role, you'll need to be assigned the **User Access Administrator** role, or another role that includes the **Microsoft.Authorization/roleAssignments/write** action. You can assign Azure RBAC roles to a user using the Azure portal, Azure CLI, or Azure PowerShell. You can learn more about the available scopes for role assignments on the [scope overview](../articles/role-based-access-control/scope-overview.md) page.
13+
When developing locally, make sure that the user account that is accessing blob data has the correct permissions. You'll need **Storage Blob Data Contributor** to read and write blob data. To assign yourself this role, you'll need to be assigned the **User Access Administrator** role, or another role that includes the **Microsoft.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 the **Storage Blob Data Contributor** role, see [Storage Blob Data Contributor](/azure/role-based-access-control/built-in-roles/storage#storage-blob-data-contributor). For more information about the available scopes for role assignments, see [Understand scope for Azure RBAC](../articles/role-based-access-control/scope-overview.md).
1414

1515
In this scenario, you'll assign permissions to your user account, scoped to the storage account, to follow the [Principle of Least Privilege](../articles/active-directory/develop/secure-least-privileged-access.md). This practice gives users only the minimum permissions needed and creates more secure production environments.
1616

0 commit comments

Comments
 (0)