Note
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier les répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de changer de répertoire.
Commencez avec l’extension Quarkus pour Azure Blob Storage afin de gérer les blobs et les conteneurs. Dans cet article, vous suivez les étapes pour tester des exemples de code pour les tâches de base.
Documentation de référence | Code source | Package (Maven) | Exemple
Prerequisites
- Compte Azure avec un abonnement actif : créez un compte gratuitement.
- Azure CLI - Installez Azure CLI 2.62.0 ou version ultérieure pour exécuter des commandes Azure CLI.
- Compte de stockage Azure : créez un compte de stockage.
- Java Development Kit (JDK) version 17 ou ultérieure.
- Apache Maven.
Configuration
Cette section vous guide dans la préparation d'un projet pour travailler avec les extensions Quarkus pour le stockage Blob Azure.
Télécharger l’exemple d’application
L’exemple d’application utilisé dans ce quickstart est une application Quarkus de base.
Utilisez git pour télécharger une copie de l’application dans votre environnement de développement, puis accédez au storage-blob-quarkus répertoire.
git clone https://github.com/Azure-Samples/quarkus-azure.git
cd quarkus-azure
git checkout 2025-01-20
cd storage-blob-quarkus
S’authentifier auprès d’Azure et autoriser l’accès aux données blob
Les demandes d’application adressées au Stockage Blob Azure doivent être autorisées. L’utilisation DefaultAzureCredential et la bibliothèque de client Azure Identity sont l’approche recommandée pour implémenter des connexions sans mot de passe aux services Azure dans votre code, y compris le stockage Blob. L’extension Dockerus pour les services Azure prend en charge cette approche.
DefaultAzureCredential est une implémentation de chaîne d’informations d’identification fournie par la bibliothèque cliente Azure Identity pour Java.
DefaultAzureCredential prend en charge plusieurs méthodes d’authentification et détermine quelle méthode doit être utilisée au moment de l’exécution. Cette approche permet à votre application d’utiliser différentes méthodes d’authentification dans différents environnements (local et production) sans implémenter de code spécifique à l’environnement.
L'ordre et les emplacements dans lesquels DefaultAzureCredential cherche les informations d'identification peuvent être trouvés dans la vue d'ensemble de la bibliothèque d'identité Azure.
Dans ce guide de démarrage rapide, votre application s’authentifie à l’aide de vos informations d’identification de connexion Azure CLI lors de l’exécution locale. Une fois qu’elle a été déployée sur Azure, votre application peut ensuite utiliser une identité managée. Cette transition entre les environnements ne nécessite aucune modification du code.
Attribuer des rôles à votre compte d’utilisateur Microsoft Entra
Lors du développement localement, assurez-vous que le compte d’utilisateur qui accède aux données d’objet blob dispose des autorisations appropriées. Vous aurez besoin de Storage Blob Data Contributor pour lire et écrire des données blob. Pour vous attribuer ce rôle, vous aurez besoin du rôle Administrateur de l’accès utilisateur ou d’un autre rôle qui inclut l’action Microsoft.Authorization/roleAssignments/write. Vous pouvez attribuer des rôles RBAC Azure à un utilisateur en utilisant le Portail Azure, Azure CLI ou Azure PowerShell. Pour plus d’informations sur le rôle Contributeur aux données Blob de stockage, consultez Contributeur aux données Blob de stockage. Pour plus d’informations sur les étendues disponibles pour les attributions de rôles, consultez Comprendre l’étendue du RBAC Azure.
Dans ce scénario, vous allez attribuer des autorisations à votre compte d’utilisateur, délimité au compte de stockage, pour suivre le principe du privilège minimum. Cette pratique offre aux utilisateurs uniquement les autorisations minimales nécessaires et crée des environnements de production plus sécurisés.
L’exemple suivant affecte le rôle Contributeur aux données d'objets blob de stockage à votre compte d’utilisateur, qui fournit à la fois un accès en lecture et en écriture aux données d'objets blob dans votre compte de stockage.
Important
Dans la plupart des cas, la propagation de l’attribution de rôle dans Azure peut prendre une ou deux minutes, mais dans de rares cas, cela peut prendre jusqu’à huit minutes. Si vous recevez des erreurs d’authentification lorsque vous exécutez votre code pour la première fois, patientez quelques instants et réessayez.
Dans le Portail Azure, recherchez votre compte de stockage à l’aide de la barre de recherche principale ou de la navigation gauche.
Dans la page vue d’ensemble du compte de stockage, sélectionnez Contrôle d’accès (IAM) dans le menu de gauche.
Dans la page Contrôle d’accès (IAM), sélectionnez l’onglet Attributions de rôle.
Sélectionnez + Ajouter dans le menu supérieur, puis ajoutez l’attribution de rôle dans le menu déroulant résultant.
Utilisez la zone de recherche pour filtrer les résultats selon le rôle souhaité. Pour cet exemple, recherchez Contributeur aux données Blob du stockage, sélectionnez le résultat correspondant, puis choisissez Suivant.
Sous Attribuer l’accès à, sélectionnez Utilisateur, groupe ou principal de service, puis sélectionnez + Sélectionner des membres.
Dans la boîte de dialogue, recherchez votre nom d’utilisateur Microsoft Entra (généralement votre adresse e-mail user@domain), puis choisissez Sélectionner en bas de la boîte de dialogue.
Sélectionnez Vérifier + attribuer pour accéder à la page finale, puis sélectionnez à nouveau Vérifier + attribuer pour terminer le processus.
Connectez-vous et connectez votre code d’application à Azure à l’aide de DefaultAzureCredential
Vous pouvez autoriser l’accès aux données dans votre compte de stockage en procédant comme suit :
Vérifiez que vous êtes authentifié avec le même compte Microsoft Entra auquel vous avez affecté le rôle sur votre compte de stockage. L’exemple suivant montre comment s’authentifier via Azure CLI :
az loginVeillez à fournir le point de terminaison de votre compte Stockage Blob Azure. L’exemple suivant montre comment définir le point de terminaison à l’aide de la variable
QUARKUS_AZURE_STORAGE_BLOB_ENDPOINTd’environnement via Azure CLI. Remplacez<resource-group-name>et<storage-account-name>par les noms de votre groupe de ressources et de votre compte de stockage avant d’exécuter la commande :export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \ --resource-group <resource-group-name> \ --name <storage-account-name> \ --query 'primaryEndpoints.blob' \ --output tsv)
Note
Une fois déployé sur Azure, vous devez activer l’identité managée sur votre application et configurer votre compte de stockage pour autoriser cette identité managée à se connecter. Pour plus d’informations sur la configuration de cette connexion entre les services Azure, consultez Authentifier les applications Java hébergées par Azure.
Exécuter l’exemple
L’exemple de code effectue les actions suivantes :
- Injecte un objet client déjà autorisé pour l’accès aux données via
DefaultAzureCredentialà l’aide de l’extension Quarkus pour le stockage Blob Azure. - Crée un conteneur dans un compte de stockage.
- Charge un objet blob dans le conteneur.
- Répertorie les objets blob dans le conteneur.
- Télécharge les données d’objet blob dans le système de fichiers local.
- Supprime les ressources blob et conteneur créées par l’application.
- Supprime la source locale et les fichiers téléchargés.
Exécutez l’application en mode JVM à l’aide de la commande suivante :
mvn package
java -jar ./target/quarkus-app/quarkus-run.jar
La sortie de l’application est similaire à l’exemple suivant (valeurs UUID omises pour la lisibilité) :
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
Avant de commencer le processus de nettoyage, vérifiez votre dossier de données pour les deux fichiers. Vous pouvez les comparer et observer qu’ils sont identiques.
Si vous le souhaitez, vous pouvez exécuter l’exemple en mode natif. Pour ce faire, vous devez installer GraalVM ou utiliser une image de générateur pour générer l’exécutable natif. Pour plus d’informations, consultez Génération d’un exécutable natif. Ce guide de démarrage rapide utilise Docker comme runtime de conteneur pour générer un exécutable natif Linux. Si vous n’avez pas installé Docker, vous pouvez le télécharger à partir du site web Docker.
Exécutez la commande suivante pour générer et exécuter l’exécutable natif dans un environnement Linux :
mvn package -Dnative -Dquarkus.native.container-build
./target/storage-blob-1.0.0-SNAPSHOT-runner
Comprendre l’exemple de code
Ensuite, vous parcourez l’exemple de code pour comprendre son fonctionnement.
Injecter un objet client avec un accès autorisé
L’utilisation de n’importe quelle ressource Azure à l’aide du Kit de développement logiciel (SDK) commence par la création d’un objet client. L’extension Quarkus pour Stockage Blob Azure injecte automatiquement un objet client avec un accès autorisé à l’aide de DefaultAzureCredential.
Pour injecter un objet client, vous devez d’abord ajouter les extensions quarkus-arc et quarkus-azure-storage-blob votre fichier pom.xml en tant que dépendances :
<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>
L’extension quarkus-arc est nécessaire pour utiliser l’annotation @Inject pour injecter l’objet client dans votre code d’application. Les dépendances quarkus-bom et quarkus-azure-services-bom sont utilisées pour gérer les versions de la plateforme Quarkus et de l'extension Quarkus pour les services Azure.
Ensuite, vous pouvez injecter l’objet client dans votre code d’application à l’aide de l’annotation @Inject :
@Inject
BlobServiceClient blobServiceClient;
C’est tout ce que vous devez coder pour obtenir un objet client à l’aide de l’extension Quarkus pour Azure Blob Storage. Pour vous assurer que l’objet client est autorisé à accéder à votre compte de stockage au moment de l’exécution, vous devez suivre les étapes décrites dans la section précédente S’authentifier auprès d’Azure et autoriser l’accès aux données blob avant d’exécuter l’application.
Gérer les objets blob et les conteneurs
L’exemple de code suivant montre comment créer un conteneur, charger un objet blob, répertorier des objets blob dans un conteneur et télécharger un objet blob.
Note
L’écriture dans le système de fichiers local est considérée comme une mauvaise pratique dans les applications natives cloud. Toutefois, l’exemple utilise le système de fichiers local pour illustrer l’utilisation du stockage d’objets blob de manière facile à vérifier pour l’utilisateur. Lorsque vous effectuez une application en production, passez en revue vos options de stockage et choisissez la meilleure option pour vos besoins. Pour plus d’informations, consultez Consulter vos options de stockage.
// 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");
Ces opérations sont similaires à celles décrites dans le guide de démarrage rapide : bibliothèque de client Stockage Blob Azure pour Java SE. Pour obtenir des explications de code plus détaillées, consultez les sections suivantes de ce guide de démarrage rapide :
- Créer un conteneur
- Télécharger des blobs dans un conteneur
- Lister les blobs dans un conteneur
- Télécharger des blobs
- Supprimer un conteneur
Nettoyage
Vous pouvez choisir de suivre les liens de la section Étapes suivantes pour déployer l’application Quarkus sur Azure. Vous pouvez également nettoyer le compte de stockage en supprimant le groupe de ressources. Pour plus d’informations, consultez le groupe de ressources Azure Resource Manager et la suppression de ressources.