Compartilhar via

Baixar um blob com Python

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

Para saber mais sobre o download de blobs com APIs assíncronas, veja Baixar blobs de modo assíncrono.

Pré-requisitos

Configurar seu ambiente

Se você não tiver um projeto existente, esta seção mostrará como configurar um projeto para funcionar com a biblioteca de clientes do Armazenamento de Blobs do Azure para Python. Para obter mais detalhes, veja Introdução ao Armazenamento de Blobs do Azure e ao Python.

Para trabalhar com os exemplos de código neste artigo, siga estas etapas para configurar seu projeto.

Instalar pacotes

Instale os seguintes pacotes usando pip install:

pip install azure-storage-blob azure-identity

Adicionar instruções de importação

Adicione as seguintes instruções import:

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

Autorização

O mecanismo de autorização precisa ter as permissões necessárias para executar uma operação de download. Para a autorização com o Microsoft Entra ID (recomendado), você precisa ter a função interna Leitor de dados do blob de armazenamento ou superior do RBAC do Azure. Para saber mais, veja as diretrizes de autorização para Obter Blob (API REST).

Criar um objeto cliente

Para conectar um aplicativo ao Armazenamento de Blobs, crie uma instância do BlobServiceClient. O seguinte exemplo mostra como criar um objeto cliente usando DefaultAzureCredential para autorização:

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

Você também pode criar objetos cliente para contêineres ou blobs específicos, diretamente ou do objeto BlobServiceClient. Para saber mais sobre como criar e gerenciar objetos clientes, veja Criar e gerenciar objetos cliente que interagem com recursos de dados.

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 clientes dividem a solicitação de download em partes, onde cada parte é baixada por meio de uma solicitação de intervalo Obter 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 seguinte exemplo baixa um blob em 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 em 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 aprimorar 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 método e no cliente ao criar uma instância de BlobClient. Essas opções também podem ser configuradas para uma instância de ContainerClient ou uma instância de 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 modo assíncrono

A biblioteca de clientes do Armazenamento de Blobs do Azure para Python dá suporte ao download de blobs de modo assíncrono. Para saber mais sobre os requisitos de instalação do projeto, veja 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 baixa o blob. Observe que somente o cliente de nível superior precisa usar async with, pois os outros clientes criados com base nele compartilham o 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 baixa um blob em um caminho de arquivo local usando um objeto BlobClient. O código é igual ao exemplo síncrono, com exceção de 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 a sintaxe async/await.

Recursos

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

Exemplos de código

Operações da API REST

O SDK do Azure para Python contém bibliotecas que se baseiam na API REST do Azure, permitindo a interação com as operações da 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:

Recursos da biblioteca de clientes

Conteúdo relacionado

  • Este artigo faz parte do guia de desenvolvedores do Armazenamento de Blobs para Python. Para saber mais, veja a lista completa de artigos do guia de desenvolvedores em Criar seu aplicativo Python.