Gérer les propriétés et les métadonnées blob avec Java

  • Article

En plus des données qu’ils contiennent, les blobs prennent en charge des propriétés système et des métadonnées définies par l’utilisateur. Cet article explique comment gérer les propriétés système et les métadonnées définies par l’utilisateur avec la bibliothèque de client du Stockage Azure pour Java.

Prérequis

Paramétrer votre environnement

Si vous n’avez pas de projet existant, cette section vous montre comment configurer un projet pour qu’il fonctionne avec la bibliothèque de client Stockage Blob Azure pour Java. Pour plus d’informations, consultez Bien démarrer avec Stockage Blob Azure et Java.

Pour utiliser les exemples de code de cet article, effectuez les étapes suivantes pour configurer votre projet.

Remarque

Cet article utilise l’outil de génération Maven pour générer et exécuter l’exemple de code. D’autres outils de génération, comme Gradle, fonctionnent également avec le Kit de développement logiciel (SDK) Azure pour Java.

Installer des packages

Ouvrez le fichier pom.xml dans votre éditeur de texte. Installez les packages en incluant le fichier de marque d’ordre d’octet ou en incluant une dépendance directe.

Ajouter des instructions import

Ajoutez les instructions import suivantes :

import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;

import java.util.*;

Autorisation

Le mécanisme d’autorisation doit disposer des autorisations nécessaires pour travailler avec les propriétés ou les métadonnées du conteneur. Pour l’autorisation avec Microsoft Entra ID (recommandé), vous devez disposer au minimum du rôle RBAC Azure intégré Lecteur des données Blob du stockage pour les opérations get et au minimum Contributeur aux données Blob du stockage pour les opérations set. Pour en savoir plus, consultez l’aide sur l’autorisation pour les opérations Set Blob Properties (API REST), Get Blob Properties (API REST), Set Blob Metadata (API REST) ou Get Blob Metadata (API REST).

Créer un objet client

Pour connecter une application au Stockage Blob, créez une instance de BlobServiceClient.

L’exemple suivant utilise BlobServiceClientBuilder pour générer un objet BlobServiceClient en utilisant DefaultAzureCredential, et montre comment créer si nécessaire des clients de conteneur et de blob :

// 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(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

Pour en savoir plus sur la création et la gestion d’objets clients, consultez Créer et gérer des objets clients qui interagissent avec des ressources de données.

À propos des propriétés et des métadonnées

  • Propriétés système : Propriétés système existant sur chaque ressource de stockage blob. Certaines d'entre elles peuvent être lues ou configurées, alors que d'autres sont en lecture seule. En arrière-plan, certaines propriétés système correspondent à certains en-têtes HTTP standard. La bibliothèque de client du Stockage Azure pour Java gère ces propriétés pour vous.

  • Métadonnées définies par l’utilisateur : ces métadonnées se composent d’une ou plusieurs paires nom/valeur, que vous spécifiez pour une ressource de stockage d’objets blob. Vous pouvez les utiliser pour stocker des valeurs supplémentaires avec la ressource. Les valeurs de métadonnées sont destinées à votre usage personnel et n’affectent pas le comportement de la ressource.

    Les paires nom/valeur de métadonnées sont des en-têtes HTTP valides ; elles doivent donc respecter toutes les restrictions régissant les en-têtes HTTP. Pour plus d’informations sur les exigences de nommage des métadonnées, consultez Noms des métadonnées.

Notes

Les étiquettes d’index d’objet blob permettent également de stocker des attributs clé/valeur arbitraires définis par l’utilisateur en même temps qu’une ressource de stockage d’objet Azure Blob. Bien que similaires à des métadonnées, seules les étiquettes d’index d’objet blob sont indexées automatiquement et peuvent être interrogées par le service blob natif. Les métadonnées ne peuvent pas être indexées et interrogées, sauf si vous utilisez un service distinct, tel que Recherche Azure.

Pour en savoir plus sur cette fonctionnalité, consultez Gérer et rechercher des données dans Stockage Blob Azure avec Blob Index.

Définir et récupérer des propriétés

Pour définir des propriétés sur un objet blob, utilisez la méthode suivante :

L’exemple de code suivant définit les propriétés système ContentType et ContentLanguage sur un blob.

Toutes les propriétés qui ne sont pas explicitement définies sont effacées. L’exemple de code suivant obtient d’abord les propriétés existantes sur l’objet blob, puis les utilise pour remplir les en-têtes qui ne sont pas mis à jour.

public void setBlobProperties(BlobClient blobClient) {
    BlobProperties properties = blobClient.getProperties();

    // Set the ContentLanguage and ContentType headers, and populate the remaining
    // headers from the existing properties
    BlobHttpHeaders blobHeaders = new BlobHttpHeaders()
            .setContentLanguage("en-us")
            .setContentType("text/plain")
            .setCacheControl(properties.getCacheControl())
            .setContentDisposition(properties.getContentDisposition())
            .setContentEncoding(properties.getContentEncoding())
            .setContentMd5(properties.getContentMd5());

    blobClient.setHttpHeaders(blobHeaders);
    System.out.println("Set HTTP headers completed");
}

Pour récupérer des propriétés sur un objet blob, utilisez la méthode suivante :

L’exemple de code suivant obtient les propriétés système d’un blob et affiche certaines des valeurs suivantes :

public void getBlobProperties(BlobClient blobClient) {
    BlobProperties properties = blobClient.getProperties();

    System.out.printf("BlobType: %s%n", properties.getBlobType());
    System.out.printf("BlobSize: %d%n", properties.getBlobSize());
    System.out.printf("ContentLanguage: %s%n", properties.getContentLanguage());
    System.out.printf("ContentType: %s%n", properties.getContentType());
}

Définir et récupérer des métadonnées

Vous pouvez indiquer des métadonnées sous la forme de paires nom-valeur sur une ressource d’objet blob ou de conteneur. Pour définir des métadonnées, envoyez un objet Mappage contenant des paires nom-valeur utilisant la méthode suivante :

L’exemple de code suivant définit les métadonnées d’un blob :

public void addBlobMetadata(BlobClient blobClient) {
    Map<String, String> metadata = new HashMap<String, String>();
    metadata.put("docType", "text");
    metadata.put("category", "reference");

    try {
        blobClient.setMetadata(metadata);
        System.out.printf("Set metadata completed %n");
    } catch (UnsupportedOperationException error) {
        System.out.printf("Failure while setting metadata %n");
    }
}

Pour récupérer des métadonnées, appelez la méthode getProperties sur votre objet blob pour remplir la collection de métadonnées, puis lisez les valeurs, comme indiqué dans l’exemple suivant. La méthode getProperties récupère les propriétés et les métadonnées de l’objet blob en appelant à la fois l’opération Obtenir les propriétés d’un objet blob et l’opération Obtenir les métadonnées d’un objet blob.

L’exemple de code suivant lit les métadonnées d’un objet blob et imprime chaque paire clé/valeur :

public void readBlobMetadata(BlobClient blobClient) {
    // Get blob properties and metadata
    BlobProperties properties = blobClient.getProperties();

    System.out.printf("Blob metadata: %n");
    properties.getMetadata().entrySet().forEach(metadataItem -> {
        System.out.printf(" %s = %s%n", metadataItem.getKey(), metadataItem.getValue());
    });
}

Ressources

Pour en savoir plus sur la gestion des propriétés système et des métadonnées définies par l’utilisateur à l’aide de la bibliothèque cliente Stockage Blob Azure pour Java, consultez les ressources suivantes.

Exemples de code

Opérations de l'API REST

Le Kit de développement logiciel (SDK) Azure pour Java contient des bibliothèques qui s'appuient sur l'API REST Azure, vous permettant d’interagir avec les opérations de l’API REST par le biais de paradigmes Java familiers. Les méthodes de bibliothèque de client pour la gestion des propriétés système et des métadonnées définies par l’utilisateur utilisent les opérations d’API REST suivantes :

Ressources de bibliothèque cliente

Contenu connexe

  • Cet article fait partie du guide pour les développeurs Stockage Blob pour Java. Pour découvrir plus d’informations, consultez la liste complète des articles du guide du développeur dans Générer votre application Java.