Caricare un BLOB in blocchi con Python

Articolo
11/16/2023

Questo articolo illustra come caricare un BLOB usando la libreria client 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 di indice.

Per informazioni sul caricamento di BLOB tramite API asincrone, vedere Caricare i BLOB in modo asincrono.

Prerequisiti

Questo articolo presuppone che sia già stato configurato un progetto per lavorare con la libreria client Archiviazione BLOB di Azure per Python. Per informazioni sulla configurazione del progetto, tra cui l'installazione del pacchetto, l'aggiunta import di istruzioni e la creazione di un oggetto client autorizzato, vedere Introduzione a 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 caricamento. Per altre informazioni, vedere le linee guida per l'autorizzazione per le operazioni API REST seguenti:
- Put Blob
- Put Block

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 complessive dell'oggetto e dalla modalità di impostazione delle 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 BlobClient oggetto :

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 BytesIO oggetto in un BLOB in blocchi usando un BlobClient oggetto :

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 BlobClient oggetto :

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 di indice

L'esempio seguente carica un BLOB in blocchi con tag di 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 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, migliorare l'affidabilità e ottimizzare i costi. Gli esempi di codice seguenti illustrano come definire le opzioni di configurazione per un caricamento sia a livello di metodo che a livello di client durante la creazione di un'istanza di BlobClient. Queste opzioni possono essere configurate anche per un'istanza containerClient o un'istanza BlobServiceClient .

Specificare le opzioni di trasferimento dei dati per il caricamento

È possibile impostare le opzioni di configurazione quando si crea un'istanza di un client per ottimizzare le prestazioni per le operazioni di trasferimento dei dati. È possibile passare gli argomenti di parola chiave seguenti durante la costruzione di un oggetto client in Python:

max_block_size - Dimensioni massime del blocco per il caricamento di un BLOB in blocchi in blocchi. Il valore predefinito è 4 MiB.
max_single_put_size - Se le dimensioni del BLOB sono minori o uguali a max_single_put_size, il BLOB viene caricato con una singola Put Blob richiesta. 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 BlockPut Block List. Il valore predefinito è 64 MiB.

Per altre informazioni sui limiti delle dimensioni di trasferimento per i Archiviazione BLOB, vedere Destinazioni di scalabilità per l'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.

Nell'esempio di codice seguente viene illustrato come specificare le opzioni di trasferimento dei dati durante la creazione di un BlobClient oggetto e come caricare i dati usando tale oggetto client. I valori forniti in questo esempio non devono essere 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 caricamenti e download con Python.

Impostare il livello di accesso di un BLOB al caricamento

È possibile impostare il livello di accesso di un BLOB al caricamento passando l'argomento standard_blob_tier parola chiave 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, Coldo Archive. Per impostare il livello di accesso su Cold, è necessario usare una versione minima della libreria client 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 Archiviazione BLOB di Azure per Python supporta il caricamento asincrono dei BLOB. Per altre informazioni sui requisiti di configurazione del progetto, vedere Programmazione asincrona.

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

Aggiungere le seguenti istruzioni Import:

import asyncio

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

Aggiungere il codice per eseguire il programma usando asyncio.run. Questa funzione esegue la coroutine passata, main() nell'esempio, e gestisce il asyncio ciclo di eventi. Le coroutine vengono dichiarate con la sintassi async/await. In questo esempio la main() coroutine crea prima il primo livello BlobServiceClient usando async with, quindi chiama il metodo che carica il BLOB. Si noti che solo il client di primo livello deve usare async with, come 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.upload_blob_file(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())
```

Aggiungere il codice per caricare il BLOB. Nell'esempio seguente viene caricato un BLOB da un percorso di file locale usando un ContainerClient oggetto . Il codice è uguale all'esempio sincrono, ad eccezione del fatto che il metodo viene dichiarato con la async parola chiave e la await parola chiave viene usata quando si chiama il upload_blob metodo .

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 usando la libreria client 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 il caricamento di BLOB usano le operazioni API REST seguenti:

Share via