Gérer les métadonnées et les propriétés de conteneur avec Python
Les conteneurs d’objets blob prennent en charge des propriétés système et des métadonnées définies par l’utilisateur, en plus des données qu’ils contiennent. Cet article présente la gestion des propriétés système et des métadonnées définies par l’utilisateur avec la bibliothèque de client 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 de conteneur de manière asynchrone.
Prérequis
- Abonnement Azure : créez-en un gratuitement
- Compte de stockage Azure : créez un compte de stockage
- Python 3.8+
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
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 Get Container Properties (API REST), Set Container Metadata (API REST) ou Get Container 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 : des propriétés système s’appliquent à 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.
Récupérer les propriétés de conteneur
Pour récupérer les propriétés d’un conteneur, utilisez la méthode suivante :
L’exemple de code suivant récupère les propriétés système d’un conteneur et écrit les valeurs des propriétés dans une fenêtre de console :
def get_properties(self, blob_service_client: BlobServiceClient, container_name):
container_client = blob_service_client.get_container_client(container=container_name)
properties = container_client.get_container_properties()
print(f"Public access type: {properties.public_access}")
print(f"Lease status: {properties.lease.status}")
print(f"Lease state: {properties.lease.state}")
print(f"Has immutability policy: {properties.has_immutability_policy}")
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, utilisez la méthode suivante :
La définition des métadonnées de conteneur remplace toutes les métadonnées existantes associées au conteneur. Il n'est pas possible de modifier une paire nom-valeur individuelle.
L’exemple de code suivant définit les métadonnées d’un conteneur :
def set_metadata(self, blob_service_client: BlobServiceClient, container_name):
container_client = blob_service_client.get_container_client(container=container_name)
# Retrieve existing metadata, if desired
metadata = container_client.get_container_properties().metadata
more_metadata = {'docType': 'text', 'docCategory': 'reference'}
metadata.update(more_metadata)
# Set metadata on the container
container_client.set_container_metadata(metadata=metadata)
Pour récupérer des métadonnées, appelez la méthode suivante :
L’exemple suivant lit les valeurs de métadonnées :
def get_metadata(self, blob_service_client: BlobServiceClient, container_name):
container_client = blob_service_client.get_container_client(container=container_name)
# Retrieve existing metadata, if desired
metadata = container_client.get_container_properties().metadata
for k, v in metadata.items():
print(k, v)
Définir des métadonnées de conteneur de manière asynchrone
La bibliothèque de client Stockage Blob Azure pour Python prend en charge la gestion des propriétés de conteneur 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 de conteneur à l’aide d’API asynchrones :
Ajoutez les instructions d’importation suivantes :
import asyncio from azure.identity.aio import DefaultAzureCredential from azure.storage.blob.aio import BlobServiceClient
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énementasyncio
. Les coroutines sont déclarées avec la syntaxe asynchrone/await. Dans cet exemple, la coroutinemain()
crée d’abord leBlobServiceClient
de niveau supérieur à l’aide deasync with
, puis appelle la méthode qui définit les métadonnées de conteneur. Notez que seul le client de niveau supérieur doit utiliserasync with
, car d’autres clients créés à partir de celui-ci partagent le même pool de connexions.async def main(): sample = ContainerSamples() # 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())
Ajoutez du code pour définir les métadonnées de conteneur. 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éthodesget_container_properties
etset_container_metadata
.async def set_metadata(self, blob_service_client: BlobServiceClient, container_name): container_client = blob_service_client.get_container_client(container=container_name) # Retrieve existing metadata, if desired metadata = (await container_client.get_container_properties()).metadata more_metadata = {'docType': 'text', 'docCategory': 'reference'} metadata.update(more_metadata) # Set metadata on the container await container_client.set_container_metadata(metadata=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 définition et la récupération des propriétés de conteneur et des métadonnées à l’aide de la bibliothèque de client Stockage Blob Azure pour Python, consultez les ressources suivantes.
Exemples de code
- Afficher synchrone ou exemples de code asynchrones de cet article (GitHub)
Opérations de l'API REST
Le Kit de développement logiciel (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 de l’API REST via des paradigmes Python familiers. Les méthodes de la bibliothèque de client pour définir et récupérer des propriétés et des métadonnées utilisent les opérations d’API REST suivantes :
- Get Container Properties (API REST)
- Set Container Metadata (API REST)
- Get Container Metadata (API REST)
La méthode get_container_properties
récupère les propriétés et les métadonnées de conteneur en appelant à la fois l’opération Obtenir les propriétés d’un conteneur et l’opération Obtenir les métadonnées d’un conteneur.
Ressources de bibliothèque cliente
- Documentation de référence sur la bibliothèque cliente
- Code source de la bibliothèque de client
- Package (PyPi)
Contenu connexe
- Cet article fait partie du guide Stockage Blob pour Python pour les développeurs. Pour en savoir plus, consultez la liste complète des articles du guide du développeur dans Générer votre application Python.