Télécharger un blob avec Python
Cet article montre comment télécharger un blob avec la bibliothèque de client du Stockage Azure pour Python. Vous pouvez télécharger des données blob vers différentes destinations, notamment un chemin d’accès de fichier local, un flux ou une chaîne de texte. Vous pouvez également ouvrir un flux d’objets blob et lire à partir de celui-ci.
Pour en savoir plus sur le chargement d’objet blob à l’aide d’API asynchrones, consultez Télécharger des objets blob de manière asynchrone.
- Abonnement Azure : créez-en un gratuitement
- Compte de stockage Azure : créez un compte de stockage
- Python 3.8+
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.
Installez les packages suivants en utilisant pip install
:
pip install azure-storage-blob azure-identity
Ajoutez les instructions import
suivantes :
import io
import os
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient
Le mécanisme d’autorisation doit disposer des autorisations nécessaires pour effectuer une opération de téléchargement. Pour l’autorisation avec Microsoft Entra ID (recommandé), vous devez disposer au minimum du rôle RBAC Azure intégré Lecteur de données Blob du stockage. Pour en savoir plus, consultez l’aide sur l’autorisation pour l’opération Get Blob (API REST).
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.
Vous pouvez utiliser la méthode suivante pour télécharger un objet blob :
La méthode download_blob
renvoie un objet StorageStreamDownloader. Au cours d’un téléchargement, les bibliothèques de client divisent la demande de téléchargement en blocs, chaque bloc étant ensuite téléchargé via une demande de plage Get Blob distincte. Ce comportement dépend de la taille totale du blob et de la façon dont les options de transfert de données sont définies.
L’exemple suivant télécharge un blob dans un chemin d’accès de fichiers :
def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob:
download_stream = blob_client.download_blob()
sample_blob.write(download_stream.readall())
L’exemple suivant télécharge un blob dans un flux. Dans cet exemple, StorageStreamDownloader.read_into télécharge le contenu de l’objet blob dans un flux et retourne le nombre d’octets lus :
def download_blob_to_stream(self, blob_service_client: BlobServiceClient, container_name):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
# readinto() downloads the blob contents to a stream and returns the number of bytes read
stream = io.BytesIO()
num_bytes = blob_client.download_blob().readinto(stream)
print(f"Number of bytes: {num_bytes}")
L’exemple suivant télécharge un objet blob et itère sur des blocs dans le flux de téléchargement. Dans cet exemple, StorageStreamDownloader.chunks retourne un itérateur, qui vous permet de lire le contenu d’objet blob en blocs :
def download_blob_chunks(self, blob_service_client: BlobServiceClient, container_name):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
# This returns a StorageStreamDownloader
stream = blob_client.download_blob()
chunk_list = []
# Read data in chunks to avoid loading all into memory at once
for chunk in stream.chunks():
# Process your data (anything can be done here - 'chunk' is a byte array)
chunk_list.append(chunk)
L’exemple suivant télécharge le contenu d’objet blob sous forme de texte. Dans cet exemple, le paramètre encoding
est nécessaire pour que readall()
renvoie une chaîne, sinon il retourne des octets :
def download_blob_to_string(self, blob_service_client: BlobServiceClient, container_name):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
# encoding param is necessary for readall() to return str, otherwise it returns bytes
downloader = blob_client.download_blob(max_concurrency=1, encoding='UTF-8')
blob_text = downloader.readall()
print(f"Blob contents: {blob_text}")
Vous pouvez définir des options de configuration de bibliothèque de client lors du téléchargement d’un objet blob. Ces options peuvent être paramétrées pour améliorer les performances et améliorer la fiabilité. Les exemples de code suivants montrent comment définir les options de configuration pour un téléchargement, tant au niveau de la méthode qu’au niveau du client, dans le cadre de l’instanciation de BlobClient. Ces options peuvent également être configurées pour une instance ContainerClient ou une instance BlobServiceClient.
Vous pouvez définir les options de configuration à l’occasion de l’instanciation d’un client afin d’optimiser les opérations de transfert de données sur le plan des performances. Vous pouvez transmettre les arguments de mot clé suivants lors de la construction d’un objet client en Python :
max_chunk_get_size
– Taille de bloc maximale utilisée pour le téléchargement d’un blob. La valeur par défaut est 4 Mio.max_single_get_size
– Taille maximale pour un blob à télécharger en un seul appel. Si la taille totale du blob dépassemax_single_get_size
, le reste des données blob est téléchargé en blocs. La valeur par défaut est 32 Mio.
Pour les opérations de téléchargement, vous pouvez également transmettre l’argument max_concurrency
lors de l’appel de download_blob. Cet argument définit le nombre maximal de connexions parallèles pour l’opération de téléchargement.
L’exemple de code suivant montre comment spécifier les options de transfert de données lors de la création d’un objet BlobClient
, et comment télécharger les données à l’aide de cet objet client. Les valeurs fournies dans cet exemple ne sont pas destinées à être une recommandation. Pour régler correctement ces valeurs, vous devez tenir compte des besoins spécifiques de votre application.
def download_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
# Create a BlobClient object with data transfer options for download
blob_client = BlobClient(
account_url=account_url,
container_name=container_name,
blob_name=blob_name,
credential=DefaultAzureCredential(),
max_single_get_size=1024*1024*32, # 32 MiB
max_chunk_get_size=1024*1024*4 # 4 MiB
)
with open(file=os.path.join(r'file_path', 'file_name'), mode="wb") as sample_blob:
download_stream = blob_client.download_blob(max_concurrency=2)
sample_blob.write(download_stream.readall())
La bibliothèque cliente Stockage Blob Azure pour Python prend en charge le téléchargement asynchrone d’objets blob. Pour en savoir plus sur les exigences de configuration de projet, consultez programmation asynchrone.
Procédez comme suit pour télécharger un objet blob à 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, BlobClient
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, lamain()
coroutine crée d’abord le niveau supérieurBlobServiceClient
à l’aide deasync with
, puis appelle la méthode qui télécharge l’objet blob. 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 = 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.download_blob_to_file(blob_service_client, "sample-container") if __name__ == '__main__': asyncio.run(main())
Ajoutez du code pour télécharger l’objet blob. L’exemple suivant télécharge un blob dans un chemin d’accès de fichier local à l’aide d’un objet
BlobClient
. Le code est identique à l’exemple synchrone, sauf que la méthode est déclarée avec le mot cléasync
et que le mot cléawait
est utilisé lors de l’appel de la méthodedownload_blob
.async def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name): blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt") with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob: download_stream = await blob_client.download_blob() data = await download_stream.readall() sample_blob.write(data)
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.
Pour en savoir plus sur le téléchargement d’objets blob à l’aide de la bibliothèque de client Stockage Blob Azure pour Python, consultez les ressources suivantes.
- Afficher synchrone ou exemples de code asynchrones de cet article (GitHub)
Le kit de développement logiciel (SDK) Azure pour Python 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 Python familiers. Les méthodes de bibliothèque de client pour télécharger des objets blob utilisent l’opération d’API REST suivante :
- Get Blob (API REST)
- Documentation de référence sur la bibliothèque cliente
- Code source de la bibliothèque de client
- Package (PyPi)
- 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.