Condividi tramite

Copiare un BLOB con pianificazione asincrona tramite Go

  • Articolo

Questo articolo illustra come copiare un BLOB con pianificazione asincrona usando il modulo client di Archiviazione di Azure per Go. È 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 descritti in questo articolo usano l'operazione API REST Copy 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 si ha un URL per l'oggetto di origine, vedere Copiare un BLOB da un URL dell'oggetto di origine con Go.

Prerequisiti

Configurazione dell'ambiente

Se non si ha un progetto esistente, questa sezione illustra come configurare un progetto per l'uso con il modulo client di Archiviazione BLOB di Azure per Go. I passaggi includono l'installazione del modulo, l'aggiunta di percorsi import e la creazione di un oggetto client autorizzato. Per informazioni dettagliate, vedere Introduzione all'archiviazione BLOB di Azure e Go.

Installare i moduli

Installare il modulo azblob usando il comando seguente:

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

Per eseguire l'autenticazione con Microsoft Entra ID (scelta consigliata), installare il modulo azidentity usando il comando seguente:

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Aggiungere percorsi di importazione

Nel file di codice aggiungere i percorsi di importazione seguenti:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

Questi percorsi di importazione rappresentano il minimo necessario per iniziare. Alcuni esempi di codice in questo articolo potrebbero richiedere percorsi di importazione aggiuntivi. Per informazioni dettagliate specifiche e utilizzo di esempio, vedere Esempi di codice.

Creare un oggetto client

Per connettere un'app all'archiviazione BLOB, creare un oggetto client usando azblob. NewClient. Nell'esempio seguente viene illustrato come creare un oggetto client usando DefaultAzureCredential per l'autorizzazione:

func getServiceClientTokenCredential(accountURL string) *azblob.Client {
    // Create a new service client with token credential
    credential, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(accountURL, credential, nil)
    handleError(err)

    return client
}

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), è 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 Copy Blob o Abort Copy Blob.

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 dal modulo client di Archiviazione di Azure per Go 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:

Copiare un BLOB da un'origine all'interno di 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 (scelta consigliata), una firma di accesso condiviso o una chiave dell'account. Per un'operazione di copia sincrona alternativa, vedere Copiare un BLOB da un URL dell'oggetto di origine con Go.

Se l'origine della 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 presuppone l'inserimento della propria firma di accesso condiviso. 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. È stato inoltre impostato il livello di accesso per il BLOB di destinazione su Cool usando lo struct StartCopyFromURLOptions.

func copyFromSourceAsync(srcBlob *blockblob.Client, destBlob *blockblob.Client) {
    // Lease the source blob during copy to prevent other clients from modifying it
    blobLeaseClient, err := lease.NewBlobClient(srcBlob, nil)
    handleError(err)

    _, err = blobLeaseClient.AcquireLease(context.TODO(), int32(60), nil)
    handleError(err)

    // Retrieve the SAS token for the source blob and append it to the URL
    sas := "<sas-token>"
    url := srcBlob.URL() + "?" + sas

    // Set copy options
    copyOptions := blob.StartCopyFromURLOptions{
        Tier: to.Ptr(blob.AccessTierCool),
    }

    // Copy the blob from the source URL to the destination blob
    startCopy, err := destBlob.StartCopyFromURL(context.TODO(), url, &copyOptions)
    handleError(err)

    // If startCopy.CopyStatus returns a status of "pending", the operation has started asynchronously
    // You can optionally add logic to poll the copy status and wait for the operation to complete
    // Example:
    copyStatus := *startCopy.CopyStatus
    for copyStatus == blob.CopyStatusTypePending {
        time.Sleep(time.Second * 2)

        properties, err := destBlob.GetProperties(context.TODO(), nil)
        handleError(err)

        copyStatus = *properties.CopyStatus
    }

    // Release the lease on the source blob
    _, err = blobLeaseClient.ReleaseLease(context.TODO(), nil)
    handleError(err)
}

L'esempio seguente mostra l'utilizzo di esempio:

// TODO: replace <storage-account-name> placeholders with actual storage account names
srcURL := "https://<src-storage-account-name>.blob.core.windows.net/"
destURL := "https://<dest-storage-account-name>.blob.core.windows.net/"

credential, err := azidentity.NewDefaultAzureCredential(nil)
handleError(err)

srcClient, err := azblob.NewClient(srcURL, credential, nil)
handleError(err)
destClient, err := azblob.NewClient(destURL, credential, nil)
handleError(err)

srcBlob := srcClient.ServiceClient().NewContainerClient("source-container").NewBlockBlobClient("source-blob")
destBlob := destClient.ServiceClient().NewContainerClient("destination-container").NewBlockBlobClient("destination-blob-1")

copyFromSourceAsync(srcBlob, destBlob)

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 fa riferimento a uno scenario per la copia di un BLOB da un URL dell'oggetto di origine accessibile:

func copyFromExternalSourceAsync(srcURL string, destBlob *blockblob.Client) {
    // Set copy options
    copyOptions := blob.StartCopyFromURLOptions{
        Tier: to.Ptr(blob.AccessTierCool),
    }

    // Copy the blob from the source URL to the destination blob
    startCopy, err := destBlob.StartCopyFromURL(context.TODO(), srcURL, &copyOptions)
    handleError(err)

    // If startCopy.CopyStatus returns a status of "pending", the operation has started asynchronously
    // You can optionally add logic to poll the copy status and wait for the operation to complete
    // Example:
    copyStatus := *startCopy.CopyStatus
    for copyStatus == blob.CopyStatusTypePending {
        time.Sleep(time.Second * 2)

        properties, err := destBlob.GetProperties(context.TODO(), nil)
        handleError(err)

        copyStatus = *properties.CopyStatus
    }
}

L'esempio seguente mostra l'utilizzo di esempio:

externalURL := "<source-url>"

destBlob = destClient.ServiceClient().NewContainerClient("destination-container").NewBlockBlobClient("destination-blob-2")

copyFromExternalSourceAsync(externalURL, destBlob)

Controllare lo stato di un'operazione di copia

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

L'esempio di codice seguente illustra come controllare lo stato di un'operazione di copia:

func checkCopyStatus(destBlob *blockblob.Client) {
    // Retrieve the properties from the destination blob
    properties, err := destBlob.GetProperties(context.TODO(), nil)
    handleError(err)

    copyID := *properties.CopyID
    copyStatus := *properties.CopyStatus

    fmt.Printf("Copy operation %s is %s\n", copyID, copyStatus)
}

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 Abort Copy Blob, che annulla un'operazione Copy Blob in sospeso. L'esempio di codice seguente illustra come interrompere un'operazione Copy Blob in sospeso:

func abortCopy(destBlob *blockblob.Client) {
    // Retrieve the copy ID from the destination blob
    properties, err := destBlob.GetProperties(context.TODO(), nil)
    handleError(err)

    copyID := *properties.CopyID
    copyStatus := *properties.CopyStatus

    // Abort the copy operation if it's still pending
    if copyStatus == blob.CopyStatusTypePending {
        _, err := destBlob.AbortCopyFromURL(context.TODO(), copyID, nil)
        handleError(err)

        fmt.Printf("Copy operation %s aborted\n", copyID)
    }
}

Risorse

Per altre informazioni sulla copia di BLOB con pianificazione asincrona tramite il modulo client di Archiviazione BLOB di Azure per Go, vedere le risorse seguenti.

Esempi di codice

Operazioni dell'API REST

Azure SDK per Go contiene librerie basate sull'API REST di Azure che consentono di interagire con le operazioni dell'API REST tramite paradigmi Go noti. I metodi descritti in questo articolo usano le operazioni API REST seguenti:

Risorse del modulo client

Contenuto correlato

  • Questo articolo fa parte della Guida per sviluppatori di Archiviazione BLOB per Go. Per altre informazioni, vedere l’elenco completo degli articoli della Guida per sviluppatori inCreare la propria app Go.