Descarga de un blob con Python

  • Artículo

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

Configurar el entorno

Si no tiene un proyecto existente, en esta sección se muestra cómo configurar uno para que funcione con la biblioteca cliente de Azure Blob Storage para Python. Para más información, vea Introducción a Azure Blob Storage y Python.

Para trabajar con los ejemplos de código de este artículo, siga los pasos siguientes a fin de configurar el proyecto.

Instalar paquetes

Instale los siguientes paquetes mediante pip install:

pip install azure-storage-blob azure-identity

Adición de instrucciones import

Agregue las instrucciones siguientes import :

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

Authorization

El mecanismo de autorización debe tener los permisos necesarios para realizar una operación de descarga. Para la autorización con Microsoft Entra ID (recomendado) se necesita el rol integrado de RBAC de Azure de Lector de datos de Storage Blob o superior. Para obtener más información, consulte la guía de autorización de Obtener blobs (API de REST).

Creación de un objeto de cliente

Para conectar una aplicación a Blob Storage, cree una instancia de BlobServiceClient. En el ejemplo siguiente se muestra cómo crear un objeto de cliente mediante DefaultAzureCredential para la autorización:

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

También puede crear objetos de cliente para contenedores o blobs específicos ya sea directamente o desde el objeto BlobServiceClient. Para obtener más información sobre cómo crear y administrar objetos de cliente, consulte Crear y administrar objetos de cliente que interactúan con los recursos de datos.

Descarga de un blob

Puede usar el método siguiente para descargar un 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:

  1. Agregue las siguientes instrucciones import:

    import asyncio

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

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

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

Ejemplos de código

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:

Recursos de la biblioteca cliente

Contenido relacionado

  • Este artículo forma parte de la guía para desarrolladores de Blob Storage para Python. Para más información, consulte la lista completa de artículos de la guía para desarrolladores en Compilación de la aplicación de Python.