Démarrage rapide : Bibliothèque de client Stockage Blob Azure pour Python

  • Article

Remarque

L’option Générer à partir de zéro vous guide pas à pas dans le processus de création d’un projet, d’installation de packages, d’écriture du code et d’exécution d’une application console de base. Cette approche est recommandée si vous souhaitez comprendre tous les détails impliqués dans la création d’une application qui se connecte au service Stockage Blob Azure. Si vous préférez automatiser les tâches de déploiement et commencer par un projet terminé, choisissez Commencer avec un modèle.

Remarque

L’option Commencer avec un modèle utilise Azure Developer CLI pour automatiser les tâches de déploiement et commencer par un projet terminé. Cette approche est recommandée si vous souhaitez explorer le code le plus rapidement possible sans passer par les tâches de configuration. Si vous préférez suivre des instructions pas à pas pour générer l’application, choisissez Générer à partir de zéro.

Commencez à utiliser la bibliothèque de client Stockage Blob Azure pour Python 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.

Documentation de référence API | Code source de la bibliothèque | Package (PyPI) | Exemples

Cette vidéo vous montre comment commencer à utiliser la bibliothèque cliente Stockage Blob Azure pour Python.

Les étapes de la vidéo sont également décrites dans les sections suivantes.

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

Créer le projet

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

  1. Dans une fenêtre de console (telle que PowerShell ou Bash), créez un répertoire pour le projet :

    mkdir blob-quickstart

  2. Basculez vers le répertoire blob-quickstart nouvellement créé :

    cd blob-quickstart

Installer les packages

À partir du répertoire du projet, installez les packages pour les bibliothèques de client Stockage Blob Azure et Azure Identity à l’aide de la commande pip install. Le package azure-identity est nécessaire pour les connexions sans mot de passe aux services Azure.

pip install azure-storage-blob azure-identity

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. Ouvrez un nouveau fichier texte dans votre éditeur de code.
  2. Ajoutez des instructions import, créez la structure du programme et incluez une gestion des exceptions de base comme indiqué ci-dessous.
  3. Enregistrez le nouveau fichier comme blob-quickstart.py dans le répertoire blob-quickstart.
import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

try:
    print("Azure Blob Storage Python quickstart sample")

    # Quickstart code goes here

except Exception as ex:
    print('Exception:')
    print(ex)

Avec Azure Developer CLI installé, vous pouvez créer un compte de stockage et exécuter l’exemple de code en quelques commandes seulement. Vous pouvez exécuter 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-python

    Les informations suivantes vous sont demandées :

    • Nom de l’environnement : cette valeur est utilisée comme préfixe pour toutes les ressources Azure créées par Azure Developer CLI. Le nom doit être unique dans l’ensemble des abonnements Azure et il doit contenir entre 3 et 24 caractères. Le nom peut contenir uniquement des chiffres et des lettres minuscules.

  • Connexion à Azure :

    azd auth login

  • Approvisionnez et déployez les ressources sur Azure :

    azd up

    Les informations suivantes vous sont demandées :

    • Abonnement : abonnement Azure sur lequel vos ressources sont déployées.
    • Emplacement : région Azure où vos ressources sont déployées.

    Le déploiement peut prendre quelques minutes. La sortie de la commande azd up inclut le nom du compte de stockage nouvellement créé, dont vous aurez 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é. Pour installer les packages, mettre à jour le nom du compte de stockage dans le code et exécuter l’exemple d’application console, effectuez ces étapes :

  • Installer les packages : dans le répertoire local, installez les packages des bibliothèques de client Stockage Blob Azure et Azure Identity à l’aide de la commande suivante : pip install azure-storage-blob azure-identity
  • Mettre à jour le nom du compte de stockage : dans le répertoire local, modifiez le fichier nommé blob_quickstart.py. 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. Enregistrez les modifications.
  • Exécuter le projet : exécutez la commande suivante pour exécuter l’application : python blob_quickstart.py.
  • 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 sont des données qui 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 :

Diagram of Blob storage architecture

Utilisez les classes Python suivantes pour interagir avec ces ressources :

  • BlobServiceClient: La classe BlobServiceClient vous permet de manipuler les ressources de stockage Azure et les conteneurs blob.
  • ContainerClient : La classe ContainerClient vous permet de manipuler des conteneurs de stockage Azure et leurs blobs.
  • BlobClient : La classe BlobClient vous permet de manipuler des blobs de stockage Azure.

Exemples de code

Ces exemples d’extraits de code vous montrent comment effectuer les tâches suivantes avec la bibliothèque cliente Stockage Blob Azure pour Python :

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

L’ordre et les emplacements dans lesquels DefaultAzureCredential les informations d’identification sont disponibles dans la vue d’ensemble de la bibliothèque d’identités Azure.

Par exemple, votre application peut s’authentifier à l’aide de vos informations d’identification de connexion Azure CLI lors du développement local. Votre application peut ensuite utiliser une identité managée une fois qu’elle a été déployée 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. Vous pouvez en savoir plus sur les étendues disponibles pour les attributions de rôles dans la page vue d’ensemble de l’étendue .

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 affecte le rôle Contributeur aux données Blob du stockage à votre compte d’utilisateur, qui fournit à la fois un accès en lecture et en écriture aux données d’objet 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.

    A screenshot showing how to assign a role.

  5. Utilisez la zone de recherche pour filtrer les résultats sur le rôle souhaité. Pour cet exemple, recherchez Contributeur aux données Blob du stockage, sélectionnez le résultat correspondant, puis 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.

Se connecter et connecter le code d’application à Azure à l’aide de DefaultAzureCredential

Vous pouvez autoriser l’accès aux données dans votre compte de stockage en procédant comme suit :

  1. Vérifiez que vous êtes authentifié avec le même compte Microsoft Entra auquel vous avez attribué le rôle sur votre compte de stockage. Vous pouvez vous authentifier via 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, veillez à ce que le package azure-identity soit installé et à ce que la classe soit importée :

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

  3. Ajoutez ce code dans le bloc try. Quand le code est exécuté sur votre station de travail locale, DefaultAzureCredential utilise les informations d’identification de développeur de l’outil prioritaire auquel vous êtes connecté pour l’authentification auprès d’Azure, par exemple Azure CLI ou Visual Studio Code.

    account_url = "https://<storageaccountname>.blob.core.windows.net"
default_credential = DefaultAzureCredential()

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

  4. Veillez à mettre à jour le nom du compte de stockage dans l’URI de votre objet BlobServiceClient. Le nom du compte de stockage se trouve sur la page vue d’ensemble du Portail Azure.

    A screenshot showing how to find the storage account name.

    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 create_container sur l’objet blob_service_client. 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 du bloc try :

# Create a unique name for the container
container_name = str(uuid.uuid4())

# Create the container
container_client = blob_service_client.create_container(container_name)

Pour en savoir plus sur la création d’un conteneur et explorer d’autres exemples de code, consultez Créer un conteneur de blobs avec Python.

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.

Charger des objets blob sur un conteneur

Chargez un objet blob dans un conteneur à l’aide de upload_blob. 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 du bloc try :

# Create a local directory to hold blob data
local_path = "./data"
os.mkdir(local_path)

# Create a file in the local data directory to upload and download
local_file_name = str(uuid.uuid4()) + ".txt"
upload_file_path = os.path.join(local_path, local_file_name)

# Write text to the file
file = open(file=upload_file_path, mode='w')
file.write("Hello, World!")
file.close()

# Create a blob client using the local file name as the name for the blob
blob_client = blob_service_client.get_blob_client(container=container_name, blob=local_file_name)

print("\nUploading to Azure Storage as blob:\n\t" + local_file_name)

# Upload the created file
with open(file=upload_file_path, mode="rb") as data:
    blob_client.upload_blob(data)

Pour en savoir plus sur le chargement de blobs et explorer d’autres exemples de code, consultez Charger un blob avec Python.

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, un seul objet blob a été ajouté au conteneur. Il n’y a donc qu’un objet blob répertorié.

Ajoutez ce code à la fin du bloc try :

print("\nListing blobs...")

# List the blobs in the container
blob_list = container_client.list_blobs()
for blob in blob_list:
    print("\t" + blob.name)

Pour en savoir plus sur les listes de blobs et explorer d’autres exemples de code, consultez Lister des blobs avec Python.

Télécharger des objets blob

Téléchargez l’objet Blob créé précédemment en appelant la méthode download_blob. L’exemple de code ajoute le suffixe « DOWNLOAD » au nom de fichier afin que vous puissiez voir les deux fichiers dans votre système de fichiers local.

Ajoutez ce code à la fin du bloc try :

# Download the blob to a local file
# Add 'DOWNLOAD' before the .txt extension so you can see both files in the data directory
download_file_path = os.path.join(local_path, str.replace(local_file_name ,'.txt', 'DOWNLOAD.txt'))
container_client = blob_service_client.get_container_client(container= container_name) 
print("\nDownloading blob to \n\t" + download_file_path)

with open(file=download_file_path, mode="wb") as download_file:
 download_file.write(container_client.download_blob(blob.name).readall())

Pour en savoir plus sur le téléchargement de blobs et explorer d’autres exemples de code, consultez Télécharger un blob avec Python.

Supprimer un conteneur

Le code suivant nettoie les ressources créées par l’application en supprimant l’ensemble du conteneur avec la méthode delete_container. Si vous voulez, vous pouvez aussi supprimer les fichiers locaux.

L’application s’interrompt pour une entrée de l’utilisateur en appelant input() avant de supprimer l’objet blob, le conteneur et les fichiers locaux. Vérifiez que les ressources ont été créées correctement avant de les supprimer.

Ajoutez ce code à la fin du bloc try :

# Clean up
print("\nPress the Enter key to begin clean up")
input()

print("Deleting blob container...")
container_client.delete_container()

print("Deleting the local source and downloaded files...")
os.remove(upload_file_path)
os.remove(download_file_path)
os.rmdir(local_path)

print("Done")

Pour en savoir plus sur la suppression d’un conteneur et explorer d’autres exemples de code, consultez Supprimer et restaurer un conteneur de blobs avec Python.

Exécuter le code

Cette application crée un fichier de test dans votre dossier local et le charge dans Stockage Blob Azure. L’exemple liste ensuite le ou les objets blob du conteneur et télécharge le fichier sous un nouveau nom. Vous pouvez comparer les anciens fichiers avec les nouveaux.

Accédez au répertoire contenant le fichier blob-quickstart.py, puis exécutez la commande python suivante pour exécuter l’application :

python blob_quickstart.py

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

Azure Blob Storage Python quickstart sample

Uploading to Azure Storage as blob:
        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

Une fois que vous avez vérifié les fichiers et terminé le test, appuyez sur la touche Entrée pour supprimer les fichiers de test avec 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, vous pouvez nettoyer les ressources créées en exécutant la commande suivante :

azd down

Il vous sera demandé de confirmer la suppression des ressources. Entrez y pour confirmer.

Étapes suivantes

Dans ce démarrage rapide, vous avez appris à charger, télécharger et répertorier des objets blob avec Python.

Pour afficher des exemples d’applications de stockage blob, passez à :

Bibliothèque Stockage Blob Azure pour Python - exemples