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

À 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.

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 :

Exemples de code

Ressources de bibliothèque cliente