Partilhar 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 cliente do Armazenamento do Azure para .NET. Você pode copiar um blob de uma fonte dentro da mesma conta de armazenamento, de uma fonte em uma conta de armazenamento diferente ou de qualquer objeto acessível recuperado via solicitação HTTP GET em uma determinada URL. Você também pode abortar uma operação de cópia pendente.

Os métodos de biblioteca de cliente abordados neste artigo usam a operação Copy Blob REST API e podem ser usados 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, consulte Copiar um blob de uma URL de objeto de origem com .NET.

Pré-requisitos

Configurar o ambiente

Se você não tiver um projeto existente, esta seção mostra como configurar um projeto para trabalhar com a biblioteca de cliente do Armazenamento de Blobs do Azure para .NET. As etapas incluem a instalação do pacote, a adição de using diretivas 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 o Armazenamento de Blobs do Azure e as bibliotecas de cliente do Azure Identity usando o dotnet add package comando. 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

Adicionar using diretivas

Adicione estas using diretivas à parte superior do 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 adicionais using .

Criar um objeto cliente

Para conectar um aplicativo ao Armazenamento de Blob, crie uma instância de 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 de cliente para contêineres ou blobs específicos. Para saber mais sobre como criar e gerenciar objetos de cliente, consulte Criar e gerenciar objetos de cliente 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 para anular uma cópia pendente. Para autorização com o Microsoft Entra ID (recomendado), a função interna menos privilegiada do RBAC do Azure varia com base em vários fatores. Para saber mais, consulte as diretrizes de autorização para Copiar Blob (API REST) ou Abortar Blob de Cópia (API REST).

Sobre a cópia de blobs com agendamento assíncrono

A Copy Blob operação pode ser concluída de forma assíncrona e é executada com base no melhor esforço, o que significa que não é garantido que a operação comece imediatamente ou seja concluída dentro de um período de tempo especificado. A operação de cópia é agendada em segundo plano e executada à medida que o servidor tem recursos disponíveis. A operação pode ser concluída de forma síncrona se a cópia ocorrer na mesma conta de armazenamento.

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

  • Copie um blob de origem para um blob de destino com um nome diferente. O blob de destino pode ser um blob existente do mesmo tipo de blob (bloco, acréscimo ou página), 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, que substitui o blob de destino. Esse tipo de operação de cópia remove quaisquer 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 bloco existente ou pode ser um novo blob de bloco criado pela operação de cópia. Não há suporte para copiar de arquivos para blobs de página ou acrescentar blobs.
  • Copie um instantâneo sobre seu blob base. Ao promover um instantâneo para a posição do blob base, você pode restaurar uma versão anterior de um blob.
  • Copie 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 Copy Blob operação, incluindo informações sobre propriedades, marcas de índice, metadados e cobrança, consulte Copiar comentários de Blob.

Copiar um blob com agendamento assíncrono

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

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

Os StartCopyFromUri métodos e StartCopyFromUriAsync retornam um objeto CopyFromUriOperation contendo 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 através do Microsoft Entra ID, de uma assinatura de acesso partilhado (SAS) ou de uma chave de conta. Para uma operação de cópia síncrona alterativa, consulte 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 via token SAS. O token SAS precisa incluir a permissão Read ('r'). Para saber mais sobre tokens SAS, consulte 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 anexado. O exemplo mostra como gerar o token SAS usando a biblioteca do cliente, mas você também pode fornecer o seu próprio. O exemplo também mostra como conceder o blob de origem durante a operação de cópia para evitar alterações no blob de um cliente diferente. A Copy Blob operação salva o ETag valor do blob de origem quando a operação de cópia é iniciada. Se o ETag valor 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();
}

Nota

Os tokens SAS de delegação de usuários oferecem maior segurança, pois são assinados com 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 chave de delegação de usuário.

Copiar um blob de uma fonte 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 uma determinada URL, 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 Copy Blob operação, você pode chamar UpdateStatusAsync e analisar a resposta para obter o valor para o x-ms-copy-status cabeçalho.

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

Abortar uma operação pendente 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, faça 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 seguintes operações:

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

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 cliente do Armazenamento de Blobs do Azure para .NET, consulte os recursos a seguir.

Amostras de código

Operações da API REST

O SDK do Azure para .NET contém bibliotecas que se baseiam na API REST do Azure, permitindo que você interaja com operações da API REST por meio de paradigmas .NET familiares. Os métodos de biblioteca de cliente abordados neste artigo usam as seguintes operações de API REST:

Recursos da biblioteca do cliente

Conteúdos relacionados

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