Partager via

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

  • Cet article suppose que vous disposez déjà d'un projet configuré pour fonctionner avec la bibliothèque client Azure Blob Storage pour Python. Pour en savoir plus sur la configuration de votre projet, y compris l'installation du package, l'ajout d'instructions import et la création d'un objet client autorisé, consultez Bien démarrer avec Azure Blob Storage et Python.
  • Pour utiliser des API asynchrones dans votre code, consultez les conditions requises dans la section programmation asynchrone.
  • Le mécanisme d’autorisation doit disposer des autorisations nécessaires pour effectuer une opération de téléchargement. Pour en savoir plus, consultez les conseils d’autorisation pour l’opération d’API REST suivante :

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.

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 :

Exemples de code

Ressources de bibliothèque cliente