Baixar um blob com Python

  • Artigo

Este artigo mostra como baixar um blob usando a biblioteca de clientes de Armazenamento do Microsoft Azure para Python. Você pode baixar dados de blob em vários destinos, incluindo um caminho de arquivo local, fluxo ou cadeia de caracteres de texto. Você também pode abrir um fluxo de blob e lê-lo.

Para saber mais sobre download de blobs usando APIs assíncronas, confira Download de blobs de forma assíncrona.

Pré-requisitos

  • Este artigo pressupõe que você já tenha um projeto configurado para trabalhar com a biblioteca de clientes do Armazenamento de Blobs do Azure para Python. Para saber mais sobre como configurar seu projeto, incluindo a instalação de pacote, a adição de instruções de import e a criação de um objeto de cliente autorizado, consulte Introdução ao Armazenamento de Blobs do Azure e Python.
  • Para usar APIs assíncronas no seu código, confira os requisitos na seção Programação assíncrona.
  • O mecanismo de autorização deve ter permissões para executar uma operação de download. Para saber mais, consulte as diretrizes de autorização para as seguintes operações de API REST:

Baixar um blob

Você pode usar o seguinte método para baixar um blob:

O método download_blob retorna um objeto StorageStreamDownloader. Durante um download, as bibliotecas de cliente dividem a solicitação de download em partes, onde cada parte é baixada através de uma solicitação de intervalo Get Blob separada. Esse comportamento depende do tamanho total do blob e de como as opções de transferência de dados são definidas.

Download em um caminho de arquivo

O exemplo a seguir baixa um blob para um caminho de arquivo:

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

Download em um fluxo

O exemplo a seguir baixa um blob para um fluxo. Neste exemplo, StorageStreamDownloader.read_into baixa o conteúdo do blob para um fluxo e retorna o número de bytes lidos:

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

Baixar um blob em partes

O exemplo a seguir baixa um blob e itera em partes no fluxo de download. Neste exemplo, StorageStreamDownloader.chunks retorna um iterador que permite ler o conteúdo do blob em partes:

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)

Download em uma cadeia de caracteres

O exemplo a seguir baixa o conteúdo do blob como texto. Neste exemplo, o parâmetro encoding é necessário para retornar readall() para uma cadeia de caracteres, caso contrário, retornará 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}")

Baixar um blob de blocos com opções de configuração

Você pode definir as opções de configuração da biblioteca de clientes ao baixar um blob. Essas opções podem ser ajustadas para melhorar o desempenho e aumentar a confiabilidade. Os exemplos de código a seguir mostram como definir opções de configuração para um download no nível do método e no nível do cliente ao instanciar BlobClient. Essas opções também podem ser configuradas para uma instância ContainerClient ou uma instância BlobServiceClient.

Especificar opções de transferência de dados durante o download

Você pode definir opções de configuração ao instanciar um cliente para otimizar o desempenho das operações de transferência de dados. Você pode passar os seguintes argumentos de palavra-chave ao construir um objeto cliente no Python:

  • max_chunk_get_size – O tamanho máximo da parte usada para baixar um blob. O padrão é 4 MiB.
  • max_single_get_size – O tamanho máximo para que um blob seja baixado em uma única chamada. Se o tamanho total do blob exceder max_single_get_size, o restante dos dados de blob será baixado em partes. O padrão é 32 MiB.

Para operações de download, você também pode passar o argumento max_concurrency ao chamar download_blob. Esse argumento define o número máximo de conexões paralelas para a operação de download.

O exemplo de código a seguir mostra como especificar opções de transferência de dados ao criar um objeto BlobClient e como baixar dados usando esse objeto cliente. Os valores fornecidos neste exemplo não se destinam a ser uma recomendação. Para ajustar adequadamente esses valores, você precisa considerar as necessidades específicas do seu aplicativo.

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

Download de blobs de forma assíncrona

A biblioteca de clientes do Armazenamento de Blobs do Azure para Python dá suporte ao download de blobs de forma assíncrona. Para saber mais sobre os requisitos de instalação do projeto, confira Programação assíncrona.

Siga estas etapas para o download de um blob usando APIs assíncronas:

  1. Adicione as seguintes instruções de importação:

    import asyncio

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

  2. Adicione o código para executar o programa usando asyncio.run. Essa função executa a corrotina passada, main() no nosso exemplo, e gerencia o loop de eventos asyncio. As corrotinas são declaradas com a sintaxe async/await. Neste exemplo, a corrotina main() primeiro cria o BlobServiceClient de nível superior usando async with e, em seguida, chama o método que faz o download do blob. Observe que somente o cliente de nível superior precisa usar async with, pois os outros clientes criados a partir dele compartilham o mesmo pool de conexões.

    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. Adicione o código para download do blob. O exemplo a seguir faz o download de um blob para um caminho de arquivo local usando um objeto BlobClient. O código é igual ao exemplo síncrono, exceto que o método é declarado com a palavra-chave async e a palavra-chave await é usada ao chamar o 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)

Com essa configuração básica em vigor, você pode implementar outros exemplos neste artigo como corrotinas usando sintaxe a async/await.

Recursos

Para saber mais sobre como baixar blobs usando a biblioteca de clientes de Armazenamento de Blobs do Azure para Python, consulte os seguintes recursos.

Operações da API REST

O SDK do Azure para Python contém bibliotecas que criam sobre a API REST do Azure, permitindo a interação com as operações de API REST por meio de paradigmas conhecidos do Python. Os métodos da biblioteca de clientes para baixar blobs usam a seguinte operação da API REST:

Exemplos de código

Recursos da biblioteca de clientes