Scaricare un BLOB con Python

  • Articolo

Questo articolo illustra come scaricare un BLOB usando la libreria client di Archiviazione di Azure per Python. È possibile scaricare dati BLOB in varie destinazioni, tra cui un percorso di file locale, un flusso o una stringa di testo. È anche possibile aprire un flusso BLOB e leggerlo.

Per informazioni su come scaricare BLOB tramite API asincrone, vedere Scaricare BLOB in modo asincrono.

Prerequisiti

Configurazione dell'ambiente

Se non si dispone di un progetto esistente, questa sezione illustra come configurare un progetto per l’uso con la libreria client di Archiviazione BLOB di Azure per Python. Per altre informazioni, vedere Introduzione ad Archiviazione BLOB di Azure e Python.

Per usare gli esempi di codice in questo articolo, seguire questa procedura per configurare il progetto.

Installare i pacchetti

Installare i pacchetti seguenti tramite pip install:

pip install azure-storage-blob azure-identity

Aggiungere le istruzioni di importazione

Aggiungere le istruzioni import seguenti:

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

Autorizzazione

Il meccanismo di autorizzazione deve disporre delle autorizzazioni necessarie per eseguire un'operazione di download. Per l'autorizzazione con Microsoft Entra ID (scelta consigliata), è necessario disporre del ruolo predefinito Controllo degli accessi in base al ruolo di Azure Lettore dei dati del BLOB di archiviazione o ruolo superiore. Per altre informazioni, vedere le indicazioni sulle autorizzazioni per Get Blob (API REST).

Creare un oggetto client

Per connettere un'app ad Archiviazione BLOB, creare un'istanza di BlobServiceClient. Nell'esempio seguente viene illustrato come creare un oggetto client usando DefaultAzureCredential per l'autorizzazione:

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

È anche possibile creare oggetti client per contenitori o BLOB specifici, direttamente o dall'oggetto BlobServiceClient. Per altre informazioni sulla creazione e la gestione di oggetti client, vedere Creare e gestire oggetti client che interagiscono con le risorse dati.

Scaricare un BLOB

Per scaricare un BLOB è possibile usare il metodo seguente:

Il metodo download_blob restituisce un oggetto StorageStreamDownloader. Durante un download, le librerie client suddividono la richiesta di download in blocchi. Ogni blocco viene scaricato con una richiesta di intervallo Get Blob separata. Questo comportamento dipende dalle dimensioni totali del BLOB e dal modo in cui sono impostate le opzioni di trasferimento dei dati.

Scaricare in un percorso di file

L'esempio seguente scarica un BLOB in un percorso di file:

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

Scaricare in un flusso

L'esempio seguente scarica un BLOB in un flusso. In questo esempio, StorageStreamDownloader.read_into scarica il contenuto del BLOB in un flusso e restituisce il numero di byte letti:

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

Scaricare un BLOB in blocchi

L'esempio seguente scarica un BLOB ed esegue l'iterazione sui blocchi nel flusso di download. In questo esempio StorageStreamDownloader.chunks restituisce un iteratore, che consente di leggere il contenuto del BLOB in blocchi:

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)

Scaricare in una stringa

L'esempio seguente scarica il contenuto del BLOB come testo. In questo esempio il parametro encoding è necessario perché readall() restituisca una stringa; in caso contrario, restituisce byte:

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

Scaricare un BLOB in blocchi con le opzioni di configurazione

È possibile definire le opzioni di configurazione della libreria client durante il download di un BLOB. Queste opzioni possono essere ottimizzate per migliorare le prestazioni e l'affidabilità. Gli esempi di codice seguenti illustrano come definire le opzioni di configurazione per un download quando si crea un'istanza di BlobClient, sia a livello di metodo, sia a livello di client. Queste opzioni possono essere configurate anche per un'istanza di ContainerClient o per un'istanza di BlobServiceClient.

Specificare le opzioni di trasferimento dei dati al download

È possibile impostare le opzioni di configurazione al momento della creazione di un'istanza di un client in modo da ottimizzare le prestazioni per le operazioni di trasferimento dei dati. Quando si costruisce un oggetto client in Python, è possibile passare gli argomenti della parola chiave seguenti:

  • max_chunk_get_size: dimensioni massime del blocco da usare per il download di un BLOB. Il valore predefinito è 4 MiB.
  • max_single_get_size: dimensioni massime per eseguire il download di un BLOB in una singola chiamata. Se le dimensioni totali del BLOB superano max_single_get_size, il resto dei dati BLOB viene scaricato in blocchi. Il valore predefinito è 32 MiB.

Per le operazioni di download è anche possibile passare l'argomento max_concurrency quando si chiama download_blob. Questo argomento definisce il numero massimo di connessioni parallele per l'operazione di download.

L'esempio di codice seguente mostra come specificare le opzioni di trasferimento dei dati durante la creazione di un oggetto BlobClient e come scaricare i dati usando tale oggetto client. I valori forniti in questo esempio non sono necessariamente quelli consigliati. Per ottimizzare correttamente questi valori è necessario considerare le esigenze specifiche dell'app.

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

Scaricare BLOB in modo asincrono

La libreria client di Archiviazione BLOB di Azure per Python supporta il download asincrono dei BLOB. Per altre informazioni sui requisiti di configurazione del progetto, vedere Programmazione asincrona.

Seguire questa procedura per scaricare un BLOB usando le API asincrone:

  1. Aggiungere le seguenti istruzioni Import:

    import asyncio

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

  2. Aggiungere il codice per eseguire il programma utilizzando asyncio.run. Questa funzione esegue la coroutine passata, main() nell'esempio, e gestisce il ciclo di eventi asyncio. Le coroutine vengono dichiarate con la sintassi async/await. In questo esempio, la coroutine main() crea innanzitutto il BlobServiceClient di primo livello usando async with, quindi chiama il metodo che scarica il BLOB. Si noti che solo il client di primo livello deve usare async with, poiché gli altri client creati da esso condividono lo stesso pool di connessioni.

    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. Aggiungere codice per scaricare il BLOB. L'esempio seguente scarica un BLOB in un percorso di file locale usando un oggetto BlobClient. Il codice è uguale a quello dell'esempio sincrono, ad eccezione del fatto che il metodo viene dichiarato con la parola chiave async e che quando si chiama il metodo download_blob viene usata la parola chiave await.

    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 questa configurazione di base, è possibile implementare altri esempi in questo articolo come coroutine usando la sintassi async/await.

Risorse

Per altre informazioni su come scaricare i BLOB tramite la libreria client di Archiviazione BLOB di Azure per Python, vedere le risorse seguenti.

Esempi di codice

Operazioni dell'API REST

Azure SDK per Python contiene librerie basate sull'API REST di Azure, che consentono di interagire con le operazioni dell'API REST tramite paradigmi Python noti. I metodi della libreria client per scaricare i BLOB usano l'operazione API REST seguente:

Risorse della libreria client

Contenuto correlato

  • Questo articolo fa parte della Guida per sviluppatori di Archiviazione BLOB per Python. Per altre informazioni, vedere l’elenco completo degli articoli della Guida per sviluppatori in Creare la propria app Python.