Descarga de un blob con Python
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
- Una suscripción a Azure: cree una cuenta gratuita
- Una cuenta de Azure Storage: cree una cuenta de almacenamiento
- Python 3.8 y versiones posteriores
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 encoding
s 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 superamax_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 eventosasyncio
. Las corrutinas se declaran con la sintaxis async/await. En este ejemplo, la corrutinamain()
primero crea el nivel superiorBlobServiceClient
medianteasync with
y, después, llama al método que descarga el blob. Tenga en cuenta que solo el cliente de nivel superior debe usarasync 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 claveasync
y la palabra claveawait
se usa al llamar al métododownload_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
- Ver ejemplo de código sincrónicos o asincrónicos de este artículo (GitHub)
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)
Recursos de la biblioteca cliente
- Documentación de referencia de la biblioteca cliente
- Código fuente de la biblioteca del cliente
- Paquete (PyPi)
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.