Descarga de un blob con Python

Artículo
11/24/2023

En este artículo se muestra cómo descargar un blob con la biblioteca cliente de Azure Storage para Python. Puede descargar datos de blob en varios destinos, incluyendo una ruta de acceso de archivo local, una secuencia o una cadena de texto. También puede abrir una secuencia de blobs y leerla.

Para aprender a descargar blobs mediante API asincrónicas, consulte Descarga de blobs de forma asincrónica.

Requisitos previos

En este artículo se supone que ya tiene un proyecto configurado para trabajar con la biblioteca cliente de Azure Blob Storage para Python. Para obtener información sobre cómo configurar el proyecto, incluida la instalación de paquetes, la adición de directivas de import y la autorización de un objeto de cliente, consulte Introducción a Azure Storage y Java.
Para usar API asincrónicas en el código, consulte los requisitos de la sección Programación asincrónica.
El mecanismo de autorización debe tener permisos para realizar una operación de descarga. Para obtener más información, consulte la guía de autorización para la siguiente operación de la API de REST:
- Get Blob

Descarga de un blob

Puede usar el método siguiente para descargar un blob:

BlobClient.download_blob

El método download_blob devuelve un objeto StorageStreamDownloader. Durante una descarga, las bibliotecas cliente dividen la solicitud de descarga en fragmentos, donde cada fragmento se descarga con una solicitud de intervalo Get Blob. Este comportamiento depende del tamaño total del blob y de cómo se establecen las opciones de transferencia de datos.

Descarga en una ruta de acceso de archivo

En el ejemplo siguiente se descarga un blob en una ruta de acceso de archivo:

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

Descarga en una secuencia

En el ejemplo siguiente se descarga un blob en una secuencia. En este ejemplo, StorageStreamDownloader.read_into descarga el contenido del blob en una secuencia y devuelve el número de bytes leídos:

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

Descarga de un blob en fragmentos

En el ejemplo siguiente se descarga un blob y se recorren en iteración los fragmentos de la secuencia de descarga. En este ejemplo, StorageStreamDownloader.chunks devuelve un iterador, que permite leer el contenido del blob en fragmentos:

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)

Descarga en una cadena

En el ejemplo siguiente se descarga el contenido del blob como texto. En este ejemplo, el parámetro encodings necesario para que readall() devuelva una cadena; de lo contrario, devuelve bytes:

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

Descargar un blob en bloques con opciones de configuración

Puede definir las opciones de configuración de la biblioteca cliente al descargar un blob. Estas opciones se pueden ajustar para mejorar el rendimiento y la confiabilidad. En los ejemplos de código siguientes, se muestra cómo definir opciones de configuración para una descarga tanto en el nivel de método como en el nivel de cliente al crear instancias de BlobClient. Estas opciones también se pueden configurar para una instancia ContainerClient o una instancia de BlobServiceClient.

Especificar opciones de transferencia de datos al descargar

Puede establecer opciones de configuración al crear instancias de un cliente para optimizar el rendimiento de las operaciones de transferencia de datos. Puede pasar los argumentos de palabra clave siguientes al construir un objeto de cliente en Python:

max_chunk_get_size: tamaño máximo de fragmento que se usa para descargar un blob. El valor predeterminado es 4 MB.
max_single_get_size: tamaño máximo de un blob que se va a descargar en una sola llamada. Si el tamaño total del blob supera max_single_get_size, el resto de los datos del blob se descarga en fragmentos. El valor predeterminado es 32 MB.

Para las operaciones de descarga, también puede pasar el argumento max_concurrency al llamar a download_blob. Este argumento define el número máximo de conexiones paralelas para la operación de descarga.

En el ejemplo de código siguiente, se muestra cómo especificar opciones de transferencia de datos al crear un objeto BlobClient y cómo descargar datos mediante ese objeto de cliente. Los valores proporcionados en este ejemplo no están diseñados para ser una recomendación. Para ajustar correctamente estos valores, debe tener en cuenta las necesidades específicas de la aplicación.

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

Descarga de blobs de forma asincrónica

La biblioteca cliente de Azure Blob Storage para Python admite la descarga de blobs de forma asincrónica. Para obtener más información sobre los requisitos de configuración del proyecto, consulte Programación asincrónica.

Siga estos pasos para descargar un blob mediante API asincrónicas:

Agregue las siguientes instrucciones import:

import asyncio

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

Agregue código para ejecutar el programa mediante asyncio.run. Esta función ejecuta la corrutina pasada, main() en nuestro ejemplo, y administra el bucle de eventos asyncio. Las corrutinas se declaran con la sintaxis async/await. En este ejemplo, la corrutina main() primero crea el nivel superior BlobServiceClient mediante async with y, después, llama al método que descarga el blob. Tenga en cuenta que solo el cliente de nivel superior debe usar async with, ya que otros clientes creados a partir de él comparten el mismo grupo de conexiones.
```
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())
```

Agregue código para descargar el blob. En el ejemplo siguiente se descarga un blob en una ruta de acceso de archivo local mediante un objeto BlobClient. El código es el mismo que el ejemplo sincrónico, salvo que el método se declara con la palabra clave async y la palabra clave await se usa al llamar al método 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)

Con esta configuración básica, puede implementar otros ejemplos de este artículo como corrutinas mediante la sintaxis async/await.

Recursos

Para más información sobre cómo descargar blobs mediante la biblioteca cliente de Azure Blob Storage para Python, consulte los recursos siguientes.

Operaciones de API REST

El SDK de Azure para Python contiene bibliotecas que se crean a partir de la API REST de Azure, lo que le permite interactuar con las operaciones de API REST mediante paradigmas conocidos de Python. Los métodos de la biblioteca cliente para descargar blobs usan la siguiente operación de API REST:

Get Blob (API REST)

Ejemplos de código

Ver ejemplo de código sincrónicos o asincrónicos de este artículo (GitHub)