Biblioteca de cliente de Blobs de Armazenamento do Azure para .NET – versão 12.15.1

Artigo
04/03/2023

Versão do Servidor: 2021-02-12, 2020-12-06, 2020-10-02, 2020-08-04, 2020-06-12, 2020-04-08, 2020-02-10, 2019-12-12, 2019-07-07 e 2019-02-02

O Armazenamento de blobs do Azure é a solução de armazenamento de objetos da Microsoft para a cloud. O armazenamento de blobs está otimizado para armazenar quantidades em grande escala de dados não estruturados. 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.

Código fonte | Pacote (NuGet) | Documentação | de referência da API Documentação | da API REST Documentação do produto

Introdução

Instalar o pacote

Instale a biblioteca de cliente dos Blobs de Armazenamento do Azure para .NET com NuGet:

dotnet add package Azure.Storage.Blobs

Pré-requisitos

Precisa de uma subscrição do Azure e de uma Conta de Armazenamento para utilizar este pacote.

Para criar uma nova Conta de Armazenamento, pode utilizar o Portal do Azure, o Azure PowerShell ou a CLI do Azure. Eis um exemplo com a CLI do Azure:

az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS

Autenticar o cliente

Para interagir com o serviço armazenamento de Blobs do Azure, terá de criar uma instância da classe BlobServiceClient. A biblioteca de Identidades do Azure facilita a adição do suporte do Azure Active Directory para autenticar clientes do SDK do Azure com os serviços do Azure correspondentes.

// Create a BlobServiceClient that will authenticate through Active Directory
Uri accountUri = new Uri("https://MYSTORAGEACCOUNT.blob.core.windows.net/");
BlobServiceClient client = new BlobServiceClient(accountUri, new DefaultAzureCredential());

Saiba mais sobre como ativar o Azure Active Directory para autenticação com o Armazenamento do Azure na nossa documentação e nos nossos exemplos.

Conceitos-chave

O Armazenamento de blobs foi concebido para:

Entrega de imagens ou documentos diretamente a um browser.
Armazenamento de ficheiros para acesso distribuído.
Transmissão de áudio e vídeo.
Escrever nos ficheiros de registo.
Armazenamento de dados de cópia de segurança e restauro, recuperação após desastre e arquivo.
Armazenamento de dados para análise por um serviço no local ou alojado no Azure.

O armazenamento de blobs oferece três tipos de recursos:

A conta de armazenamento utilizada através de BlobServiceClient
Um contentor na conta de armazenamento utilizada através de BlobContainerClient
Um blob num contentor utilizado através de BlobClient

Saiba mais sobre as opções de autenticação (incluindo Cadeias de Ligação, Chave Partilhada, Assinaturas de Chave Partilhada, Active Directory e acesso público anónimo)nos nossos exemplos.

Segurança de threads

Garantimos que todos os métodos de instância de cliente são seguros para threads e independentes uns dos outros (orientação). Isto garante que a recomendação de reutilização de instâncias de cliente é sempre segura, mesmo entre threads.

Conceitos adicionais

Exemplos

Carregar um blob

// Get a connection string to our Azure Storage account.  You can
// obtain your connection string from the Azure Portal (click
// Access Keys under Settings in the Portal Storage account blade)
// or using the Azure CLI with:
//
//     az storage account show-connection-string --name <account_name> --resource-group <resource_group>
//
// And you can provide the connection string to your application
// using an environment variable.

string connectionString = "<connection_string>";
string containerName = "sample-container";
string blobName = "sample-blob";
string filePath = "sample-file";

// Get a reference to a container named "sample-container" and then create it
BlobContainerClient container = new BlobContainerClient(connectionString, containerName);
container.Create();

// Get a reference to a blob named "sample-file" in a container named "sample-container"
BlobClient blob = container.GetBlobClient(blobName);

// Upload local file
blob.Upload(filePath);

Transferir um blob

// Get a temporary path on disk where we can download the file
string downloadPath = "hello.jpg";

// Download the public blob at https://aka.ms/bloburl
new BlobClient(new Uri("https://aka.ms/bloburl")).DownloadTo(downloadPath);

Enumerar blobs

// Get a connection string to our Azure Storage account.
string connectionString = "<connection_string>";
string containerName = "sample-container";
string filePath = "hello.jpg";

// Get a reference to a container named "sample-container" and then create it
BlobContainerClient container = new BlobContainerClient(connectionString, containerName);
container.Create();

// Upload a few blobs so we have something to list
container.UploadBlob("first", File.OpenRead(filePath));
container.UploadBlob("second", File.OpenRead(filePath));
container.UploadBlob("third", File.OpenRead(filePath));

// Print out all the blob names
foreach (BlobItem blob in container.GetBlobs())
{
    Console.WriteLine(blob.Name);
}

APIs Assíncronas

Suportamos totalmente APIs síncronas e assíncronas.

// Get a temporary path on disk where we can download the file
string downloadPath = "hello.jpg";

// Download the public blob at https://aka.ms/bloburl
await new BlobClient(new Uri("https://aka.ms/bloburl")).DownloadToAsync(downloadPath);

Resolução de problemas

Todas as operações do serviço Blob irão emitir uma RequestFailedException em caso de falha com s útilErrorCode. Muitos destes erros são recuperáveis.

// Get a connection string to our Azure Storage account.
string connectionString = "<connection_string>";
string containerName = "sample-container";

// Try to delete a container named "sample-container" and avoid any potential race conditions
// that might arise by checking if the container is already deleted or is in the process
// of being deleted.
BlobContainerClient container = new BlobContainerClient(connectionString, containerName);

try
{
    container.Delete();
}
catch (RequestFailedException ex)
    when (ex.ErrorCode == BlobErrorCode.ContainerBeingDeleted ||
          ex.ErrorCode == BlobErrorCode.ContainerNotFound)
{
    // Ignore any errors if the container being deleted or if it has already been deleted
}

Passos seguintes

Comece a utilizar os nossos exemplos de Blobs:

Hello World: carregar, transferir e listar blobs (ou de forma assíncrona)
Autenticação: autenticar com cadeias de ligação, acesso público, chaves partilhadas, assinaturas de acesso partilhado e o Azure Active Directory.

Contribuir

Veja a CONTRIBUTING.md de Armazenamento para obter detalhes sobre como criar, testar e contribuir para esta biblioteca.

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Impressões