Início Rápido: Armazenamento de Blobs do Azure biblioteca de cliente para .NET

Introdução à biblioteca de cliente Armazenamento de Blobs do Azure para .NET. Armazenamento de Blobs do Azure é a solução de armazenamento de objetos da Microsoft para a cloud. Siga estes passos para instalar o pacote e experimente código de exemplo para tarefas básicas. O armazenamento de blobs está otimizado para armazenar quantidades em grande escala de dados não estruturados.

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

Pré-requisitos

Configurar

Esta secção orienta-o ao longo da preparação de um projeto para trabalhar com a biblioteca de cliente Armazenamento de Blobs do Azure para .NET.

Criar o projeto

Para obter os passos seguintes, terá de criar uma aplicação de consola .NET com a CLI do .NET ou o Visual Studio 2022.

  1. Na parte superior do Visual Studio, navegue para Ficheiro>Novo>Projeto...

  2. Na janela de diálogo, introduza a aplicação de consola na caixa de pesquisa do modelo de projeto e selecione o primeiro resultado. Selecione Seguinte na parte inferior da caixa de diálogo.

    Uma captura de ecrã a mostrar como criar um novo projeto com o Visual Studio.

  3. Para o Nome do Projeto, introduza BlobQuickstart. Deixe os valores predefinidos para os restantes campos e selecione Seguinte.

  4. Para o Framework, certifique-se de que o .NET 6.0 está selecionado. Em seguida, escolha Criar. O novo projeto será aberto dentro do ambiente do Visual Studio.

Instalar o pacote

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

  1. No Explorador de Soluções, clique com o botão direito do rato no nó Dependências do projeto. Selecione Gerir Pacotes NuGet.

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

    Uma captura de ecrã a mostrar como adicionar um novo pacote com o Visual Studio.

Configurar o código da aplicação

Substitua o código inicial no Program.cs ficheiro para que corresponda ao seguinte exemplo, 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!");

Autenticar no Azure e autorizar o acesso aos dados de blobs

Os pedidos de aplicação para Armazenamento de Blobs do Azure têm de ser autorizados. Utilizar a DefaultAzureCredential classe fornecida pela biblioteca de cliente da Identidade do Azure é a abordagem recomendada para implementar ligações sem palavra-passe aos serviços do Azure no seu código, incluindo o Armazenamento de Blobs.

Também pode autorizar pedidos para Armazenamento de Blobs do Azure com a chave de acesso da conta. No entanto, esta abordagem deve ser utilizada com cuidado. Os programadores têm de ser diligentes para nunca exporem a chave de acesso numa localização não seguras. Qualquer pessoa que tenha a chave de acesso pode autorizar pedidos contra a conta de armazenamento e, efetivamente, tem acesso a todos os dados. DefaultAzureCredential oferece benefícios de segurança e gestão melhorados sobre a chave de conta para permitir a autenticação sem palavra-passe. Ambas as opções são demonstradas no exemplo seguinte.

DefaultAzureCredential é uma classe fornecida pela biblioteca de cliente da Identidade do Azure para .NET, sobre a qual pode saber mais na descrição geral DefaultAzureCredential. DefaultAzureCredential suporta vários métodos de autenticação e determina que método deve ser utilizado no runtime. Esta abordagem permite que a sua aplicação utilize diferentes métodos de autenticação em diferentes ambientes (local vs. produção) sem implementar código específico do ambiente.

A ordem e as localizações em que DefaultAzureCredential procura credenciais podem ser encontradas na descrição geral da biblioteca de Identidades do Azure.

Por exemplo, a sua aplicação pode autenticar com as suas credenciais de início de sessão do Visual Studio ao programar localmente. Em seguida, a sua aplicação pode utilizar uma identidade gerida depois de ter sido implementada no Azure. Não são necessárias alterações de código para esta transição.

Atribuir funções à sua conta de utilizador Azure AD

Ao programar localmente, certifique-se de que a conta de utilizador que está a aceder aos dados de blobs tem as permissões corretas. Precisará do Contribuidor de Dados do Blob de Armazenamento para ler e escrever dados de blobs. Para se atribuir a si próprio esta função, terá de lhe ser atribuída a função Administrador de Acesso de Utilizador ou outra função que inclua a ação Microsoft.Authorization/roleAssignments/write . Pode atribuir funções RBAC do Azure a um utilizador com o portal do Azure, a CLI do Azure ou Azure PowerShell. Pode saber mais sobre os âmbitos disponíveis para atribuições de funções na página de descrição geral do âmbito .

Neste cenário, irá atribuir permissões à sua conta de utilizador, no âmbito da conta de armazenamento, para seguir o Princípio do Menor Privilégio. Esta prática dá aos utilizadores apenas as permissões mínimas necessárias e cria ambientes de produção mais seguros.

O exemplo seguinte irá atribuir a função Contribuidor de Dados do Blob de Armazenamento à sua conta de utilizador, que fornece acesso de leitura e escrita aos dados de blobs na sua conta de armazenamento.

Importante

Na maioria dos casos, a propagação da atribuição de funções no Azure demorará um minuto ou dois, mas em casos raros poderá demorar até oito minutos. Se receber erros de autenticação quando executar o código pela primeira vez, aguarde alguns momentos e tente novamente.

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

  2. Na página de descrição geral da conta de armazenamento, selecione Controlo de acesso (IAM) no menu esquerdo.

  3. Na página Controlo de acesso (IAM), selecione o separador Atribuições de funções .

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

    Uma captura de ecrã a mostrar como atribuir uma função.

  5. Utilize a caixa de pesquisa para filtrar os resultados para a função pretendida. Neste exemplo, procure Contribuidor de Dados do Blob de Armazenamento , selecione o resultado correspondente e, em seguida, selecione Seguinte.

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

  7. Na caixa de diálogo, procure o seu Azure AD nome de utilizador (normalmente o seu endereço de e-mail user@domain) e, em seguida, selecione 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.

Iniciar sessão e ligar o código da aplicação ao Azure com DefaultAzureCredential

Pode autorizar o acesso aos dados na sua conta de armazenamento através dos seguintes passos:

  1. Certifique-se de que está autenticado com a mesma conta Azure AD à qual atribuiu a função. Pode autenticar através da CLI do Azure, do Visual Studio ou Azure PowerShell.

    Inicie sessão no Azure através da CLI do Azure com o seguinte comando:

    az login
    
  2. Para utilizar DefaultAzureCredentialo , adicione o pacote Azure.Identity à sua aplicação.

    1. No Explorador de Soluções, clique com o botão direito do rato no nó Dependências do projeto. Selecione Gerir Pacotes NuGet.

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

      Uma captura de ecrã a mostrar como adicionar o pacote de identidade.

  3. Atualize o código Program.cs para corresponder ao seguinte exemplo. Quando o código é executado na estação de trabalho local durante o desenvolvimento, utilizará as credenciais de programador da ferramenta priorizada na qual tem sessão iniciada 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 que atualiza o nome da conta de armazenamento no URI do .BlobServiceClient O nome da conta de armazenamento pode ser encontrado na página de descrição geral do portal do Azure.

    Uma captura de ecrã a mostrar como localizar o nome da conta de armazenamento.

    Nota

    Quando implementado no Azure, este mesmo código pode ser utilizado para autorizar pedidos para o Armazenamento do Azure a partir de uma aplicação em execução no Azure. No entanto, terá de ativar a identidade gerida na sua aplicação no Azure. Em seguida, configure a sua conta de armazenamento para permitir que essa identidade gerida se ligue. Para obter instruções detalhadas sobre como configurar esta ligação entre os serviços do Azure, veja o tutorial Autenticação de aplicações alojadas no Azure .

Modelo de objeto

Armazenamento de Blobs do Azure está otimizado para armazenar grandes quantidades de dados não estruturados. Os dados não estruturados não cumprem um determinado modelo ou definição de dados, como texto ou dados binários. O armazenamento de blobs oferece três tipos de recursos:

  • A conta de armazenamento
  • Um contentor na conta de armazenamento
  • Um blob no contentor

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

Diagrama da arquitetura de armazenamento de Blobs.

Utilize as seguintes classes .NET para interagir com estes recursos:

  • BlobServiceClient: a BlobServiceClient classe permite-lhe manipular recursos do Armazenamento do Azure e contentores de blobs.
  • BlobContainerClient: a BlobContainerClient classe permite-lhe manipular contentores do Armazenamento do Azure e os respetivos blobs.
  • BlobClient: a BlobClient classe permite-lhe manipular blobs de Armazenamento do Azure.

Exemplos de código

Os fragmentos de código de exemplo nas secções seguintes demonstram como realizar operações de dados básicas com a biblioteca de cliente Armazenamento de Blobs do Azure para .NET.

Importante

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

  • Azure.Identity (se estiver a utilizar a abordagem sem palavra-passe)
  • Azure.Storage.Blobs

Criar um contentor

Decida um nome para o novo contentor. O código abaixo acrescenta um valor GUID ao nome do contentor para garantir que é exclusivo.

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.

Pode chamar o método CreateBlobContainerAsync no blobServiceClient para criar um contentor na sua conta de armazenamento.

Adicione este código ao final da Program.cs classe:

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

Carregar um blob para um contentor

Adicione o seguinte código ao final da Program.cs classe:

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

O fragmento de código conclui os seguintes passos:

  1. Cria um ficheiro de texto no diretório de dados local.
  2. Obtém uma referência a um objeto BlobClient ao chamar o método GetBlobClient no contentor a partir da secção Criar um contentor .
  3. Carrega o ficheiro de texto local para o blob ao chamar o método UploadAsync . Este método cria o blob, caso ainda não exista, ou substitui-o se o mesmo já existir.

Listar blobs num contentor

Liste os blobs no contentor ao chamar o método GetBlobsAsync . Neste caso, apenas um blob foi adicionado ao contentor, pelo que a operação de listagem devolve apenas esse blob.

Adicione o seguinte código ao final da Program.cs classe:

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

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

Transferir um blob

Transfira o blob criado anteriormente ao chamar o método DownloadToAsync . O código de exemplo adiciona um sufixo de "TRANSFERIDO" ao nome do ficheiro para que possa ver ambos os ficheiros no sistema de ficheiros local.

Adicione o seguinte código ao final da Program.cs classe:

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

Eliminar um contentor

O código seguinte limpa os recursos que a aplicação criou ao eliminar todo o contentor com DeleteAsync. Também elimina os ficheiros locais criados pela aplicação.

A aplicação coloca em pausa a entrada do utilizador ao chamar Console.ReadLine antes de eliminar o blob, o contentor e os ficheiros locais. Esta é uma boa oportunidade para verificar se os recursos foram realmente criados corretamente, antes de serem eliminados.

Adicione o seguinte código ao final da Program.cs classe:

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

O código concluído

Depois de concluir estes passos, o código no seu Program.cs ficheiro deve agora assemelhar-se 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

Esta aplicação cria um ficheiro de teste na pasta de dados local e carrega-o para o Armazenamento de blobs. Em seguida, o exemplo lista os blobs no contentor e transfere o ficheiro com um novo nome para que possa comparar os ficheiros antigos e novos.

Se estiver a utilizar o Visual Studio, prima F5 para criar e executar o código e interagir com a aplicação de consola. Se estiver a utilizar a CLI .NET, navegue para o diretório da aplicação e, em seguida, crie e execute a aplicação.

dotnet build
dotnet run

O resultado da aplicação é semelhante ao seguinte exemplo:

Azure Blob Storage - .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 a pasta de dados dos dois ficheiros. Pode abri-los e constatar que são idênticos.

Depois de verificar os ficheiros, prima a tecla Enter para eliminar os ficheiros de teste e concluir a demonstração.

Passos seguintes

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

Para ver as aplicações de exemplo do Armazenamento de blobs, continue para: