Transferir um blob com .NET

  • Artigo

Este artigo mostra como transferir um blob com a biblioteca de cliente do Armazenamento do Azure para .NET. Pode transferir dados de blobs para vários destinos, incluindo um caminho de ficheiro local, fluxo ou cadeia de texto. Também pode abrir um fluxo de blobs e ler a partir do mesmo.

Pré-requisitos

  • Este artigo pressupõe que já tem um projeto configurado para funcionar com a biblioteca de cliente Armazenamento de Blobs do Azure para .NET. Para saber mais sobre a configuração do projeto, incluindo a instalação de pacotes, a adição using de diretivas e a criação de um objeto de cliente autorizado, consulte Introdução ao Armazenamento de Blobs do Azure e .NET.
  • O mecanismo de autorização tem de ter permissões para efetuar uma operação de transferência. Para saber mais, veja a documentação de orientação de autorização para a seguinte operação da API REST:

Transferir um blob

Pode utilizar qualquer um dos seguintes métodos para transferir um blob:

Também pode abrir um fluxo para ler a partir de um blob. O fluxo só transfere o blob à medida que o fluxo é lido. Pode utilizar um dos seguintes procedimentos:

Transferir para um caminho de ficheiro

O exemplo seguinte transfere um blob para um caminho de ficheiro local. Se o diretório especificado não existir, o código lança um DirectoryNotFoundException. Se o ficheiro já existir em localFilePath, é substituído por predefinição durante as transferências subsequentes.

public static async Task DownloadBlobToFileAsync(
    BlobClient blobClient,
    string localFilePath)
{
    await blobClient.DownloadToAsync(localFilePath);
}

Transferir para um fluxo

O exemplo seguinte transfere um blob ao criar um objeto do Stream e, em seguida, transfere-o para esse fluxo. Se o diretório especificado não existir, o código lança um DirectoryNotFoundException.

public static async Task DownloadBlobToStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

Transferir para uma cadeia

O exemplo seguinte pressupõe que o blob é um ficheiro de texto e transfere o blob para uma cadeia:

public static async Task DownloadBlobToStringAsync(BlobClient blobClient)
{
    BlobDownloadResult downloadResult = await blobClient.DownloadContentAsync();
    string blobContents = downloadResult.Content.ToString();
}

Transferir a partir de um fluxo

O exemplo seguinte transfere um blob ao ler a partir de um fluxo:

public static async Task DownloadBlobFromStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    using (var stream = await blobClient.OpenReadAsync())
    {
        FileStream fileStream = File.OpenWrite(localFilePath);
        await stream.CopyToAsync(fileStream);
    }
}

Transferir um blob de blocos com opções de configuração

Pode definir opções de configuração da biblioteca de cliente ao transferir um blob. Estas opções podem ser otimizadas para melhorar o desempenho e melhorar a fiabilidade. Os exemplos de código seguintes mostram como utilizar BlobDownloadToOptions para definir opções de configuração ao chamar um método de transferência. Tenha em atenção que estão disponíveis as mesmas opções para BlobDownloadOptions.

Especificar opções de transferência de dados ao transferir

Pode configurar os valores em StorageTransferOptions para melhorar o desempenho das operações de transferência de dados. O seguinte exemplo de código mostra como definir valores para StorageTransferOptions e incluir as opções como parte de uma BlobDownloadToOptions instância. Os valores fornecidos neste exemplo não se destinam a ser uma recomendação. Para ajustar corretamente estes valores, tem de considerar as necessidades específicas da sua aplicação.

public static async Task DownloadBlobWithTransferOptionsAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var transferOptions = new StorageTransferOptions
    {
        // Set the maximum number of parallel transfer workers
        MaximumConcurrency = 2,

        // Set the initial transfer length to 8 MiB
        InitialTransferSize = 8 * 1024 * 1024,

        // Set the maximum length of a transfer to 4 MiB
        MaximumTransferSize = 4 * 1024 * 1024
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferOptions = transferOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

Para saber mais sobre como otimizar as opções de transferência de dados, veja Otimização do desempenho para carregamentos e transferências.

Especificar opções de validação de transferência ao transferir

Pode especificar opções de validação de transferência para ajudar a garantir que os dados são transferidos corretamente e não foram adulterados durante o trânsito. As opções de validação de transferência podem ser definidas ao nível do cliente com BlobClientOptions, que aplica opções de validação a todos os métodos chamados a partir de uma instância blobClient .

Também pode substituir as opções de validação de transferência ao nível do método com BlobDownloadToOptions. O seguinte exemplo de código mostra como criar um BlobDownloadToOptions objeto e especificar um algoritmo para gerar uma soma de verificação. A soma de verificação é então utilizada pelo serviço para verificar a integridade dos dados dos conteúdos transferidos.

public static async Task DownloadBlobWithChecksumAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var validationOptions = new DownloadTransferValidationOptions
    {
        AutoValidateChecksum = true,
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferValidation = validationOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

A tabela seguinte mostra as opções disponíveis para o algoritmo de soma de verificação, conforme definido por StorageChecksumAlgorithm:

Name Valor Descrição
Automático 0 Recomendado. Permite que a biblioteca escolha um algoritmo. Diferentes versões de biblioteca podem escolher algoritmos diferentes.
Nenhuma 1 Nenhum algoritmo selecionado. Não calcule nem solicite somas de verificação.
MD5 2 Algoritmo hash MD5 padrão.
StorageCrc64 3 CRC personalizado do Armazenamento do Azure de 64 bits.

Recursos

Para saber mais sobre como transferir blobs com a biblioteca de cliente Armazenamento de Blobs do Azure para .NET, veja os seguintes recursos.

Operações da API REST

O SDK do Azure para .NET contém bibliotecas que se baseiam na API REST do Azure, o que lhe permite interagir com operações da API REST através de paradigmas de .NET familiares. Os métodos da biblioteca de cliente para transferir blobs utilizam a seguinte operação da API REST:

Exemplos de código

Recursos da biblioteca de cliente

Ver também