Guia de início rápido: biblioteca de cliente do Armazenamento de Blobs do Azure para .NET

  • Artigo

Nota

A opção Construir do zero orienta você passo a passo pelo processo de criação de um novo projeto, instalação de pacotes, escrita do código e execução de um aplicativo de console básico. Essa abordagem é recomendada se você quiser entender todos os detalhes envolvidos na criação de um aplicativo que se conecta ao Armazenamento de Blobs do Azure. Se preferir automatizar as tarefas de implantação e começar com um projeto concluído, escolha Iniciar com um modelo.

Nota

A opção Iniciar com um modelo usa a CLI do Desenvolvedor do Azure para automatizar tarefas de implantação e inicia você com um projeto concluído. Essa abordagem é recomendada se você quiser explorar o código o mais rápido possível sem passar pelas tarefas de configuração. Se preferir instruções passo a passo para criar o aplicativo, escolha Construir do zero.

Introdução à biblioteca de cliente do Armazenamento de Blobs do Azure para .NET. O Armazenamento de Blobs do Azure é a solução de armazenamento de objetos da Microsoft para a nuvem e é otimizado para armazenar grandes quantidades de dados não estruturados.

Neste artigo, siga as etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

Neste artigo, você usa a CLI do Desenvolvedor do Azure para implantar recursos do Azure e executar um aplicativo de console concluído com apenas alguns comandos.

Documentação | de referência da API Pacote de código-fonte | da biblioteca (NuGet)Exemplos |

Este vídeo mostra como começar a usar a biblioteca de cliente do Armazenamento de Blobs do Azure para .NET.

As etapas no vídeo também são descritas nas seções a seguir.

Pré-requisitos

Configuração

Esta seção orienta você na preparação de um projeto para trabalhar com a biblioteca de cliente do Armazenamento de Blobs do Azure para .NET.

Criar o projeto

Crie um aplicativo de console .NET usando a CLI do .NET ou o Visual Studio 2022.

  1. Na parte superior do Visual Studio, navegue até Arquivo>Novo>Projeto...

  2. Na janela de diálogo, insira o aplicativo de console na caixa de pesquisa de modelo de projeto e selecione o primeiro resultado. Escolha Avançar na parte inferior da caixa de diálogo.

    A screenshot showing how to create a new project using Visual Studio.

  3. Para o Nome do Projeto, digite BlobQuickstart. Deixe os valores padrão para o restante dos campos e selecione Avançar.

  4. Para o Framework, verifique se a versão instalada mais recente do .NET está selecionada. Em seguida, escolha Criar. O novo projeto é aberto dentro do ambiente do Visual Studio.

Instalar o pacote

Para interagir com o Armazenamento de Blobs do Azure, instale a biblioteca de cliente do Armazenamento de Blobs do Azure para .NET.

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no nó Dependências do seu projeto. Selecione Gerenciar pacotes NuGet.

  2. Na janela resultante, procure Azure.Storage.Blobs. Selecione o resultado apropriado e selecione Instalar.

    A screenshot showing how to add a new package using Visual Studio.

Configurar o código do aplicativo

Substitua o código inicial no Program.cs arquivo para que ele corresponda ao exemplo a seguir, que inclui as instruções necessárias using para este exercício.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Com a CLI do Desenvolvedor do Azure instalada, você pode criar uma conta de armazenamento e executar o código de exemplo com apenas alguns comandos. Você pode executar o projeto em seu ambiente de desenvolvimento local ou em um DevContainer.

Inicializar o modelo da CLI do Azure Developer e implantar recursos

Em um diretório vazio, siga estas etapas para inicializar o modelo, provisionar recursos do Azure e começar a usar o azd código:

  • Clone os ativos do repositório de início rápido do GitHub e inicialize o modelo localmente:

    azd init --template blob-storage-quickstart-dotnet

    Ser-lhe-ão solicitadas as seguintes informações:

    • Nome do ambiente: esse valor é usado como um prefixo para todos os recursos do Azure criados pela CLI do Desenvolvedor do Azure. O nome deve ser exclusivo em todas as assinaturas do Azure e deve ter entre 3 e 24 caracteres. O nome pode conter apenas letras minúsculas e números.

  • Faça logon no Azure:

    azd auth login

  • Provisione e implante os recursos no Azure:

    azd up

    Ser-lhe-ão solicitadas as seguintes informações:

    • Assinatura: a assinatura do Azure na qual seus recursos são implantados.
    • Local: a região do Azure onde seus recursos são implantados.

    A implantação pode levar alguns minutos para ser concluída. A saída do azd up comando inclui o nome da conta de armazenamento recém-criada, que você precisará mais tarde para executar o código.

Execute o código de exemplo

Neste ponto, os recursos são implantados no Azure e o projeto está pronto para ser executado. Siga estas etapas para atualizar o nome da conta de armazenamento no código e executar o aplicativo de console de exemplo:

  • Atualize o nome da conta de armazenamento: navegue até o src diretório e edite Program.cs. Localize o espaço reservado <storage-account-name> e substitua-o pelo nome real da conta de armazenamento criada pelo azd up comando. Guarde as alterações.
  • Executar o projeto: Se você estiver usando o Visual Studio, pressione F5 para criar e executar o código e interagir com o aplicativo de console. Se você estiver usando a CLI do .NET, navegue até o diretório do aplicativo, compile o projeto usando o e execute o aplicativo usando dotnet buildo dotnet run.
  • Observe a saída: Este aplicativo cria um arquivo de teste em sua pasta de dados local e o carrega em um contêiner na conta de armazenamento. O exemplo lista os blobs no contêiner e baixa o arquivo com um novo nome para que você possa comparar os arquivos antigos e novos.

Para saber mais sobre como o código de exemplo funciona, consulte Exemplos de código.

Quando terminar de testar o código, consulte a seção Limpar recursos para excluir os recursos criados pelo azd up comando.

Modelo de objeto

O Armazenamento de Blobs do Azure é otimizado para armazenar grandes quantidades de dados não estruturados. Os dados não estruturados não aderem a um modelo ou definição de dados específicos, como texto ou dados binários. O armazenamento de Blob oferece três tipos de recursos:

  • A conta de armazenamento
  • Um contêiner na conta de armazenamento
  • Uma bolha no recipiente

O diagrama seguinte mostra a relação entre estes recursos.

Diagram of Blob storage architecture.

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

  • BlobServiceClient: A BlobServiceClient classe permite manipular recursos de Armazenamento do Azure e contêineres de blob.
  • BlobContainerClient: A BlobContainerClient classe permite manipular contêineres de Armazenamento do Azure e seus blobs.
  • BlobClient: A BlobClient classe permite manipular blobs de Armazenamento do Azure.

Exemplos de código

Os trechos de código de exemplo nas seções a seguir demonstram como executar as seguintes tarefas com a biblioteca de cliente do Armazenamento de Blobs do Azure para .NET:

Importante

Certifique-se de ter instalado os pacotes NuGet corretos e adicionado as instruções using necessárias para que os exemplos de código funcionem, conforme descrito na seção de configuração .

Nota

O modelo da CLI do Desenvolvedor do Azure inclui um projeto com código de exemplo já instalado. Os exemplos a seguir fornecem detalhes para cada parte do código de exemplo. O modelo implementa o método de autenticação sem senha recomendado, conforme descrito na seção Autenticar no Azure . O método de cadeia de conexão é mostrado como uma alternativa, mas não é usado no modelo e não é recomendado para código de produção.

Autenticar no Azure e autorizar o acesso a dados de blob

As solicitações de aplicativo para o Armazenamento de Blobs do Azure devem ser autorizadas. Usar a classe fornecida pela biblioteca de cliente do Azure Identity é a DefaultAzureCredential abordagem recomendada para implementar conexões sem senha aos serviços do Azure em seu código, incluindo o Armazenamento de Blob.

Você também pode autorizar solicitações para o Armazenamento de Blobs do Azure usando a chave de acesso da conta. No entanto, esta abordagem deve ser utilizada com precaução. Os desenvolvedores devem ser diligentes para nunca expor a chave de acesso em um local não seguro. Qualquer pessoa que tenha a chave de acesso é capaz de autorizar solicitações contra a conta de armazenamento e efetivamente tem acesso a todos os dados. DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança sobre a chave da conta para permitir autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

DefaultAzureCredentialé uma classe fornecida pela biblioteca de cliente do Azure Identity para .NET, sobre a qual você pode saber mais na visão geral de DefaultAzureCredential. DefaultAzureCredential suporta vários métodos de autenticação e determina qual método deve ser usado em tempo de execução. Essa abordagem permite que seu aplicativo use métodos de autenticação diferentes em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

A ordem e os locais em que DefaultAzureCredential procura credenciais podem ser encontrados na visão geral da biblioteca de Identidades do Azure.

Por exemplo, seu aplicativo pode autenticar usando suas credenciais de entrada do Visual Studio com ao desenvolver localmente. Seu aplicativo pode usar uma identidade gerenciada depois de implantado no Azure. Não são necessárias alterações de código para esta transição.

Atribuir funções à sua conta de utilizador do Microsoft Entra

Ao desenvolver localmente, certifique-se de que a conta de usuário que está acessando dados de blob tem as permissões corretas. Você precisará do Storage Blob Data Contributor para ler e gravar dados de blob. Para atribuir essa função a si mesmo, você precisará receber a função de Administrador de Acesso de Usuário ou outra função que inclua a ação Microsoft.Authorization/roleAssignments/write. Você pode atribuir funções do RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Você pode saber mais sobre os escopos disponíveis para atribuições de função na página de visão geral do escopo.

Nesse cenário, você atribuirá permissões à sua conta de usuário, com escopo para a conta de armazenamento, para seguir o Princípio do Menor Privilégio. Essa prática oferece aos usuários apenas as permissões mínimas necessárias e cria ambientes de produção mais seguros.

O exemplo a seguir atribuirá a função de Colaborador de Dados de Blob de Armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados de blob em sua conta de armazenamento.

Importante

Na maioria dos casos, levará um ou dois minutos para que a atribuição de função se propague no Azure, mas, em casos raros, pode levar até oito minutos. Se você receber erros de autenticação quando executar o código pela primeira vez, aguarde alguns momentos e tente novamente.

  1. No portal do Azure, localize sua conta de armazenamento usando a barra de pesquisa principal ou a navegação à esquerda.

  2. Na página de visão geral da conta de armazenamento, selecione Controle de acesso (IAM) no menu à esquerda.

  3. Na página Controle de acesso (IAM), selecione a guia Atribuições de função.

  4. Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu suspenso resultante.

    A screenshot showing how to assign a role.

  5. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, procure por Storage Blob Data Contributor e selecione o resultado correspondente e, em seguida, escolha Next.

  6. Em Atribuir acesso a, selecione Utilizador, grupo ou entidade de serviço e, em seguida, selecione + Selecionar membros.

  7. Na caixa de diálogo, procure seu nome de usuário do Microsoft Entra (geralmente seu endereço de e-mail user@domain ) e escolha Selecionar na parte inferior da caixa de diálogo.

  8. Selecione Rever + atribuir para ir para a página final e, em seguida, Rever + atribuir novamente para concluir o processo.

Entre e conecte o código do seu aplicativo ao Azure usando DefaultAzureCredential

Você pode autorizar o acesso aos dados em sua conta de armazenamento usando as seguintes etapas:

  1. Para desenvolvimento local, certifique-se de que está autenticado com a mesma conta do Microsoft Entra à qual atribuiu a função. Você pode autenticar por meio de ferramentas de desenvolvimento populares, como a CLI do Azure ou o Azure PowerShell. As ferramentas de desenvolvimento com as quais você pode autenticar variam entre os idiomas.

    Entre no Azure por meio da CLI do Azure usando o seguinte comando:

    az login

  2. Para usar DefaultAzureCredentialo , adicione o pacote Azure.Identity ao seu aplicativo.

    1. No Gerenciador de Soluções, clique com o botão direito do mouse no nó Dependências do seu projeto. Selecione Gerenciar pacotes NuGet.

    2. Na janela resultante, procure Azure.Identity. Selecione o resultado apropriado e selecione Instalar.

      A screenshot showing how to add the identity package.

  3. Atualize o código Program.cs para corresponder ao exemplo a seguir. Quando o código é executado em sua estação de trabalho local durante o desenvolvimento, ele usará as credenciais de desenvolvedor da ferramenta priorizada na qual você está conectado para autenticar no Azure, como a CLI do Azure ou o Visual Studio.

    using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

  4. Certifique-se de atualizar o nome da conta de armazenamento no URI do .BlobServiceClient O nome da conta de armazenamento pode ser encontrado na página de visão geral do portal do Azure.

    A screenshot showing how to find the storage account name.

    Nota

    Quando implantado no Azure, esse mesmo código pode ser usado para autorizar solicitações ao Armazenamento do Azure a partir de um aplicativo em execução no Azure. No entanto, você precisará habilitar a identidade gerenciada em seu aplicativo no Azure. Em seguida, configure sua conta de armazenamento para permitir que essa identidade gerenciada se conecte. Para obter instruções detalhadas sobre como configurar essa conexão entre os serviços do Azure, consulte o tutorial Autenticação de aplicativos hospedados no Azure.

Criar um contentor

Crie um novo contêiner em sua conta de armazenamento chamando o método CreateBlobContainerAsync no blobServiceClient objeto. Neste exemplo, o código acrescenta um valor GUID ao nome do contêiner para garantir que ele seja exclusivo.

Adicione o seguinte código ao fim do ficheiro Program.cs:

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

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

Para saber mais sobre como criar um contêiner e explorar mais exemplos de código, consulte Criar um contêiner de blob com .NET.

Importante

Os nomes dos contentores têm de estar em minúscula. Para obter mais informações sobre a atribuição de nomes de contentores e blobs, veja Nomenclatura e Referenciação de Contentores, Blobs e Metadados.

Carregar um blob para um contentor

Carregue um blob para um contêiner usando UploadAsync. O código de exemplo cria um arquivo de texto no diretório de dados local para carregar no contêiner.

Adicione o seguinte código ao fim do ficheiro Program.cs:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
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, overwrite the blob if it already exists
await blobClient.UploadAsync(localFilePath, true);

Para saber mais sobre como carregar blobs e explorar mais exemplos de código, consulte Carregar um blob com .NET.

Listar blobs em um contêiner

Liste os blobs no contêiner chamando o método GetBlobsAsync .

Adicione o seguinte código ao fim do ficheiro Program.cs:

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

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

Para saber mais sobre como listar blobs e explorar mais exemplos de código, consulte Listar blobs com .NET.

Transferir um blob

Baixe o blob que criamos anteriormente chamando o método DownloadToAsync . O código de exemplo acrescenta a cadeia de caracteres "DOWNLOADED" ao nome do arquivo para que você possa ver ambos os arquivos no sistema de arquivos local.

Adicione o seguinte código ao fim do ficheiro Program.cs:

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

Para saber mais sobre como baixar blobs e explorar mais exemplos de código, consulte Baixar um blob com .NET.

Eliminar um contentor

O código a seguir limpa os recursos que o aplicativo criou excluindo o contêiner usando DeleteAsync. O exemplo de código também exclui os arquivos locais criados pelo aplicativo.

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

Adicione o seguinte código ao fim do ficheiro Program.cs:

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

Para saber mais sobre como excluir um contêiner e explorar mais exemplos de código, consulte Excluir e restaurar um contêiner de blob com o .NET.

O código preenchido

Depois de concluir essas etapas, o código em seu Program.cs arquivo agora deve ser semelhante ao seguinte:

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

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

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

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
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);

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

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

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

// 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 em sua pasta de dados local e o carrega para o armazenamento de Blob. O exemplo lista os blobs no contêiner e baixa o arquivo com um novo nome para que você possa comparar os arquivos antigos e novos.

Se você estiver usando o Visual Studio, pressione F5 para criar e executar o código e interagir com o aplicativo de console. Se você estiver usando a CLI do .NET, navegue até o diretório do aplicativo e, em seguida, compile e execute o aplicativo.

dotnet build

dotnet run

A saída do aplicativo é semelhante ao exemplo a seguir (valores GUID omitidos para legibilidade):

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobsGUID/quickstartGUID.txt

Listing blobs...
        quickstartGUID.txt

Downloading blob to
        ./data/quickstartGUIDDOWNLOADED.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 a pasta de dados para os dois arquivos. Você pode abri-los e observar que eles são idênticos.

Clean up resources (Limpar recursos)

Depois de verificar os arquivos e concluir o teste, pressione a tecla Enter para excluir os arquivos de teste junto com o contêiner criado na conta de armazenamento. Você também pode usar a CLI do Azure para excluir recursos.

Quando terminar o início rápido, você poderá limpar os recursos criados executando o seguinte comando:

azd down

Você será solicitado a confirmar a exclusão dos recursos. Entre y para confirmar.

Próximos passos

Neste início rápido, aprendeu a carregar, transferir e listar blobs com o .NET.

Para ver os aplicativos de exemplo de armazenamento de Blob, continue para:

Biblioteca de Armazenamento de Blobs do Azure para exemplos .NET