Condividi tramite

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

  • Questo articolo presuppone che sia già stato configurato un progetto per l'uso con la libreria client di Archivio 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 Archivio BLOB di Azure e Python.
  • Il meccanismo di autorizzazione deve disporre delle autorizzazioni per eseguire un'operazione di copia o per interrompere una copia in sospeso. Per altre informazioni, vedere le linee guida per l'autorizzazione per l'operazione API REST seguente:

Informazioni sulla copia di BLOB con pianificazione asincrona

L'operazione Copy Blob può terminare in modo asincrono e viene eseguita in modo ottimale, il che significa che l'operazione non è garantita l'avvio immediato o il completamento entro un intervallo di tempo specificato. L'operazione di copia viene pianificata in background ed eseguita come il server dispone di risorse disponibili. L'operazione può essere completata in modo sincrono se la copia si verifica 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 di BLOB (blocco, accodamento o pagina) oppure può essere un nuovo BLOB creato dall'operazione di copia.
  • Copiare un BLOB di origine in un BLOB di destinazione con lo stesso nome, che sostituisce il BLOB di destinazione. Questo tipo di operazione di copia rimuove i blocchi non inviati 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ò essere 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 del 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 della 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 della delega utente, l'entità di sicurezza di Microsoft Entra necessita delle autorizzazioni appropriate. Per i requisiti di autorizzazione, vedere Ottenere la chiave di delega utente.

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

È possibile eseguire un'operazione di copia su qualsiasi oggetto di origine che possa essere recuperato 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 comporta un BLOB di destinazione di lunghezza zero. Tuttavia, i metadati per il BLOB di destinazione hanno i nuovi valori 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. Nell'esempio di codice seguente viene illustrato 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.

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

Esempi di codice

Risorse per la libreria client