Compartir vía

Copiar un blob con programación asincrónica mediante Go

  • Artículo

En este artículo se muestra cómo copiar un blob con programación asincrónica mediante el módulo de cliente de Azure Storage para Go. Puede copiar un blob desde un origen dentro de la misma cuenta de almacenamiento, desde un origen en una cuenta de almacenamiento diferente o desde cualquier objeto accesible recuperado a través de una solicitud HTTP GET en una dirección URL determinada. También puede anular una operación de copia pendiente.

Los métodos descritos en este artículo usan la operación de la API de REST Copiar blob y se pueden usar cuando desee realizar una copia con programación asincrónica. Para la mayoría de los escenarios de copia en los que desea mover datos a una cuenta de almacenamiento y tener una dirección URL para el objeto de origen, consulte Copia de un blob desde una dirección URL de objeto de origen con Go.

Requisitos previos

Configurar el entorno

Si no tiene un proyecto existente, esta sección muestra cómo configurar un proyecto para trabajar con el módulo cliente Azure Blob Storage para Go. Los pasos incluyen la instalación del módulo, la adición de rutas de acceso de import y la creación de un objeto de cliente autorizado. Para obtener información, consulte Introducción a Azure Blob Storage y Go.

Módulos de instalación

Instale el módulo azblob mediante el siguiente comando:

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

Para autenticarse con Microsoft Entra ID (recomendado), instale el módulo azidentity mediante el siguiente comando:

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

Agregar rutas de importación

En el archivo de código, agregue las rutas de importación siguientes:

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

Estas rutas de importación representan el mínimo necesario para empezar. Algunos ejemplos de código de este artículo pueden requerir rutas de importación adicionales. Para obtener detalles específicos y ejemplos de uso, consulte Ejemplos de código.

Creación de un objeto de cliente

Para conectar una aplicación a Blob Storage, cree un objeto de cliente mediante azblob.NewClient. En el ejemplo siguiente se muestra cómo crear un objeto de cliente mediante DefaultAzureCredential para la autorización:

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
}

Authorization

El mecanismo de autorización debe tener los permisos necesarios para realizar una operación de copia, o para abortar una copia pendiente. Para la autorización con Microsoft Entra ID (recomendado) se necesita el rol integrado de RBAC de Azure de Colaborador de datos de Storage Blob o superior. Para obtener más información, consulte la guía de autorización de Copia de blob o Anular copia de blob.

Acerca de la copia de blobs con programación asincrónica

La operación Copy Blob puede finalizar de forma asincrónica y se realiza en función del mejor esfuerzo, lo que significa que no se garantiza que la operación se inicie inmediatamente o se complete dentro de un período de tiempo especificado. La operación de copia se programa en segundo plano y se realiza cuando el servidor tiene recursos disponibles. La operación se puede completar sincrónicamente si la copia se produce dentro de la misma cuenta de almacenamiento.

Una operación Copy Blob puede realizar cualquiera de las siguientes acciones:

  • Copie un blob de origen en un blob de destino con un nombre diferente. El blob de destino puede ser un blob existente del mismo tipo de blob (en bloques, anexos o en páginas), o puede ser un nuevo blob creado por la operación de copia.
  • Copie un blob de origen en un blob de destino con el mismo nombre, lo que reemplaza el blob de destino. Este tipo de operación de copia quita los bloques sin confirmar y sobrescribe los metadatos del blob de destino.
  • Copie un archivo de origen del servicio Azure File en un blob de destino. El blob de destino puede ser un blob en bloques existente o un nuevo blob de ese tipo creado por la operación de copia. No se admite la copia de archivos a blobs en páginas o blobs en anexos.
  • Copie una instantánea sobre su blob base. Si se mueve una instantánea a la posición del blob, puede restaurar una versión anterior de un blob.
  • Copie una instantánea en un blob de destino con otro nombre. El blob resultante de destino es un blob en el que se puede escribir y no una instantánea.

El blob de origen para una operación de copia puede ser de los siguientes tipos: blob en bloques, blob anexo, blob en páginas, instantánea de blob o la versión de un blob. La operación de copia siempre copia todo el blob o archivo de origen. No se admite la copia de un intervalo de bytes o un conjunto de bloques.

Si el blob de destino ya existe, debe ser del mismo tipo de blob que el blob de origen y se sobrescribe el blob de destino existente. El blob de destino no se puede modificar mientras está en curso una operación de copia y un blob de destino solo puede tener una operación de copia pendiente.

Para obtener más información sobre la operación Copy Blob, incluida la información sobre las propiedades, las etiquetas de índice, los metadatos y la facturación, consulte Comentarios sobre la copia de blobs.

Copiar un blob con programación asincrónica

En esta sección se proporciona información general sobre los métodos proporcionados por el módulo de cliente de Azure Storage para Go para realizar una operación de copia con programación asincrónica.

Los métodos siguientes encapsulan la operación de la API de REST Copiar blob y comienzan una copia asincrónica de los datos del blob de origen:

Copiar un blob desde un origen dentro de Azure

Si va a copiar un blob dentro de la misma cuenta de almacenamiento, la operación se puede completar de forma sincrónica. El acceso al blob de origen se puede autorizar mediante Microsoft Entra ID (recomendado), una firma de acceso compartido (SAS) o una clave de cuenta. Para obtener una operación de copia sincrónica alterativa, consulte Copiar un blob desde una dirección URL de objeto de origen con Go.

Si el origen de copia es un blob en otra cuenta de almacenamiento, la operación se puede completar de forma asincrónica. El blob de origen debe ser público o autorizado a través del token de SAS. El token de SAS debe incluir el permiso Lectura (“r”). Para más información sobre los tokens de SAS, consulte Delegación del acceso con firmas de acceso compartido.

En el ejemplo siguiente se muestra un escenario para copiar un blob de origen desde otra cuenta de almacenamiento con programación asincrónica. En este ejemplo, se crea una dirección URL de blob de origen con un token de SAS de delegación de usuarios anexado. En el ejemplo se supone que proporciona su propia SAS. En este ejemplo también se muestra cómo conceder el blob de origen durante la operación de copia para evitar cambios en el blob desde un cliente diferente. La operación Copy Blob guarda el valor ETag del blob de origen cuando se inicia la operación de copia. Si el valor ETag se cambia antes de que finalice la operación de copia, se produce un error en la operación. En este ejemplo, también se establece el nivel de acceso del blob de destino en Cool mediante la estructura 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)
}

En el siguiente ejemplo se muestra un ejemplo de uso:

// 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:

Los tokens de SAS de delegación de usuarios ofrecen mayor seguridad, ya que se firman con credenciales de Microsoft Entra en lugar de con una clave de cuenta. Para crear un token de SAS de delegación de usuarios, la entidad de seguridad de Microsoft Entra necesita los permisos adecuados. Para conocer los requisitos de autorización, consulte Obtención de la clave de delegación de usuarios.

Copiar un blob desde un origen externo a Azure

Puede realizar una operación de copia en cualquier objeto de origen que se pueda recuperar a través de solicitudes HTTP GET en una dirección URL determinada, incluyendo los objetos accesibles de fuera de Azure. En el ejemplo siguiente se muestra un escenario para copiar un blob desde una dirección URL de objeto de origen accesible:

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
    }
}

En el siguiente ejemplo se muestra un ejemplo de uso:

externalURL := "<source-url>"

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

copyFromExternalSourceAsync(externalURL, destBlob)

Comprobación del estado de una operación de copia

Para comprobar el estado de una operación asincrónica de Copy Blob, puede sondear el método GetProperties y comprobar el estado de la copia.

El siguiente ejemplo de código muestra cómo comprobar el estado de una operación de 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)
}

Anulación de una operación de copia

La anulación de una operación Copy Blob pendiente da como resultado un blob de destino de longitud cero. Sin embargo, los nuevos valores de los metadatos del blob de destino se copian del blob de origen o se establecen explícitamente durante la operación de copia. Para conservar los metadatos originales anteriores a la copia, cree una instantánea del blob de destino antes de llamar a uno de los métodos de copia.

Para anular una operación de copia pendiente, llame a la siguiente operación:

Estos métodos encapsulan la operación de la API de RESTAnular copia de blob, que cancela una operación Copy Blob pendiente. El siguiente ejemplo de código muestra cómo anular una operación Copy Blob pendiente:

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)
    }
}

Recursos

Para obtener más información sobre cómo descargar blobs con programación asincrónica usando el módulo de cliente de Azure Blob Storage para Go, consulte los recursos siguientes.

Ejemplos de código

Operaciones de API REST

El SDK de Azure para Go contiene bibliotecas que se crean a partir de la API de REST de Azure, lo que le permite interactuar con las operaciones de API de REST a través de paradigmas conocidos de Go. Los métodos descritos en este artículo usan las siguientes operaciones de la API de REST:

Recursos del módulo cliente

Contenido relacionado

  • Este artículo forma parte de la guía para desarrolladores de Blob Storage para Go. Para obtener más información, consulte la lista completa de artículos de la guía para desarrolladores en Compilación de la aplicación Go.