Compartilhar via

Copiar um blob com agendamento assíncrono usando o .NET

  • Artigo

Este artigo mostra como copiar um blob com agendamento assíncrono usando a biblioteca de clientes do Armazenamento do Azure para .NET. 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 de biblioteca de clientes abordados neste artigo usam a operação da API REST Copiar Blob e pode ser usado quando você deseja 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, confira Copiar um blob de uma URL de objeto de origem com o .NET.

Pré-requisitos

Configure seu ambiente

Se você não tiver um projeto existente, esta seção mostrará como configurar um projeto para funcionar com a biblioteca de clientes do Armazenamento de Blobs do Azure para .NET. As etapas incluem a instalação do pacote, a adição de diretivas using e a criação de um objeto de cliente autorizado. Para obter detalhes, consulte Introdução ao Armazenamento de Blobs do Azure e ao .NET.

Instalar Pacotes

No diretório do projeto, instale pacotes para as bibliotecas de cliente do Armazenamento de Blobs do Azure e do Azure Identity usando o comando dotnet add package. O pacote Azure.Identity é necessário para conexões sem senha com os serviços do Azure.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Adicione diretivas using

Adicione essas diretivas using ao topo do seu arquivo de código:

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

Alguns exemplos de código neste artigo podem exigir diretivas using adicionais.

Criar um objeto cliente

Para conectar um aplicativo ao Armazenamento de Blobs, crie uma instância do BlobServiceClient. O exemplo a seguir mostra como criar um objeto cliente usando DefaultAzureCredential para autorização:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

Você pode registrar um cliente de serviço para injeção de dependência em um aplicativo .NET.

Você também pode criar objetos cliente para contêineres ou blobs específicos. Para saber mais sobre como criar e gerenciar objetos clientes, confira Criar e gerenciar objetos clientes que interagem com recursos de dados.

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), a função interna do RBAC do Azure com menos privilégios varia de acordo com vários fatores. Para saber mais, consulte as diretrizes de autorização para Copiar blob (API REST) e Anular cópia do blob (API REST).

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.

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 pela biblioteca de clientes do Armazenamento do Azure para .NET 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:

Os métodos StartCopyFromUri e StartCopyFromUriAsync retornam um objeto CopyFromUriOperation que contém informações sobre a operação de cópia. Esses métodos são usados quando você deseja agendamento assíncrono para uma operação de cópia.

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 do Microsoft Entra ID, uma Assinatura de Acesso Compartilhado (SAS) ou uma chave de conta. Para uma operação de cópia síncrona alterativa, confira Copiar um blob de uma URL de objeto de origem com .NET.

Se a origem 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 mostra como gerar o token SAS usando a biblioteca de clientes, mas você também pode fornecer o seu próprio. 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á.

//-------------------------------------------------
// Copy a blob from a different storage account
//-------------------------------------------------
public static async Task CopyAcrossStorageAccountsAsync(
    BlobClient sourceBlob,
    BlockBlobClient destinationBlob)
{
    // Lease the source blob to prevent changes during the copy operation
    BlobLeaseClient sourceBlobLease = new(sourceBlob);

    // Create a Uri object with a SAS token appended - specify Read (r) permissions
    Uri sourceBlobSASURI = await GenerateUserDelegationSAS(sourceBlob);

    try
    {
        await sourceBlobLease.AcquireAsync(BlobLeaseClient.InfiniteLeaseDuration);

        // Start the copy operation and wait for it to complete
        CopyFromUriOperation copyOperation = await destinationBlob.StartCopyFromUriAsync(sourceBlobSASURI);
        await copyOperation.WaitForCompletionAsync();
    }
    catch (RequestFailedException ex)
    {
        // Handle the exception
    }
    finally
    {
        // Release the lease once the copy operation completes
        await sourceBlobLease.ReleaseAsync();
    }
}

async static Task<Uri> GenerateUserDelegationSAS(BlobClient sourceBlob)
{
    BlobServiceClient blobServiceClient =
        sourceBlob.GetParentBlobContainerClient().GetParentBlobServiceClient();

    // Get a user delegation key for the Blob service that's valid for 1 day
    UserDelegationKey userDelegationKey =
        await blobServiceClient.GetUserDelegationKeyAsync(DateTimeOffset.UtcNow,
                                                          DateTimeOffset.UtcNow.AddDays(1));

    // Create a SAS token that's also valid for 1 day
    BlobSasBuilder sasBuilder = new BlobSasBuilder()
    {
        BlobContainerName = sourceBlob.BlobContainerName,
        BlobName = sourceBlob.Name,
        Resource = "b",
        StartsOn = DateTimeOffset.UtcNow,
        ExpiresOn = DateTimeOffset.UtcNow.AddDays(1)
    };

    // Specify read permissions for the SAS
    sasBuilder.SetPermissions(BlobSasPermissions.Read);

    // Add the SAS token to the blob URI
    BlobUriBuilder blobUriBuilder = new BlobUriBuilder(sourceBlob.Uri)
    {
        // Specify the user delegation key
        Sas = sasBuilder.ToSasQueryParameters(userDelegationKey,
                                              blobServiceClient.AccountName)
    };

    return blobUriBuilder.ToUri();
}

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.

//-------------------------------------------------
// Copy a blob from an external source
//-------------------------------------------------
public static async Task CopyFromExternalSourceAsync(
    string sourceLocation,
    BlockBlobClient destinationBlob)
{
    Uri sourceUri = new(sourceLocation);

    // Start the copy operation and wait for it to complete
    CopyFromUriOperation copyOperation = await destinationBlob.StartCopyFromUriAsync(sourceUri);
    await copyOperation.WaitForCompletionAsync();
}

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

Para verificar o status de uma operação Copy Blob, você pode chamar UpdateStatusAsync e analisar a resposta para obter o valor do cabeçalho x-ms-copy-status.

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

public static async Task CheckCopyStatusAsync(CopyFromUriOperation copyOperation)
{
    // Check for the latest status of the copy operation
    Response response = await copyOperation.UpdateStatusAsync();

    // Parse the response to find x-ms-copy-status header
    if (response.Headers.TryGetValue("x-ms-copy-status", out string value))
        Console.WriteLine($"Copy status: {value}");
}

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 uma das operações a seguir:

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

public static async Task AbortBlobCopyAsync(
    CopyFromUriOperation copyOperation,
    BlobClient destinationBlob)
{
    // Check for the latest status of the copy operation
    Response response = await copyOperation.UpdateStatusAsync();

    // Parse the response to find x-ms-copy-status header
    if (response.Headers.TryGetValue("x-ms-copy-status", out string value))
    {
        if (value == "pending")
        {
            await destinationBlob.AbortCopyFromUriAsync(copyOperation.Id);
            Console.WriteLine($"Copy operation {copyOperation.Id} aborted");
        }
    }
}

Recursos

Para saber mais sobre como copiar blobs usando a biblioteca de clientes do Armazenamento de Blobs do Azure para .NET, consulte os recursos a seguir.

Exemplos de código

Operações da API REST

O SDK do Azure para .NET contém bibliotecas que criam sobre a API REST do Azure, permitindo a interação com as operações de API REST por meio de paradigmas conhecidos do .NET. Os métodos de biblioteca de clientes abordados neste artigo usam as seguintes operações de API REST:

Recursos da biblioteca de clientes

Conteúdo relacionado

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