Quickstart: Biblioteca de clientes de armazenamento Azure Blob v12 para .NETQuickstart: Azure Blob storage client library v12 for .NET

Inicie-se com a biblioteca de clientes de armazenamento Azure Blob v12 para .NET.Get started with the Azure Blob storage client library v12 for .NET. O Armazenamento de Blobs do Azure é a solução de armazenamento de objetos da Microsoft para a cloud.Azure Blob storage is Microsoft's object storage solution for the cloud. Siga os passos para instalar a embalagem e experimente o código de exemplo para tarefas básicas.Follow steps to install the package and try out example code for basic tasks. O Armazenamento de blobs está otimizado para armazenar quantidades em grande escala de dados não estruturados.Blob storage is optimized for storing massive amounts of unstructured data.

Nota

Para começar com a versão Anterior do SDK, consulte Quickstart: Azure Blob storage client library for .NET.To get started with the previous SDK version, see Quickstart: Azure Blob storage client library for .NET.

Utilize a biblioteca de clientes de armazenamento Azure Blob v12 para.NET para:Use the Azure Blob storage client library v12 for .NET to:

  • Criar um contentorCreate a container
  • Faça upload de uma bolha para o Armazenamento AzureUpload a blob to Azure Storage
  • Liste todas as bolhas num recipienteList all of the blobs in a container
  • Descarregue a bolha para o seu computador localDownload the blob to your local computer
  • Eliminar um contentorDelete a container

Documentação de | referência APIBiblioteca Código fonte | Pacote (NuGet) | AmostrasAPI reference documentation | Library source code | Package (NuGet) | Samples

Nota

As características descritas neste artigo estão agora disponíveis para contas que têm um espaço de nome hierárquico.The features described in this article are now available to accounts that have a hierarchical namespace. Para rever as limitações, consulte as questões conhecidas com o artigo da Azure Data Lake Storage Gen2.To review limitations, see the Known issues with Azure Data Lake Storage Gen2 article.

Pré-requisitosPrerequisites

ConfiguraçãoSetting up

Esta secção acompanha-o através da preparação de um projeto para trabalhar com a biblioteca de clientes de armazenamento Azure Blob v12 para .NET.This section walks you through preparing a project to work with the Azure Blob storage client library v12 for .NET.

Criar o projetoCreate the project

Crie uma aplicação .NET Core chamada BlobQuickstartV12.Create a .NET Core application named BlobQuickstartV12.

  1. Numa janela de consola (como cmd, PowerShell dotnet new ou Bash), utilize o comando para criar uma nova aplicação de consola com o nome BlobQuickstartV12.In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name BlobQuickstartV12. Este comando cria um simples projeto C# "Hello World" com um único ficheiro fonte: Program.cs.This command creates a simple "Hello World" C# project with a single source file: Program.cs.

    dotnet new console -n BlobQuickstartV12
    
  2. Mude para o recém-criado diretório BlobQuickstartV12.Switch to the newly created BlobQuickstartV12 directory.

    cd BlobQuickstartV12
    
  3. Ao lado do diretório BlobQuickstartV12, crie outro diretório chamado data.In side the BlobQuickstartV12 directory, create another directory called data. É aqui que os ficheiros de dados blob serão criados e armazenados.This is where the blob data files will be created and stored.

    mkdir data
    

Instale o pacoteInstall the package

Ainda no diretório de aplicações, instale a biblioteca de clientes dotnet add package de armazenamento Azure Blob para o pacote .NET utilizando o comando.While still in the application directory, install the Azure Blob storage client library for .NET package by using the dotnet add package command.

dotnet add package Azure.Storage.Blobs

Configurar o quadro da aplicaçãoSet up the app framework

Do diretório do projeto:From the project directory:

  1. Abra o ficheiro Program.cs no seu editorOpen the Program.cs file in your editor
  2. Remova Console.WriteLine("Hello World!"); a declaraçãoRemove the Console.WriteLine("Hello World!"); statement
  3. Adicionar using diretivasAdd using directives
  4. Atualizar Main a declaração de método para apoiar o código assyncUpdate the Main method declaration to support async code

Aqui está o código:Here's the code:

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 as credenciais do Portal do AzureCopy your credentials from the Azure portal

Quando o pedido de amostrafaz um pedido ao Armazenamento Azure, deve ser autorizado.When the sample application makes a request to Azure Storage, it must be authorized. Para autorizar um pedido, adicione as credenciais da sua conta de armazenamento ao pedido como uma cadeia de ligação.To authorize a request, add your storage account credentials to the application as a connection string. Veja as credenciais da conta de armazenamento através dos seguintes passos:View your storage account credentials by following these steps:

  1. Inicie sessão no Portal do Azure.Sign in to the Azure portal.

  2. Localize a sua conta de armazenamento.Locate your storage account.

  3. Na secção Definições da descrição geral da conta de armazenamento, selecione Chaves de acesso.In the Settings section of the storage account overview, select Access keys. Aqui, pode ver as chaves de acesso da conta e a cadeia de ligação completa para cada chave.Here, you can view your account access keys and the complete connection string for each key.

  4. Encontre o valor da Cadeia de ligação em key1 e selecione o botão Copiar para copiar a cadeia de ligação.Find the Connection string value under key1, and select the Copy button to copy the connection string. Irá adicionar o valor da cadeia de ligação para uma variável de ambiente no próximo passo.You will add the connection string value to an environment variable in the next step.

    Captura de ecrã que mostra como copiar uma cadeia de ligação do portal do Azure

Configurar a cadeia de ligação de armazenamentoConfigure your storage connection string

Após ter copiado a cadeia de ligação, escreva-a numa nova variável de ambiente no computador local que está a executar a aplicação.After you have copied your connection string, write it to a new environment variable on the local machine running the application. Para definir a variável de ambiente, abra uma janela da consola e siga as instruções relevantes para o seu sistema operativo.To set the environment variable, open a console window, and follow the instructions for your operating system. Substitua-a <yourconnectionstring> com a sua corda de ligação real.Replace <yourconnectionstring> with your actual connection string.

WindowsWindows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Depois de adicionar a variável ambiental no Windows, deve iniciar uma nova instância da janela de comando.After you add the environment variable in Windows, you must start a new instance of the command window.

LinuxLinux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOSmacOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Reiniciar programasRestart programs

Depois de adicionar a variável ambiental, reinicie todos os programas de execução que precisem de ler a variável ambiental.After you add the environment variable, restart any running programs that will need to read the environment variable. Por exemplo, reinicie o seu ambiente de desenvolvimento ou editor antes de continuar.For example, restart your development environment or editor before continuing.

Modelo de objetoObject model

O armazenamento da Blob Azure está otimizado para armazenar quantidades massivas de dados não estruturados.Azure Blob storage is optimized for storing massive amounts of unstructured data. Os dados não estruturados são dados que não seguem uma definição ou um modelo de dados em particular, como por exemplo, texto ou dados binários.Unstructured data is data that does not adhere to a particular data model or definition, such as text or binary data. O armazenamento blob oferece três tipos de recursos:Blob storage offers three types of resources:

  • A conta de armazenamentoThe storage account
  • Um recipiente na conta de armazenamentoA container in the storage account
  • Uma bolha no recipienteA blob in the container

O diagrama seguinte mostra a relação entre estes recursos.The following diagram shows the relationship between these resources.

Diagrama da arquitetura de armazenamento blob

Utilize as seguintes classes .NET para interagir com estes recursos:Use the following .NET classes to interact with these resources:

  • BlobServiceClient: BlobServiceClient A classe permite-lhe manipular os recursos de Armazenamento Azure e os recipientes blob.BlobServiceClient: The BlobServiceClient class allows you to manipulate Azure Storage resources and blob containers.
  • BlobContainerClient: BlobContainerClient A classe permite-lhe manipular os recipientes de armazenamento Azure e as suas bolhas.BlobContainerClient: The BlobContainerClient class allows you to manipulate Azure Storage containers and their blobs.
  • BlobClient: BlobClient A classe permite-lhe manipular bolhas de Armazenamento Azure.BlobClient: The BlobClient class allows you to manipulate Azure Storage blobs.
  • BlobDownloadInfo: BlobDownloadInfo A classe representa as propriedades e conteúdos devolvidos ao descarregar uma bolha.BlobDownloadInfo: The BlobDownloadInfo class represents the properties and content returned from downloading a blob.

Exemplos de códigoCode examples

Estes snippets de código de exemplo mostram-lhe como executar o seguinte com a biblioteca de clientes de armazenamento Azure Blob para .NET:These example code snippets show you how to perform the following with the Azure Blob storage client library for .NET:

Obter a cadeia de ligaçãoGet the connection string

O código abaixo recupera a cadeia de ligação para a conta de armazenamento a partir da variável ambiental criada na secção de cadeias de ligação de armazenamento Configure.The code below retrieves the connection string for the storage account from the environment variable created in the Configure your storage connection string section.

Adicione este código Main dentro do método:Add this code inside the Main method:

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 contentorCreate a container

Decida um nome para o novo contentor.Decide on a name for the new container. O código abaixo anexa um valor GUID para o nome do recipiente para garantir que é único.The code below appends a GUID value to the container name to ensure that it is unique.

Importante

Os nomes dos contentores têm de estar em minúscula.Container names must be lowercase. 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.For more information about naming containers and blobs, see Naming and Referencing Containers, Blobs, and Metadata.

Crie uma instância da classe BlobServiceClient.Create an instance of the BlobServiceClient class. Em seguida, ligue para o método CreateBlobContainerAsync para criar o recipiente na sua conta de armazenamento.Then, call the CreateBlobContainerAsync method to create the container in your storage account.

Adicione este código ao Main fim do método:Add this code to the end of the Main method:

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

Faça upload de bolhas para um recipienteUpload blobs to a container

O seguinte código snippet:The following code snippet:

  1. Cria um ficheiro de texto no diretório de dados local.Creates a text file in the local data directory.
  2. Obtém uma referência a um objeto BlobClient, ligando para o método GetBlobClient no recipiente a partir da secção Criar um recipiente.Gets a reference to a BlobClient object by calling the GetBlobClient method on the container from the Create a container section.
  3. Envia o ficheiro de texto local para a bolha, ligando para o método UploadAsync.Uploads the local text file to the blob by calling the UploadAsync method. Este método cria o blob, caso ainda não exista, ou substitui-o se o mesmo já existir.This method creates the blob if it doesn't already exist, and overwrites it if it does.

Adicione este código ao Main fim do método:Add this code to the end of the Main method:

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

// Open the file and upload its data
using FileStream uploadFileStream = File.OpenRead(localFilePath);
await blobClient.UploadAsync(uploadFileStream, true);
uploadFileStream.Close();

Listar os blobs num contentorList the blobs in a container

Enumera as bolhas no recipiente, chamando o método GetBlobsAsync.List the blobs in the container by calling the GetBlobsAsync method. Neste caso, apenas uma bolha foi adicionada ao recipiente, pelo que a operação de listagem devolve apenas uma bolha.In this case, only one blob has been added to the container, so the listing operation returns just that one blob.

Adicione este código ao Main fim do método:Add this code to the end of the Main method:

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

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

Transferir blobsDownload blobs

Descarregue a bolha anteriormente criada, ligando para o método DownloadAsync.Download the previously created blob by calling the DownloadAsync method. O código de exemplo adiciona um sufixo de "DOWNLOAD" ao nome do ficheiro para que possa ver ambos os ficheiros no sistema de ficheiros local.The example code adds a suffix of "DOWNLOADED" to the file name so that you can see both files in local file system.

Adicione este código ao Main fim do método:Add this code to the end of the Main method:

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

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

// Download the blob's contents and save it to a file
BlobDownloadInfo download = await blobClient.DownloadAsync();

using (FileStream downloadFileStream = File.OpenWrite(downloadFilePath))
{
    await download.Content.CopyToAsync(downloadFileStream);
    downloadFileStream.Close();
}

Eliminar um contentorDelete a container

O código que se segue limpa os recursos que a app criou eliminando todo o recipiente utilizando o DeleteAsync.The following code cleans up the resources the app created by deleting the entire container by using DeleteAsync. Também elimina os ficheiros locais criados pela aplicação.It also deletes the local files created by the app.

A aplicação faz uma pausa Console.ReadLine para a entrada do utilizador, ligando antes de eliminar a bolha, o contentor e os ficheiros locais.The app pauses for user input by calling Console.ReadLine before it deletes the blob, container, and local files. Esta é uma boa oportunidade para verificar se os recursos foram efetivamente criados corretamente, antes de serem eliminados.This is a good chance to verify that the resources were actually created correctly, before they are deleted.

Adicione este código ao Main fim do método:Add this code to the end of the Main method:

// 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ódigoRun the code

Esta aplicação cria um ficheiro de teste na sua pasta de dados local e envia-o para o armazenamento blob.This app creates a test file in your local data folder and uploads it to Blob storage. O exemplo lista as bolhas no recipiente e descarrega o ficheiro com um novo nome para que possa comparar os ficheiros antigos e novos.The example then lists the blobs in the container and downloads the file with a new name so that you can compare the old and new files.

Navegue para o seu diretório de candidaturas, em seguida, construa e execute a aplicação.Navigate to your application directory, then build and run the application.

dotnet build
dotnet run

A saída da aplicação é semelhante ao seguinte exemplo:The output of the app is similar to the following example:

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 a pasta de dados dos dois ficheiros.Before you begin the clean up process, check your data folder for the two files. Pode abri-los e constatar que são idênticos.You can open them and observe that they are identical.

Depois de verificar os ficheiros, prima a tecla Enter para eliminar os ficheiros de teste e terminar a demonstração.After you've verified the files, press the Enter key to delete the test files and finish the demo.

Passos seguintesNext steps

Neste início rápido, aprendeu a carregar, transferir e listar blobs com o .NET.In this quickstart, you learned how to upload, download, and list blobs using .NET.

Para ver aplicações de amostrade armazenamento Blob, continue a:To see Blob storage sample apps, continue to: