Início rápido: Biblioteca de clientes do Armazenamento de Blobs do Azure v12 para .NET

Introdução à biblioteca de clientes do Armazenamento de Blobs do Azure v12 para .NET. O Armazenamento de Blobs do Azure é uma solução de armazenamento de objetos da Microsoft para a nuvem. Siga as etapas para instalar o pacote e testar o código de exemplo para tarefas básicas. O Armazenamento de Blobs é otimizado para armazenar grandes quantidades de dados não estruturados.

Use a biblioteca de clientes do Armazenamento de Blobs do Azure v12 para .NET para:

  • Criar um contêiner
  • Carregar um blob para o Armazenamento do Azure
  • Listar todos os blobs em um contêiner
  • Baixar o blob em seu computador local
  • Excluir um contêiner

Recursos adicionais:

Observação

Os recursos descritos neste artigo também estão disponíveis para contas que têm um namespace hierárquico. Para ver as limitações, confira o artigo Recursos do Armazenamento de Blobs disponíveis no Azure Data Lake Storage Gen2.

Pré-requisitos

Configurando

Esta seção explica como preparar um projeto para funcionar com a biblioteca de clientes do Armazenamento de Blobs do Azure v12 para .NET.

Criar o projeto

Crie um aplicativo .NET Core chamado BlobQuickstartV12.

  1. Em uma janela do console (como cmd, PowerShell ou Bash), use o comando dotnet new para criar um novo aplicativo do console com o nome BlobQuickstartV12. Esse comando cria um projeto simples C# "Olá, Mundo" com um arquivo de origem único: Program.cs.

    dotnet new console -n BlobQuickstartV12
    
  2. Alterne para o diretório BlobQuickstartV12 recém-criado.

    cd BlobQuickstartV12
    
  3. No diretório BlobQuickstartV12, crie outro diretório chamado dados. É nele que os arquivos de dados de blob serão criados e armazenados.

    mkdir data
    

Instalar o pacote

Ainda no diretório do aplicativo, instale a biblioteca de clientes do Armazenamento de Blobs do Azure para .NET usando o comando dotnet add package.

dotnet add package Azure.Storage.Blobs

Configurar o framework de aplicativos

No diretório do projeto:

  1. Abra o arquivo Program.cs no seu editor.

  2. Remova a instrução Console.WriteLine("Hello World!");.

  3. Adicione as diretivas using.

  4. Atualize a declaração de método Main para dar suporte ao método assíncrono.

    O código é o seguinte:

    using Azure.Storage.Blobs;
    using Azure.Storage.Blobs.Models;
    using System;
    using System.IO;
    using System.Threading.Tasks;
    
    namespace BlobQuickstartV12
    {
        class Program
        {
            static async Task Main()
            {
            }
        }
    }
    

Copiar suas credenciais no Portal do Azure

Quando o aplicativo de exemplo faz uma solicitação para o Armazenamento do Azure, ele precisa ser autorizado. Para autenticar uma solicitação, adicione suas credenciais da conta de armazenamento ao aplicativo como uma cadeia de conexão. Exiba suas credenciais da conta de armazenamento seguindo estas etapas:

  1. Entre no portal do Azure.

  2. Localize sua cadeia de conexão.

  3. Na seção Segurança + rede da visão geral da conta de armazenamento, selecione Chaves de acesso. Aqui, você pode ver suas chaves de acesso da conta, bem como a cadeia de conexão completa para cada chave.

  4. Encontre o valor da Cadeia de conexão em key1 e selecione o botão Copiar para copiar a cadeia de conexão. Você adicionará o valor de cadeia de conexão para uma variável de ambiente na próxima etapa.

    Captura de tela mostrando como copiar uma cadeia de conexão do portal do Azure

Configurar a cadeia de conexão de armazenamento

Depois de copiar a cadeia de conexão, grave-a em uma nova variável de ambiente no computador local que executa o aplicativo. Para definir a variável de ambiente, abra uma janela de console e siga as instruções do seu sistema operacional. Substitua <yourconnectionstring> pela cadeia de conexão real.

Windows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Após adicionar a variável de ambiente no Windows, é necessário iniciar uma nova instância da janela de comando.

Linux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Reiniciar programas

Depois de adicionar a variável de ambiente, reinicie todos os programas em execução que precisarem ler a variável de ambiente. Por exemplo, reinicie o seu ambiente ou editor de desenvolvimento antes de continuar.

Modelo de objeto

O Armazenamento de Blobs do Azure é otimizado para armazenar grandes quantidades de dados não estruturados. Dados não estruturados são dados que não estão de acordo com uma definição ou um modelo de dados específico, como texto ou dados binários. O Armazenamento de Blobs oferece três tipos de recursos:

  • A conta de armazenamento
  • Um contêiner na conta de armazenamento
  • Um blob no contêiner

O diagrama a seguir mostra a relação entre esses recursos.

Diagrama da arquitetura de Armazenamento de Blobs

Use as seguintes classes .NET para interagir com esses recursos:

  • BlobServiceClient: a classe BlobServiceClient permite manipular os recursos do Armazenamento do Azure e os contêineres do blob.
  • BlobContainerClient: a classe BlobContainerClient permite manipular os contêineres do Armazenamento do Azure e seus blobs.
  • BlobClient: a classe BlobClient permite manipular os blobs do Armazenamento do Azure.
  • BlobDownloadInfo: a classe BlobDownloadInfo representa as propriedades e o conteúdo retornados do download de um blob.

Exemplos de código

Estes exemplos de snippets de código mostram como executar o seguinte com a biblioteca de clientes do Armazenamento de Blobs do Azure para .NET:

Obtenha a cadeia de conexão

O código a seguir recupera a cadeia de conexão da conta de armazenamento a partir da variável de ambiente criada na seção Configurar a cadeia de conexão do armazenamento.

Adicione esse código dentro do método Main:

Console.WriteLine("Azure Blob Storage v12 - .NET quickstart sample\n");

// Retrieve the connection string for use with the application. The storage
// connection string is stored in an environment variable on the machine
// running the application called AZURE_STORAGE_CONNECTION_STRING. If the
// environment variable is created after the application is launched in a
// console or with Visual Studio, the shell or application needs to be closed
// and reloaded to take the environment variable into account.
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

Criar um contêiner

Escolha um nome para o novo contêiner. O código abaixo anexa um valor GUID ao nome do contêiner para garantir que ele seja exclusivo.

Importante

Os nomes de contêiner devem estar em minúsculas. Para saber mais sobre como nomear contêineres e blobs, veja Nomenclatura e referência de contêineres, blobs e metadados.

Crie uma instância da classe BlobServiceClient. Em seguida, chame o método CreateBlobContainerAsync para criar o contêiner em sua conta de armazenamento.

Adicione este código ao final do método Main:

// Create a BlobServiceClient object which will be used to create a container client
BlobServiceClient blobServiceClient = new BlobServiceClient(connectionString);

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

Carregar blobs em um contêiner

O trecho de código a seguir:

  1. Cria um arquivo de texto no diretório de dados local.
  2. Obtém uma referência para um objeto BlobClient chamando o método GetBlobClient no contêiner da seção Criar um contêiner.
  3. Carrega o arquivo de texto local para o blob chamando o método UploadAsync. Esse método criará o blob se ele ainda não existir e o substituirá se já existir.

Adicione este código ao final do método Main:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "./data/";
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Listar os blobs em um contêiner

Liste os blobs no contêiner chamando o método GetBlobsAsync. Nesse caso, apenas um blob foi adicionado ao contêiner, portanto, a operação de listagem retorna apenas esse blob.

Adicione este código ao final do método Main:

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

Baixar blobs

Baixe o blob criado anteriormente chamando o método DownloadAsync. O código de exemplo adiciona um sufixo "DOWNLOADED" ao nome do arquivo para que você possa ver os dois arquivos no sistema de arquivos local.

Adicione este código ao final do método Main:

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

Excluir um contêiner

O código a seguir limpa os recursos que o aplicativo criou ao excluir todo o contêiner usando DeleteAsync. Ele também exclui os arquivos locais criados pelo aplicativo.

O aplicativo pausa a entrada do usuário chamando Console.ReadLine antes de excluir o blob, o contêiner e os arquivos locais. Essa é uma boa chance de verificar se os recursos foram realmente criados corretamente antes de serem excluídos.

Adicione este código ao final do método Main:

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Executar o código

Este aplicativo cria um arquivo de teste na pasta dados local e o carrega no Armazenamento de Blobs. Em seguida, o exemplo lista os blobs no contêiner e baixa o arquivo com um novo nome para que você possa comparar os arquivos novos e antigos.

Navegue até seu diretório de aplicativo e, em seguida, crie e execute o aplicativo.

dotnet build
dotnet run

A saída do aplicativo é semelhante ao seguinte exemplo:

Azure Blob Storage v12 - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobs60c70d78-8d93-43ae-954d-8322058cfd64/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Listing blobs...
        quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Downloading blob to
        ./data/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31DOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

Antes de iniciar o processo de limpeza, verifique se os dois arquivos estão na pasta dados. Você pode abri-los e ver se eles são idênticos.

Depois de verificar os arquivos, pressione a tecla Enter para excluir os arquivos de teste e concluir a demonstração.

Próximas etapas

Neste início rápido você aprendeu a carregar, baixar e listar blobs usando .NET.

Para ver os aplicativos de exemplo de armazenamento de blobs, acesse: