Baixe um blob com Python

  • Artigo

Este artigo mostra como baixar um blob usando a biblioteca de cliente do Armazenamento do Azure para Python. Você pode baixar dados de blob para 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 ler a partir dele.

Para saber mais sobre como baixar blobs usando APIs assíncronas, consulte Baixar blobs de forma assíncrona.

Pré-requisitos

Configurar o ambiente

Se você não tiver um projeto existente, esta seção mostra como configurar um projeto para trabalhar com a biblioteca de cliente do Armazenamento de Blobs do Azure para Python. Para obter mais detalhes, consulte Introdução ao Armazenamento de Blobs do Azure e 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 deve ter as permissões necessárias para executar uma operação de download. Para autorização com o Microsoft Entra ID (recomendado), você precisa da função interna do RBAC do Azure RBAC Storage Blob Data Reader ou superior. Para saber mais, consulte as diretrizes de autorização para Obter Blob (API REST).

Criar um objeto cliente

Para conectar um aplicativo ao Armazenamento de Blob, crie uma instância de BlobServiceClient. O exemplo a seguir 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 de cliente para contêineres ou blobs específicos, diretamente ou a partir do BlobServiceClient objeto. Para saber mais sobre como criar e gerenciar objetos de cliente, consulte Criar e gerenciar objetos de cliente que interagem com recursos de dados.

Transferir um blob

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

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

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

Transferir para 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 pedaços

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 para uma cadeia de caracteres

O exemplo a seguir baixa o conteúdo do blob como texto. Neste exemplo, o encoding parâmetro é necessário para readall() retornar uma cadeia de caracteres, caso contrário, ele retorna 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 bloco com opções de configuração

Você pode definir opções de configuração da biblioteca do cliente 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 para operações de transferência de dados. Você pode passar os seguintes argumentos de palavra-chave ao construir um objeto cliente em Python:

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

Para operações de download, você também pode passar o max_concurrency argumento 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 BlobClient objeto e como baixar dados usando esse objeto cliente. Os valores fornecidos neste exemplo não pretendem ser uma recomendação. Para ajustar corretamente 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())

Baixar blobs de forma assíncrona

A biblioteca de cliente 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 configuração do projeto, consulte Programação assíncrona.

Siga estas etapas para baixar 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 código para executar o programa usando asyncio.runo . Essa função executa a co-rotina passada, main() em nosso exemplo, e gerencia o loop de asyncio eventos. As co-rotinas são declaradas com a sintaxe async/await. Neste exemplo, a main() co-rotina primeiro cria o nível BlobServiceClient superior usando async withe, em seguida, chama o método que baixa o blob. Observe que apenas o cliente de nível superior precisa usar async witho , pois 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 código para baixar o blob. O exemplo a seguir baixa um blob para um caminho de arquivo local usando um BlobClient objeto. O código é o mesmo que o exemplo síncrono, exceto que o método é declarado com a async palavra-chave e a await palavra-chave é usada ao chamar o download_blob método.

    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 co-rotinas usando a sintaxe async/await.

Recursos

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

Amostras 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 que você interaja com operações da API REST por meio de paradigmas Python familiares. Os métodos da biblioteca de cliente para baixar blobs usam a seguinte operação da API REST:

Recursos da biblioteca do cliente

Conteúdos relacionados

  • Este artigo faz parte do guia do desenvolvedor do Blob Storage para Python. Para saber mais, consulte a lista completa de artigos do guia do desenvolvedor em Build your Python app.