Démarrage rapide : Bibliothèque cliente de Stockage Blob Azure pour Java SE

Remarque

L’option Build from Scratch vous guide dans la création d’un projet, l’installation de paquets, l’écriture de code et l’exécution d’une application console basique. Choisissez cette option pour comprendre comment créer une application qui se connecte à Stockage Blob Azure. Pour automatiser les tâches de déploiement et commencer par un projet terminé, choisissez Commencer avec un modèle.

Remarque

L’option Start with a Template utilise la CLI Azure Developer pour automatiser les tâches de déploiement et fournit un projet terminé. Choisissez cette option pour explorer le code sans avoir terminé les tâches de configuration. Pour des instructions étape par étape pour construire l’application, choisissez Construire à partir de zéro.

Commencez à utiliser la bibliothèque de client Stockage Blob Azure pour Java pour gérer les objets blob et les conteneurs.

Dans cet article, vous suivez les étapes pour installer le package et essayer l’exemple de code pour les tâches de base.

Dans cet article, vous utilisez Azure Developer CLI pour déployer des ressources Azure et exécuter une application console terminée en quelques commandes seulement.

Conseil

Pour les applications Spring qui utilisent les ressources stockage Azure, considérez Spring Cloud Azure. Ce projet open source intègre Spring avec les services Azure. Pour un exemple de Stockage Blob, voir Uploader un fichier vers un stockage Azure Blob.

Documentation de référence sur l’API | Code source de la bibliothèque | Package (Maven) | Exemples

Prérequis

Configuration

Cette section vous guide tout au long de la préparation d’un projet à utiliser avec la bibliothèque de client Stockage Blob Azure pour Java.

Créer le projet

Créez une application Java nommée blob-quickstart.

  1. Dans une fenêtre de console (par exemple, PowerShell ou Bash), utilisez Maven pour créer une application console nommée blob-quickstart. Tapez la commande mvn suivante pour créer un projet Java « Hello world! ».

    mvn archetype:generate `
    --define interactiveMode=n `
    --define groupId=com.blobs.quickstart `
    --define artifactId=blob-quickstart `
    --define archetypeArtifactId=maven-archetype-quickstart `
    --define archetypeVersion=1.4

  2. Examinez les résultats issus de la génération du projet.

    [INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/blobs/quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Project created from Archetype in dir: C:\QuickStarts\blob-quickstart
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  7.056 s
[INFO] Finished at: 2019-10-23T11:09:21-07:00
[INFO] ------------------------------------------------------------------------
    ```

  3. Basculez vers le dossier blob-quickstart nouvellement créé.

    cd blob-quickstart

  4. Dans le répertoire blob-quickstart , créez un autre répertoire appelé data. Ce dossier est l’endroit où les fichiers de données blob sont créés et stockés.

    mkdir data

Installer les packages

Ouvrez le fichier pom.xml dans votre éditeur de texte.

Ajoutez azure-sdk-bom pour établir une dépendance sur la dernière version de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. En utilisant azure-sdk-bom, vous n’avez pas besoin de spécifier la version de chaque dépendance individuelle. Pour en savoir plus sur la BOM, consultez le README de la BOM du SDK Azure.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Ajoutez ensuite les éléments dependency suivants au groupe de dépendances. Vous avez besoin de la dépendance Azure-identity pour les connexions sans mot de passe aux services Azure.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Configurer le framework d’application

À partir du répertoire du projet, procédez comme suit pour créer la structure de base de l’application :

  1. Accédez au répertoire /src/main/java/com/blobs/quickstart.
  2. Ouvrez le fichier App.java dans votre éditeur.
  3. Supprimez la ligne System.out.println("Hello world!");
  4. Ajoutez les directives import requises

Le code doit ressembler à ce framework :

package com.blobs.quickstart;

/**
 * Azure Blob Storage quickstart
 */
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

En utilisant la CLI Azure Developer, vous pouvez créer un compte de stockage et exécuter le code d’exemple avec seulement quelques commandes. Vous pouvez faire tourner le projet dans votre environnement de développement local ou dans un DevContainer.

Initialiser le modèle Azure Developer CLI et déployer des ressources

À partir d’un répertoire vide, procédez comme suit pour initialiser le modèle azd, approvisionner des ressources Azure et commencer à utiliser le code :

  • Clonez les ressources du référentiel de démarrage rapide à partir de GitHub et initialisez le modèle localement :

    azd init --template blob-storage-quickstart-java

    Vous êtes invité à entrer les informations suivantes :

    • Environment name : Azure Developer CLI utilise cette valeur comme préfixe pour toutes les ressources Azure qu’elle crée. Le nom doit être unique dans tous les abonnements Azure et comporter entre 3 et 24 caractères. Le nom peut contenir uniquement des chiffres et des lettres minuscules.

  • Connectez-vous à Azure :

    azd auth login

  • Approvisionnez et déployez les ressources sur Azure :

    azd up

    Vous êtes invité à entrer les informations suivantes :

    • Abonnement : L’abonnement Azure pour déployer vos ressources.
    • Emplacement : La région Azure pour déployer vos ressources.

    Le déploiement peut prendre quelques minutes. La sortie de la azd up commande inclut le nom du compte de stockage nouvellement créé, dont vous avez besoin ultérieurement pour exécuter le code.

Exécuter l’exemple de code

À ce stade, les ressources sont déployées sur Azure et le code est presque prêt à être exécuté. Suivez ces étapes pour mettre à jour le nom du compte de stockage dans le code et exécuter l’exemple d’application console :

  • Mettre à jour le nom du compte de stockage:
    1. Dans le répertoire local, accédez au répertoire blob-quickstart/src/main/java/com/blobs/quickstart .
    2. Ouvrez le fichier nommé App.java dans votre éditeur. Recherchez l’espace réservé <storage-account-name> et remplacez-le par le nom réel du compte de stockage créé par la commande azd up.
    3. Enregistrez les modifications.
  • Exécutez le projet :
    1. Naviguez jusqu’au répertoire blob-quickstart contenant le fichier pom.xml. Compilez le projet à l’aide de la commande mvn suivante : 
      mvn compile
    2. Empaquetez le code compilé dans son format distribuable : 
      mvn package
    3. Exécutez la commande mvn suivante pour exécuter l’application : 
      mvn exec:java
  • Observez la sortie : cette application crée un fichier de test dans votre dossier local data et le charge dans un conteneur du compte de stockage. L’exemple liste ensuite les objets blob du conteneur et télécharge le fichier avec un nouveau nom pour que vous puissiez comparer les deux fichiers.

Pour en savoir plus sur le fonctionnement de l’exemple de code, consultez la section Exemples de code.

Une fois que vous avez terminé de tester le code, consultez la section Nettoyer les ressources pour supprimer les ressources créées par la commande azd up.

Modèle objet

Stockage Blob Azure est optimisé pour stocker des quantités massives de données non structurées. Les données non structurées n’obéissent pas à un modèle ou une définition de données en particulier, comme des données texte ou binaires. Le stockage Blob offre trois types de ressources :

  • Le compte de stockage
  • Un conteneur dans le compte de stockage.
  • Un blob dans le conteneur

Le diagramme suivant montre la relation entre ces ressources.

Diagramme montrant un compte de stockage contenant un conteneur de blob et un blob.

Utilisez les classes Java suivantes pour interagir avec ces ressources :

  • BlobServiceClient : La BlobServiceClient classe gère les ressources stockage Azure et les conteneurs blob. Le compte de stockage fournit l’espace de noms de niveau supérieur pour le service BLOB.
  • BlobServiceClientBuilder : La BlobServiceClientBuilder classe fournit une API fluide pour configurer et créer BlobServiceClient des objets.
  • BlobContainerClient : La BlobContainerClient classe gère les conteneurs stockage Azure et leurs blobs.
  • BlobClient : La BlobClient classe gère les blobs stockage Azure.
  • BlobItem : La classe BlobItem représente des objets blob retournés par un appel à listBlobs.

Exemples de code

Ces exemples d’extraits de code vous montrent comment effectuer les actions suivantes avec la bibliothèque de client Stockage Blob Azure pour Java :

Important

Ajoutez les dépendances et directives décrites dans la configuration avant d’utiliser les exemples de code.

Remarque

Le modèle Azure Developer CLI inclut un fichier contenant déjà un exemple de code. Les exemples suivants fournissent des détails pour chaque partie de l’exemple de code. Le modèle implémente la méthode d’authentification sans mot de passe recommandée, comme décrit dans la section S’authentifier auprès d’Azure. La méthode de chaîne de connexion est présentée comme une alternative, mais elle n’est pas utilisée dans le modèle et n’est pas recommandée pour le code de production.

S’authentifier auprès d’Azure et autoriser l’accès aux données blob

Les demandes d’application vers le Stockage Blob Azure doivent être autorisées. L’utilisation de la classe DefaultAzureCredential fournie par la bibliothèque de client Azure Identity est l’approche recommandée pour implémenter des connexions sans mot de passe aux services Azure dans votre code, y compris le Stockage Blob.

Vous pouvez également autoriser les demandes vers le Stockage Blob Azure à l’aide de la clé d’accès au compte. Toutefois, cette approche doit être utilisée avec prudence. Les développeurs doivent être vigilants pour ne jamais exposer la clé d’accès dans un emplacement non sécurisé. Toute personne disposant de la clé d’accès est en mesure d’autoriser les demandes sur le compte de stockage et a accès efficacement à toutes les données. DefaultAzureCredential offre des avantages améliorés en matière de gestion et de sécurité par rapport à la clé de compte pour autoriser l’authentification sans mot de passe. Les deux options sont illustrées dans l’exemple suivant.

DefaultAzureCredential est une classe fournie par la bibliothèque de client 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 ou production) sans implémenter de code spécifique à l’environnement.

Vous trouverez l’ordre et les emplacements où DefaultAzureCredential recherche des informations d’identification dans la vue d’ensemble de la bibliothèque d’identités Azure.

Par exemple, votre application peut s’authentifier en utilisant vos identifiants de connexion Visual Studio Code lors du développement local. Votre application pourra alors utiliser une identité gérée après le déploiement sur Azure. Aucune modification du code n’est requise pour cette transition.

Attribuer des rôles à votre compte d’utilisateur Microsoft Entra

Lors du développement local, assurez-vous que le compte d’utilisateur qui accède aux données blob dispose des autorisations appropriées. Vous aurez besoin du Contributeur aux données Blob de stockage 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 à l’aide du 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, étendues au compte de stockage, pour suivre le Principe des privilèges 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 attribue le rôle Storage Blob Data Contributor à votre compte utilisateur, ce qui fournit à la fois un accès en lecture et en écriture aux données 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.

  1. Dans le Portail Azure, recherchez votre compte de stockage à l’aide de la barre de recherche principale ou de la navigation gauche.

  2. Dans la page vue d’ensemble du compte de stockage, sélectionnez Contrôle d’accès (IAM) dans le menu de gauche.

  3. Sur la page Contrôle d’accès (IAM), sélectionnez l’onglet Attributions de rôles.

  4. Sélectionnez + Ajouter dans le menu supérieur, puis Ajouter une attribution de rôle dans le menu déroulant résultant.

    Capture d’écran montrant comment attribuer un rôle.

  5. Utilisez la zone de recherche pour filtrer les résultats sur le rôle souhaité. Dans cet exemple, recherchez Storage Blob Data Contributor, puis sélectionnez le résultat correspondant et choisissez Suivant.

  6. Sous Attribuer l’accès à, sélectionnez Utilisateur, groupe ou principal de service, puis sélectionnez + Sélectionner des membres.

  7. Dans la boîte de dialogue, recherchez votre nom d’utilisateur Microsoft Entra (généralement votre adresse e-mail utilisateur@domaine), puis choisissez Sélectionner en bas de la boîte de dialogue.

  8. Sélectionnez Vérifier + affecter pour accéder à la page finale, puis Vérifier + attribuer à nouveau pour terminer le processus.

Connectez-vous et connectez votre code d’application à Azure à l’aide de DefaultAzureCredential

Autorisez l’accès aux données de votre compte de stockage en suivant ces étapes :

  1. Authentification en utilisant le même compte Microsoft Entra auquel vous avez attribué le rôle de compte de stockage. Utilisez Azure CLI, Visual Studio Code ou Azure PowerShell.

    Connectez-vous à Azure via Azure CLI à l’aide de la commande suivante :

    az login

  2. Pour utiliser DefaultAzureCredential, ajoute la dépendance azure-identity à pom.xml:

    <dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
</dependency>

  3. Ajoutez ce code à la méthode main. Lorsque le code s'exécute sur votre poste de travail local, il utilise les identifiants développeur de l'outil priorisé auquel vous êtes connecté pour s'authentifier à Azure, comme Azure CLI ou Visual Studio Code.

    /*
 * The default credential first checks environment variables for configuration
 * If environment configuration is incomplete, it will try managed identity
 */
DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(defaultCredential)
        .buildClient();

  4. Mettez à jour le nom du compte de stockage dans l’URI de votre BlobServiceClient. Trouvez le nom du compte de stockage sur la page d’aperçu du portail Azure.

    Capture d’écran montrant comment trouver le nom du compte de stockage.

    Remarque

    Lorsqu’il est déployé sur Azure, ce même code peut être utilisé pour autoriser les demandes adressées à Stockage Azure à partir d’une application s’exécutant dans Azure. Toutefois, vous devez activer l’identité managée sur votre application dans Azure. Configurez ensuite votre compte de stockage pour autoriser cette identité managée à se connecter. Pour obtenir des instructions détaillées sur la configuration de cette connexion entre les services Azure, consultez le didacticiel d’authentification à partir d’applications hébergées sur Azure .

Créez un conteneur.

Créez un conteneur dans votre compte de stockage en appelant la méthode createBlobContainer sur l’objet blobServiceClient. Dans cet exemple, le code ajoute une valeur GUID au nom du conteneur pour s’assurer qu’il est unique.

Ajoutez ce code à la fin de la méthode main :

// 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);

Pour plus d’informations et d’exemples, voir Créer un conteneur de blob avec Java.

Important

Les noms de conteneurs doivent être en minuscules. Pour plus d’informations sur l’affectation de noms aux conteneurs et objets blob, consultez Affectation de noms et références aux conteneurs, objets blob et métadonnées.

Télécharger des blobs dans un conteneur

Chargez un objet blob dans un conteneur en appelant la méthode uploadFromFile. L’exemple de code crée un fichier texte dans le répertoire de données local à charger dans le conteneur.

Ajoutez ce code à la fin de la méthode main :

// 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);

Pour plus d’informations et d’exemples, voir Télécharger un blob avec Java.

Créer la liste des objets blob d’un conteneur

Répertoriez les objets Blob dans le conteneur en appelant la méthode list_Blobs. Dans ce cas, vous n’avez ajouté qu’un seul blob au conteneur, donc l’opération de listing ne retourne qu’un seul blob.

Ajoutez ce code à la fin de la méthode main :

System.out.println("\nListing blobs...");

// List the blob(s) in the container.
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("\t" + blobItem.getName());
}

Pour plus d’informations et d’exemples, voir Liste de blobs avec Java.

Télécharger des blobs

Téléchargez l’objet blob créé précédemment en appelant la méthode downloadToFile. Le code d’exemple ajoute un suffixe de DOWNLOAD au nom du fichier afin que vous puissiez voir les deux fichiers dans le système de fichiers local.

Ajoutez ce code à la fin de la méthode main :

// 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);

Pour plus d’informations et d’exemples, voir Télécharger un blob avec Java.

Supprimer un conteneur

Le code suivant nettoie les ressources créées par l’application en supprimant tout le conteneur en utilisant la méthode de suppression . Il supprime également les fichiers locaux créés par l’application.

L’application se met en pause en attendant une saisie de l’utilisateur lors de l’appel à System.console().readLine() avant de supprimer le blob, le conteneur et les fichiers locaux. Cette pause vous donne l’occasion de vérifier que l’application a correctement créé les ressources avant de les supprimer.

Ajoutez ce code à la fin de la méthode main :

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");

Pour plus d’informations et d’exemples, voir Supprimer et restaurer un conteneur blob avec Java.

Exécuter le code

Cette application crée un fichier de test dans votre dossier local et le charge sur un stockage blob. L’exemple liste ensuite les objets blob du conteneur et télécharge le fichier avec un nouveau nom pour que vous puissiez comparer les deux fichiers.

Suivez ces étapes pour compiler, empaqueter et exécuter le code :

  1. Accédez au répertoire contenant le fichier pom.xml, puis compilez le projet à l’aide de la commande mvn suivante : 
    mvn compile
  2. Empaquetez le code compilé dans son format distribuable : 
    mvn package
  3. Exécutez la commande mvn suivante pour exécuter l’application : 
    mvn exec:java -D exec.mainClass=com.blobs.quickstart.App -D exec.cleanupDaemonThreads=false
    Pour simplifier l’étape d’exécution, ajoutez-la exec-maven-pluginpom.xml et configurez-la comme indiqué dans le code suivant : 
    <plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <version>1.4.0</version>
  <configuration>
    <mainClass>com.blobs.quickstart.App</mainClass>
    <cleanupDaemonThreads>false</cleanupDaemonThreads>
  </configuration>
</plugin>
    Avec cette configuration, exécutez l’application avec la commande suivante : 
    mvn exec:java

La sortie de l’application est similaire à l’exemple suivant (valeurs UUID omises pour une meilleure lisibilité) :

Azure Blob Storage - Java quickstart sample

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 la présence des deux fichiers dans votre dossier data. Vous pouvez les comparer et constater qu’ils sont identiques.

Nettoyer les ressources

Après avoir vérifié les fichiers et terminé le test, appuyez sur Entrée pour supprimer les fichiers de test ainsi que le conteneur que vous avez créé dans le compte de stockage. Vous pouvez également utiliser Azure CLI pour supprimer des ressources.

Lorsque vous avez terminé avec le démarrage rapide, nettoyez les ressources que vous avez créées en exécutant la commande suivante :

azd down

Vous êtes invité à confirmer la suppression des ressources. Entrez y pour confirmer.

Étape suivante

Exemples stockage Azure et guides de développement pour JavaDémarrage rapide : extension Quarkus pour Stockage Blob AzureUtiliser Spring Boot pour charger un fichier dans Stockage Blob Azure

  • Last updated on