Share via

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

  • Questo articolo presuppone che sia già stato configurato un progetto per l'uso con la libreria client di Archiviazione BLOB di Azure per Python. Per informazioni sulla configurazione del progetto, tra cui l'installazione del pacchetto, l'aggiunta di istruzioni import e la creazione di un oggetto client autorizzato, vedere Introduzione ad Archiviazione BLOB di Azure e Python.
  • Per usare le API asincrone nel codice, vedere i requisiti nella sezione Programmazione asincrona.
  • Il meccanismo di autorizzazione deve disporre delle autorizzazioni per eseguire un'operazione di download. Per altre informazioni, vedere le linee guida per l'autorizzazione per l'operazione API REST seguente:

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 codice per eseguire il programma usando 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.

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:

Esempi di codice

Risorse per la libreria client