Compartilhar via

Copiar um blob com o agendamento assíncrono usando o Go

  • Artigo

Este artigo mostra como copiar um blob com agendamento assíncrono usando o módulo cliente Armazenamento do Microsoft Azure para Go. Você pode copiar um blob de uma origem dentro da mesma conta de armazenamento, de uma origem em uma conta de armazenamento diferente ou de qualquer objeto acessível recuperado por meio de uma solicitação HTTP GET em um URL específico. Você também pode anular uma operação de cópia pendente.

Os métodos abordados neste artigo usam a operação Copiar Blob API REST e podem ser usados quando você quiser executar uma cópia com agendamento assíncrono. Para a maioria dos cenários de cópia em que você deseja mover dados para uma conta de armazenamento e ter uma URL para o objeto de origem, consulte Copiar um blob de uma URL de objeto de origem com o Go.

Pré-requisitos

Configure seu ambiente

Se você não tiver um projeto existente, esta seção mostrará como configurar um projeto para trabalhar com o módulo de cliente do Armazenamento de Blobs do Azure para Go. As etapas incluem a instalação do módulo, a adição de caminhos import e a criação de um objeto cliente autorizado. Para obter detalhes, consulte Introdução ao Armazenamento de Blobs do Azure e Go.

Instalar módulos

Instale o módulo azblob usando o seguinte comando:

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

Para autenticar com o Microsoft Entra ID (recomendado), instale o módulo azidentity usando o comando a seguir:

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

Adicionar caminhos de importação

No arquivo de código, adicione os seguintes caminhos de importação:

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

Esses caminhos de importação representam o mínimo necessário para começar. Alguns exemplos de código neste artigo podem exigir caminhos de importação adicionais. Para obter detalhes específicos e uso de exemplo, consulte Exemplos de código.

Criar um objeto cliente

Para conectar um aplicativo ao Armazenamento de Blobs, crie um objeto cliente usando azblob.NewClient. O exemplo a seguir mostra como criar um objeto cliente usando DefaultAzureCredential para autorização:

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
}

Autorização

O mecanismo de autorização deve ter as permissões necessárias para executar uma operação de cópia ou anular uma cópia pendente. Para autorização com o Microsoft Entra ID (recomendado), você precisa da função interna de Colaborador de Dados de Blob de Armazenamento ou superior do RBAC do Azure. Para saber mais, consulte as diretrizes de autorização para Copiar Blob ou anular Cópia de Blob.

Sobre como copiar blobs com agendamento assíncrono

A operação Copy Blob pode ser concluída de forma assíncrona e é executada da melhor maneira possível, o que significa que não há garantia de que a operação começará imediatamente ou será concluída dentro de um prazo especificado. A operação de cópia é agendada em segundo plano e executada conforme o servidor tem recursos disponíveis. A operação poderá ser concluída de forma síncrona se a cópia ocorrer na mesma conta de armazenamento.

Uma operação Copy Blob pode executar qualquer uma das ações a seguir:

  • Copie um blob de origem em um blob de destino com outro nome. O blob de destino pode ser um blob existente do mesmo tipo de blob (blocos, acréscimo ou páginas), ou pode ser um novo blob criado pela operação de cópia.
  • Copie um blob de origem para um blob de destino com o mesmo nome, isso substitui o blob de destino. Esse tipo de operação de cópia remove todos os blocos não confirmados e substitui os metadados do blob de destino.
  • Copie um arquivo de origem no serviço de Arquivo do Azure para um blob de destino. O blob de destino pode ser um blob de blocos existente ou pode ser um novo blob de blocos criado pela operação de cópia. Não há suporte para a cópia de arquivos para blobs de páginas ou blobs de acréscimo.
  • Copiar um instantâneo sobre seu blob de base. Promovendo um instantâneo para a posição do blob de base, você pode restaurar uma versão anterior de um blob.
  • Copiar um instantâneo para um blob de destino com um nome diferente. O blob de destino resultante é um blob gravável e não um instantâneo.

O blob de origem de uma operação de cópia pode ser um dos seguintes tipos: blob de blocos, blob de acréscimo, blob de página, instantâneo de blob ou versão de blob. A operação de cópia sempre copia o blob de origem inteiro. Não há suporte para a cópia de um intervalo de bytes ou um conjunto de blocos.

Se o blob de destino já existir, ele deve ser do mesmo tipo de blob que o blob de origem e o blob de destino existente será substituído. O blob de destino não pode ser modificado enquanto uma operação de cópia estiver em andamento e um blob de destino só pode ter uma operação de cópia pendente.

Para saber mais sobre a operação Copy Blob, incluindo informações sobre propriedades, marcas de índice, metadados e cobrança, confira Copiar comentários do Blob.

Copiar um blob com agendamento assíncrono

Esta seção fornece uma visão geral dos métodos fornecidos pelo módulo cliente do Armazenamento do Microsoft Azure para Go para executar uma operação de cópia com agendamento assíncrono.

Os seguintes métodos encapsulam a operação da API REST Copiar Blob e iniciam uma cópia assíncrona de dados do blob de origem:

Copiar um blob de uma fonte no Azure

Se você estiver copiando um blob dentro da mesma conta de armazenamento, a operação poderá ser concluída de forma síncrona. O acesso ao blob de origem pode ser autorizado por meio da ID do Microsoft Entra (recomendada), uma SAS (assinatura de acesso compartilhado) ou uma chave de conta. Para obter uma operação de cópia síncrona alterativa, consulte Copiar um blob de uma URL de objeto de origem com o Go.

Se a fonte da cópia for um blob em uma conta de armazenamento diferente, a operação poderá ser concluída de forma assíncrona. O blob de origem deve ser público ou autorizado por meio do token SAS. O token SAS precisa incluir a permissão de Leitura ("r"). Para saber mais sobre tokens SAS, confira Delegar acesso com assinaturas de acesso compartilhado.

O exemplo a seguir mostra um cenário para copiar um blob de origem de uma conta de armazenamento diferente com agendamento assíncrono. Neste exemplo, criamos uma URL de blob de origem com um token SAS de delegação de usuário acrescentado. O exemplo pressupõe que você forneça sua própria SAS. O exemplo também mostra como alugar o blob de origem durante a operação de cópia para impedir alterações no blob de um cliente diferente. A operação Copy Blob salva o valor ETag do blob de origem quando a operação de cópia é iniciada. Se o valor ETag for alterado antes da conclusão da operação de cópia, a operação falhará. Também definimos a camada de acesso do blob de destino para Cool usando o 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)
}

O exemplo a seguir mostra o uso de exemplo:

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

Observação

Os tokens SAS de delegação de usuário oferecem maior segurança, pois são assinados com as credenciais do Microsoft Entra em vez de uma chave de conta. Para criar um token SAS de delegação de usuário, a entidade de segurança do Microsoft Entra precisa de permissões apropriadas. Para obter os requisitos de autorização, consulte Obter a Chave de Delegação de Usuário.

Copiar um blob de uma origem fora do Azure

Você pode executar uma operação de cópia em qualquer objeto de origem que possa ser recuperado por meio da solicitação HTTP GET em um URL específico, incluindo objetos acessíveis fora do Azure. O exemplo a seguir mostra um cenário para copiar um blob de uma URL de objeto de origem acessível:

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

O exemplo a seguir mostra o uso de exemplo:

externalURL := "<source-url>"

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

copyFromExternalSourceAsync(externalURL, destBlob)

Verificar o status de uma operação de cópia

Para verificar o status de uma operação de Copy Blob assíncrona, você pode sondar o método GetProperties e verificar o status da cópia.

O exemplo de código a seguir mostra como verificar o status de uma operação de cópia:

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

Anular uma operação de cópia

Anular uma operação Copy Blob resulta em um blob de destino de comprimento zero. No entanto, os metadados para o blob de destino têm os novos valores copiados do blob de origem ou definidos explicitamente durante a operação de cópia. Para manter os metadados originais de antes da cópia, obtenha um instantâneo do blob de destino antes de chamar um dos métodos de cópia.

Para anular uma operação de cópia pendente, chame a operação a seguir:

Esse métodos encapsula a operação Anular Copiar Blob da API REST, que cancela uma operação Copy Blob pendente. O exemplo de código a seguir mostra como anular uma operação Copy Blob pendente:

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 saber mais sobre como copiar blobs com agendamento assíncrono usando o módulo cliente do Armazenamento de Blobs do Azure para Go, consulte os recursos a seguir.

Exemplos de código

Operações da API REST

O SDK do Azure para linguagem Go contém bibliotecas que se baseiam na API REST do Azure, permitindo a interação com as operações de API REST por meio de paradigmas conhecidos do Go. Os métodos abordados neste artigo usam as seguintes operações de API REST:

Recursos do módulo cliente

Conteúdo relacionado

  • Este artigo faz parte do guia para desenvolvedores do Armazenamento de Blobs para Go. Para saber mais, veja a lista completa de artigos do guia do desenvolvedor em Criar seu aplicativo Go.