Copiare un BLOB con pianificazione asincrona tramite Python

  • Articolo

Questo articolo illustra come copiare un BLOB con pianificazione asincrona usando la libreria client di Archiviazione di Azure per Python. È possibile copiare un BLOB da un'origine all'interno dello stesso account di archiviazione, da un'origine in un account di archiviazione diverso o da qualsiasi oggetto accessibile recuperato tramite una richiesta HTTP GET in un determinato URL. È anche possibile interrompere un'operazione di copia in sospeso.

I metodi della libreria client illustrati in questo articolo usano l'operazione API REST Copia BLOB e possono essere usati quando si vuole eseguire una copia con pianificazione asincrona. Per la maggior parte degli scenari di copia in cui si vogliono spostare i dati in un account di archiviazione e avere un URL per l'oggetto di origine, vedere Copiare un BLOB da un URL dell'oggetto di origine con Python.

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 datetime
from azure.identity import DefaultAzureCredential
from azure.storage.blob import (
    BlobServiceClient,
    BlobClient,
    BlobLeaseClient,
    BlobSasPermissions,
    generate_blob_sas
)

Autorizzazione

Il meccanismo di autorizzazione deve disporre delle autorizzazioni necessarie per eseguire un'operazione di copia o per interrompere una copia in sospeso. Per l'autorizzazione con Microsoft Entra ID (scelta consigliata), il ruolo predefinito Controllo degli accessi in base al ruolo di Azure con privilegi minimi varia in base a diversi fattori. Per altre informazioni, vedere le indicazioni sulle autorizzazioni per Copy Blob (API REST) o Abort Copy 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.

Informazioni sulla copia di BLOB con pianificazione asincrona

L'operazione Copy Blob può terminare in modo asincrono e viene eseguita secondo il criterio del massimo sforzo, il che significa che non sono garantiti l'avvio immediato dell'operazione o il completamento entro un intervallo di tempo specificato. L'operazione di copia viene pianificata in background ed eseguita non appena il server ha risorse disponibili. L'operazione può essere completata in modo sincrono se la copia avviene all'interno dello stesso account di archiviazione.

Un'operazione Copy Blob può eseguire una delle azioni seguenti:

  • Copiare un BLOB di origine in un BLOB di destinazione con un nome diverso. Il BLOB di destinazione può essere un BLOB esistente dello stesso tipo (BLOB in blocchi, di accodamento o di pagine) oppure può trattarsi di un nuovo BLOB creato dall'operazione di copia.
  • Copiare un BLOB di origine in un BLOB di destinazione con lo stesso nome, sostituendo così il BLOB di destinazione. Questo tipo di operazione di copia rimuove i blocchi non sottoposti a commit e sovrascrive i metadati del BLOB di destinazione.
  • Copiare un file di origine nel servizio file di Azure in un BLOB di destinazione. Il BLOB di destinazione può essere un BLOB in blocchi esistente o può trattarsi di un nuovo BLOB in blocchi creato dall'operazione di copia. La copia da file a BLOB di pagine o BLOB di accodamento non è supportata.
  • Copiare uno snapshot sul relativo BLOB di base. Promuovendo uno snapshot alla posizione del BLOB di base, è possibile ripristinare la versione precedente di un BLOB.
  • Copiare uno snapshot in un BLOB di destinazione con un nome diverso. Il BLOB di destinazione risultante è un BLOB scrivibile, non uno snapshot.

Il BLOB di origine per un'operazione di copia può essere uno dei tipi seguenti: BLOB in blocchi, BLOB di accodamento, BLOB di pagine, snapshot BLOB o versione BLOB. L'operazione copia sempre l'intero BLOB o file di origine. La copia di un intervallo di byte o di un set di blocchi non è supportata.

Se il BLOB di destinazione esiste già, deve essere dello stesso tipo di BLOB del BLOB di origine e il BLOB di destinazione esistente viene sovrascritto. Il BLOB di destinazione non può essere modificato mentre è in corso un'operazione di copia e un BLOB di destinazione può avere una sola operazione di copia in sospeso.

Per altre informazioni sull'operazione Copy Blob, incluse le informazioni sulle proprietà, i tag di indice, i metadati e la fatturazione, vedere le osservazioni sulla copia di BLOB.

Copiare un BLOB con pianificazione asincrona

Questa sezione offre una panoramica dei metodi forniti dalla libreria client di Archiviazione di Azure per Python per eseguire un'operazione di copia con pianificazione asincrona.

I metodi seguenti eseguono il wrapping dell'operazione API REST Copia BLOB e avviano una copia asincrona dei dati dal BLOB di origine:

start_copy_from_url restituisce un dizionario contenente copy_status e copy_id. La proprietà copy_status ha esito positivo se la copia è stata completata in modo sincrono o in sospeso se la copia è stata avviata in modo asincrono.

Copiare un BLOB da un'origine in Azure

Se si copia un BLOB all'interno dello stesso account di archiviazione, l'operazione può essere completata in modo sincrono. L'accesso al BLOB di origine può essere autorizzato tramite Microsoft Entra ID, una firma di accesso condiviso (SAS) o una chiave dell'account. Per un'operazione di copia sincrona alterative, vedere Copiare un BLOB da un URL di un oggetto di origine con Python.

Se l'origine di copia è un BLOB in un account di archiviazione diverso, l'operazione può essere completata in modo asincrono. Il BLOB di origine deve essere pubblico o autorizzato tramite token di firma di accesso condiviso. Il token di firma di accesso condiviso deve includere l'autorizzazione di lettura ('r'). Per altre informazioni sui token di firma di accesso condiviso, vedere Delegare l'accesso con firme di accesso condiviso.

L'esempio seguente illustra uno scenario per la copia di un BLOB di origine da un account di archiviazione diverso con pianificazione asincrona. In questo esempio viene creato un URL del BLOB di origine con un token di firma di accesso condiviso di delega utente aggiunto. L'esempio mostra come generare il token di firma di accesso condiviso usando la libreria client, ma è anche possibile specificare il proprio. L'esempio mostra anche come creare un lease sul BLOB di origine durante l'operazione di copia per impedire modifiche al BLOB da un client diverso. L'operazione Copy Blob salva il valore ETag del BLOB di origine all'avvio dell'operazione di copia. Se il valore ETag viene modificato prima del completamento dell'operazione di copia, l'operazione non riesce.

def copy_from_source_in_azure_async(self, source_blob: BlobClient, destination_blob: BlobClient, blob_service_client: BlobServiceClient):
    # Lease the source blob during copy to prevent other clients from modifying it
    lease = BlobLeaseClient(client=source_blob)

    sas_token = self.generate_user_delegation_sas(blob_service_client=blob_service_client, source_blob=source_blob)
    source_blob_sas_url = source_blob.url + "?" + sas_token

    # Create an infinite lease by passing -1 as the lease duration
    lease.acquire(lease_duration=-1)

    # Start the copy operation - specify False for the requires_sync parameter
    copy_operation = dict()
    copy_operation = destination_blob.start_copy_from_url(source_url=source_blob_sas_url, requires_sync=False)
    
    # If start_copy_from_url returns copy_status of 'pending', the operation has been started asynchronously
    # You can optionally add logic here to wait for the copy operation to complete

    # Release the lease on the source blob
    lease.break_lease()

def generate_user_delegation_sas(self, blob_service_client: BlobServiceClient, source_blob: BlobClient):
    # Get a user delegation key
    delegation_key_start_time = datetime.datetime.now(datetime.timezone.utc)
    delegation_key_expiry_time = delegation_key_start_time + datetime.timedelta(hours=1)
    key = blob_service_client.get_user_delegation_key(
        key_start_time=delegation_key_start_time,
        key_expiry_time=delegation_key_expiry_time
    )

    # Create a SAS token that's valid for one hour, as an example
    sas_token = generate_blob_sas(
        account_name=blob_service_client.account_name,
        container_name=source_blob.container_name,
        blob_name=source_blob.blob_name,
        account_key=None,
        user_delegation_key=key,
        permission=BlobSasPermissions(read=True),
        expiry=datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(hours=1),
        start=datetime.datetime.now(datetime.timezone.utc)
    )

    return sas_token

Nota

I token di firma di accesso condiviso di delega utente offrono maggiore sicurezza, perché sono firmati con le credenziali di Microsoft Entra anziché con una chiave dell'account. Per creare un token di firma di accesso condiviso di delega utente, l'entità di sicurezza di Microsoft Entra necessita delle autorizzazioni appropriate. Per i requisiti di autorizzazione, vedere Get User Delegation Key.

Copiare un BLOB da un'origine all'esterno di Azure

È possibile eseguire un'operazione di copia su qualsiasi oggetto di origine recuperabile tramite una richiesta HTTP GET in un determinato URL, inclusi gli oggetti accessibili all'esterno di Azure. L'esempio seguente illustra uno scenario per la copia di un BLOB da un URL dell'oggetto di origine accessibile.

def copy_from_external_source_async(self, source_url: str, destination_blob: BlobClient):
    # Start the copy operation - specify False for the requires_sync parameter
    copy_operation = dict()
    copy_operation = destination_blob.start_copy_from_url(source_url=source_url, requires_sync=False)
    
    # If start_copy_from_url returns copy_status of 'pending', the operation has been started asynchronously
    # You can optionally add logic here to wait for the copy operation to complete

Controllare lo stato di un'operazione di copia

Per controllare lo stato di un'operazione Copy Blob asincrona, è possibile eseguire il polling del metodo get_blob_properties e controllare lo stato della copia.

Nell'esempio di codice seguente viene illustrato come controllare lo stato di un'operazione di copia in sospeso:

def check_copy_status(self, destination_blob: BlobClient):
    # Get the copy status from the destination blob properties
    copy_status = destination_blob.get_blob_properties().copy.status

    return copy_status

Interrompere un'operazione di copia

L'interruzione di un'operazione Copy Blob in sospeso produce un BLOB di destinazione di lunghezza zero. Per i metadati del BLOB di destinazione, tuttavia, i nuovi valori verranno copiati dal BLOB di origine o impostati in modo esplicito durante l'operazione di copia. Per mantenere i metadati originali prima della copia, creare uno snapshot del BLOB di destinazione prima di chiamare uno dei metodi di copia.

Per interrompere un'operazione di copia in sospeso, chiamare l'operazione seguente:

Questo metodo esegue il wrapping dell'operazione API REST Interrompi copia BLOB, che annulla un'operazione Copy Blob in sospeso. L'esempio di codice seguente illustra come interrompere un'operazione Copy Blob in sospeso:

def abort_copy(self, destination_blob: BlobClient):
    # Get the copy operation details from the destination blob properties
    copy_status = destination_blob.get_blob_properties().copy.status
    copy_id = destination_blob.get_blob_properties().copy.id

    # Check the copy status and abort if pending
    if copy_status == 'pending':
        destination_blob.abort_copy(copy_id)
        print(f"Copy operation {copy_id} has been aborted")

Risorse

Per altre informazioni sulla copia di BLOB con pianificazione asincrona tramite la libreria client di Archivio BLOB di Azure per Python, vedere le risorse seguenti.

Esempi di codice

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 illustrati in questo articolo usano le operazioni API REST seguenti:

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.