Caricare un BLOB in blocchi con Python

• .NET
• Java
• JavaScript
• Python
• Go

Questo articolo illustra come caricare un BLOB usando la libreria client di Archiviazione di Azure per Python. È possibile caricare dati in un BLOB in blocchi da un percorso di file, un flusso, un oggetto binario o una stringa di testo. È anche possibile caricare BLOB con tag indice.

Per informazioni su come caricare BLOB tramite API asincrone, vedere Caricare BLOB in modo asincrono.

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito
• Account di archiviazione di Azure: creare un account di archiviazione
• Python 3.8+

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
import uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobBlock, BlobClient, StandardBlobTier

Autorizzazione

Il meccanismo di autorizzazione deve disporre delle autorizzazioni necessarie per caricare un BLOB. Per l'autorizzazione con Microsoft Entra ID (scelta consigliata), è necessario disporre del ruolo predefinito di Controllo degli accessi in base al ruolo di Azure Collaboratore ai dati del BLOB di archiviazione o ruolo superiore. Per altre informazioni, vedere le indicazioni sulle autorizzazioni per Put Blob (API REST) e Put Block (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.

Caricare dati in un BLOB in blocchi

Per caricare un BLOB usando un flusso o un oggetto binario, usare il metodo seguente:

• upload_blob

Questo metodo crea un nuovo BLOB da un'origine dati con suddivisione automatica in blocchi, ovvero l'origine dati può essere suddivisa in blocchi più piccoli e caricati. Per eseguire il caricamento, la libreria client può usare Put Blob o una serie di chiamate Put Block seguite da Put Block List. Questo comportamento dipende dalle dimensioni totali dell'oggetto e dal modo in cui sono impostate le opzioni di trasferimento dei dati.

Caricare un BLOB in blocchi da un percorso di file locale

L'esempio seguente carica un file in un BLOB in blocchi usando un oggetto BlobClient:

def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)

Caricare un BLOB in blocchi da un flusso

L'esempio seguente crea byte casuali di dati e carica un oggetto BytesIO in un BLOB in blocchi usando un oggetto BlobClient:

def upload_blob_stream(self, blob_service_client: BlobServiceClient, container_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    input_stream = io.BytesIO(os.urandom(15))
    blob_client.upload_blob(input_stream, blob_type="BlockBlob")

Caricare dati binari in un BLOB in blocchi

L'esempio seguente carica i dati binari in un BLOB in blocchi usando un oggetto BlobClient:

def upload_blob_data(self, blob_service_client: BlobServiceClient, container_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    data = b"Sample data for blob"

    # Upload the blob data - default blob type is BlockBlob
    blob_client.upload_blob(data, blob_type="BlockBlob")

Caricare un BLOB in blocchi con tag indice

L'esempio seguente carica un BLOB in blocchi con tag indice:

def upload_blob_tags(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    sample_tags = {"Content": "image", "Date": "2022-01-01"}
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, tags=sample_tags)

Caricare un BLOB in blocchi con le opzioni di configurazione

È possibile definire le opzioni di configurazione della libreria client durante il caricamento di un BLOB. Queste opzioni possono essere ottimizzate per migliorare le prestazioni e l'affidabilità e ottimizzare i costi. Gli esempi di codice seguenti illustrano come definire le opzioni di configurazione per un caricamento 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 per il caricamento

È 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_block_size - Dimensioni massime del blocco per il caricamento di un BLOB in blocchi. Il valore predefinito è 4 MiB.
• max_single_put_size - Se la dimensione del BLOB è minore o uguale a max_single_put_size, il BLOB viene caricato con una singola richiesta Put BlobPut Blob. Se le dimensioni del BLOB sono maggiori max_single_put_size o sconosciute, il BLOB viene caricato in blocchi usando ed eseguito il commit usando Put Block Put Block List. Il valore predefinito è 64 MiB.

Per altre informazioni sui limiti delle dimensioni di trasferimento per Archiviazione BLOB, vedere Dimensionare le destinazioni per Archiviazione BLOB.

Per le operazioni di caricamento è anche possibile passare l'argomento max_concurrency quando si chiama upload_blob. Questo argomento definisce il numero massimo di connessioni parallele da usare quando le dimensioni del BLOB superano 64 MiB.

L'esempio di codice seguente mostra come specificare le opzioni di trasferimento dei dati durante la creazione di un oggetto BlobClient e come caricare 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 upload_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
    # Create a BlobClient object with data transfer options for upload
    blob_client = BlobClient(
        account_url=account_url, 
        container_name=container_name, 
        blob_name=blob_name,
        credential=DefaultAzureCredential(),
        max_block_size=1024*1024*4, # 4 MiB
        max_single_put_size=1024*1024*8 # 8 MiB
    )
    
    with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
        blob_client = blob_client.upload_blob(data=data, overwrite=True, max_concurrency=2)

Per altre informazioni sull'ottimizzazione delle opzioni di trasferimento dei dati, vedere Ottimizzazione delle prestazioni per i caricamenti e i download con Python.

Impostare il livello di accesso di un BLOB durante il caricamento

È possibile impostare il livello di accesso di un BLOB al caricamento passando l'argomento parola chiave standard_blob_tier a upload_blob. Archiviazione di Azure offre livelli di accesso diversi, quindi puoi archiviare i dati dei BLOB nel modo più conveniente in base al modo in cui vengono usati.

L'esempio di codice seguente illustra come impostare il livello di accesso durante il caricamento di un BLOB:

def upload_blob_access_tier(self, blob_service_client: BlobServiceClient, container_name: str, blob_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
    
    #Upload blob to the cool tier
    with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
        blob_client = blob_client.upload_blob(data=data, overwrite=True, standard_blob_tier=StandardBlobTier.COOL)

L'impostazione del livello di accesso è consentita solo per i BLOB in blocchi. È possibile impostare il livello di accesso per un BLOB in blocchi su Hot, Cool, Cold o Archive. Per impostare il livello di accesso su Cold, è necessario usare una libreria client almeno alla versione 12.15.0.

Per altre informazioni sui livelli di accesso, vedere Panoramica dei livelli di accesso.

Caricare un BLOB in blocchi tramite blocchi di staging e commit

È possibile avere un maggiore controllo su come dividere i caricamenti in blocchi eseguendo manualmente lo staging di singoli blocchi di dati. Quando tutti i blocchi che costituiscono un BLOB vengono gestiti in staging, è possibile eseguirne il commit nell'archiviazione BLOB.

Usare il metodo seguente per creare un nuovo blocco di cui eseguire il commit come parte di un BLOB:

• stage_block

Usare il metodo seguente per scrivere un BLOB specificando l'elenco di ID blocchi che costituiscono il BLOB:

• commit_block_list

L'esempio seguente legge i dati da un file e i blocchi di fasi di cui eseguire il commit come parte di un BLOB:

def upload_blocks(self, blob_container_client: ContainerClient, local_file_path: str, block_size: int):
    file_name = os.path.basename(local_file_path)
    blob_client = blob_container_client.get_blob_client(file_name)

    with open(file=local_file_path, mode="rb") as file_stream:
        block_id_list = []

        while True:
            buffer = file_stream.read(block_size)
            if not buffer:
                break

            block_id = uuid.uuid4().hex
            block_id_list.append(BlobBlock(block_id=block_id))

            blob_client.stage_block(block_id=block_id, data=buffer, length=len(buffer))

        blob_client.commit_block_list(block_id_list)

Caricare BLOB in modo asincrono

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

Seguire questa procedura per caricare 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, ContainerClient
   

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 carica il BLOB. Si noti che soltanto il client di primo livello deve utilizzare async with, poiché gli altri client da esso creati 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.upload_blob_file(blob_service_client, "sample-container")
   
   if __name__ == '__main__':
       asyncio.run(main())
   

3. Aggiungere il codice per caricare il BLOB. L'esempio seguente carica un BLOB da un percorso di file locale usando un oggetto ContainerClient. Il codice è uguale a quello dell'esempio sincrono, a eccezione del fatto che il metodo viene dichiarato con la parola chiave async e che quando si richiama il metodo upload_blob si utilizza la parola chiave await.

   async def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
       container_client = blob_service_client.get_container_client(container=container_name)
       with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
           blob_client = await container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)
   

Con questa configurazione di base, è possibile implementare altri esempi in questo articolo come coroutine usando la sintassi async/await.

Risorse

Per altre informazioni sul caricamento di BLOB con la libreria client di Archiviazione BLOB di Azure per Python, vedere le risorse seguenti.

Esempi di codice

• Vedere gli esempi di codice sincroni o asincroni di questo articolo (GitHub)

Operazioni dell'API REST

Azure SDK per Python contiene librerie basate su API REST di Azure che consentono di interagire con le operazioni API REST tramite paradigmi Python noti. I metodi della libreria client per caricare i BLOB usano le operazioni API REST seguenti:

• Put Blob (API REST)
• Put Block (API REST)

Risorse della libreria client

• Documentazione di riferimento della libreria client
• Codice sorgente della libreria client
• Pacchetto (PyPi)

Vedi anche

• Gestire e trovare i dati BLOB di Azure con tag indice BLOB
• Usare i tag indice BLOB per gestire e trovare dati nell’archiviazione BLOB di Azure

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.