Télécharger un blob avec Python

  • Article

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.

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 :

import io
import os
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient

Autorisation

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

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.

Télécharger un objet blob

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.

Télécharger dans un chemin de fichier

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())

Télécharger dans un flux

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}")

Télécharger un objet blob en blocs

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)

Télécharger dans une chaîne

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}")

Télécharger un objet blob de blocs avec des options de configuration

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.

Spécifier les options de transfert de données lors du téléchargement

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épasse max_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())

Télécharger des objets blob de manière asynchrone

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 :

  1. Ajoutez les instructions d’importation suivantes :

    import asyncio

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

  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 main()coroutine crée d’abord le niveau supérieur BlobServiceClient à l’aide de async with, puis appelle la méthode qui télécharge l’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.download_blob_to_file(blob_service_client, "sample-container")

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

  3. 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éthode download_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.

Ressources

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.

Exemples de code

Opérations de l'API REST

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 :

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.