Partager via

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

  • 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 montre 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 Python.

Pour en savoir plus sur la gestion des propriétés et des métadonnées à l’aide d’API asynchrones, consultez Définir des métadonnées d’objet blob de manière asynchrone.

Prérequis

Paramétrer votre environnement

Si vous n’avez aucun projet existant, cette section vous montre comment configurer un projet de façon à utiliser la bibliothèque de client Stockage Blob Azure pour Python. Pour plus d’informations, consultez Bien démarrer avec le service Stockage Blob Azure et Python.

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

Installer des packages

Installez les packages suivants en utilisant pip install :

pip install azure-storage-blob azure-identity

Ajouter des instructions import

Ajoutez les instructions import suivantes :

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContentSettings

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 montre comment créer un objet client à l’aide de DefaultAzureCredential pour l’autorisation :

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

Vous pouvez également créer des objets clients pour des conteneurs ou des objets blob spécifiques, directement ou à partir de l’objet BlobServiceClient. 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 Stockage Azure pour Python 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 (préversion).

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 :

Toutes les propriétés qui ne sont pas explicitement définies sont effacées. Pour conserver les propriétés existantes, vous pouvez d’abord récupérer les propriétés du blob, puis les utiliser pour remplir les en-têtes qui ne sont pas mis à jour.

L’exemple de code suivant définit les propriétés système content_type et content_language sur un blob, tout en conservant les propriétés existantes :

def set_properties(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Get the existing blob properties
    properties = blob_client.get_blob_properties()

    # Set the content_type and content_language headers, and populate the remaining headers from the existing properties
    blob_headers = ContentSettings(content_type="text/plain",
                                   content_encoding=properties.content_settings.content_encoding,
                                   content_language="en-US",
                                   content_disposition=properties.content_settings.content_disposition,
                                   cache_control=properties.content_settings.cache_control,
                                   content_md5=properties.content_settings.content_md5)
    
    blob_client.set_http_headers(blob_headers)

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 :

def get_properties(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    properties = blob_client.get_blob_properties()

    print(f"Blob type: {properties.blob_type}")
    print(f"Blob size: {properties.size}")
    print(f"Content type: {properties.content_settings.content_type}")
    print(f"Content language: {properties.content_settings.content_language}")

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 les métadonnées, envoyez un dictionnaire contenant des paires nom-valeur en utilisant la méthode suivante :

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

def set_metadata(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Retrieve existing metadata, if desired
    blob_metadata = blob_client.get_blob_properties().metadata

    more_blob_metadata = {'docType': 'text', 'docCategory': 'reference'}
    blob_metadata.update(more_blob_metadata)

    # Set metadata on the blob
    blob_client.set_blob_metadata(metadata=blob_metadata)

Pour récupérer les métadonnées, appelez la méthode get_blob_properties sur votre blob pour remplir la collection de métadonnées, puis lisez les valeurs, comme indiqué dans l’exemple suivant. La méthode get_blob_properties 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 :

def get_metadata(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Retrieve existing metadata, if desired
    blob_metadata = blob_client.get_blob_properties().metadata

    for k, v in blob_metadata.items():
        print(k, v)

Définir des métadonnées d’objet blob de manière asynchrone

La bibliothèque de client Stockage Blob Azure pour Python prend en charge la gestion des propriétés d’objet blob et des métadonnées de manière asynchrone. Pour en savoir plus sur les exigences de configuration de projet, consultez programmation asynchrone.

Suivez ces étapes pour définir des métadonnées d’objet blob à l’aide d’API asynchrones :

  1. Ajoutez les instructions d’importation suivantes :

    import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient

  2. Ajoutez du code pour exécuter le programme à l’aide de asyncio.run. Cette fonction exécute la coroutine passée, main() dans notre exemple et gère la boucle d’événement asyncio. Les coroutines sont déclarées avec la syntaxe asynchrone/await. Dans cet exemple, la coroutine main() crée d’abord le BlobServiceClient de premier niveau à l’aide de async with, puis appelle la méthode qui définit les métadonnées d’objet blob. Notez que seul le client de niveau supérieur doit utiliser async with, car d’autres clients créés à partir de celui-ci partagent le même pool de connexions.

    async def main():
    sample = BlobSamples()

    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    credential = DefaultAzureCredential()

    async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
        await sample.set_metadata(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())

  3. Ajoutez du code pour définir les métadonnées d’objet blob. Le code est identique à celui de l’exemple synchrone. Toutefois, la méthode est déclarée avec le mot clé async, et le mot clé await est utilisé au moment de l’appel des méthodes get_blob_properties et set_blob_metadata.

    async def set_metadata(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Retrieve existing metadata, if desired
    properties = await blob_client.get_blob_properties()
    blob_metadata = properties.metadata

    more_blob_metadata = {'docType': 'text', 'docCategory': 'reference'}
    blob_metadata.update(more_blob_metadata)

    # Set metadata on the blob
    await blob_client.set_blob_metadata(metadata=blob_metadata)

Avec cette configuration de base en place, vous pouvez implémenter d’autres exemples dans cet article en tant que coroutines à l’aide de la syntaxe asynchrone/await.

Ressources

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

Exemples de code

Opérations de l'API REST

Le SDK Azure pour Python contient des bibliothèques qui reposent sur l’API REST Azure, ce qui vous permet d’interagir avec les opérations d’API REST en utilisant des paradigmes Python 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 Stockage Blob pour Python pour les développeurs. Pour découvrir plus d’informations, consultez la liste complète des articles du guide du développeur dans Générer votre application Python.