Introdução ao Armazenamento de Blobs do Azure e .NET

Artigo
10/26/2023

Este artigo mostra como se conectar ao Armazenamento de Blobs do Azure usando a biblioteca de clientes do Armazenamento de Blobs do Azure para .NET. Após se conectar, seu código pode operar em contêineres, blobs e recursos do serviço de Armazenamento de Blobs.

Referência de API | Código-fonte da biblioteca | Pacote (NuGet) | Exemplos | Fazer comentários

Pré-requisitos

Assinatura do Azure - criar uma gratuitamente
Conta de armazenamento do Azure – criar uma conta de armazenamento
O SDK do .NET atual para o seu sistema operacional. Obtenha o SDK e não o runtime.

Configurar o seu projeto

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

No diretório do projeto, instale pacotes para as bibliotecas de cliente do Armazenamento de Blobs do Azure e do Azure Identity usando o comando dotnet add package. O pacote Azure.Identity é necessário para conexões sem senha com os serviços do Azure.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Adicione essas instruções using ao início de seu arquivo de código.

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

Informações da biblioteca de clientes do blob:

Azure.Storage.Blobs: contém as classes primárias (objetos cliente) que você pode usar para operar no serviço, contêineres e blobs.
Azure.Storage.Blobs.Specialized: contém classes que você pode usar para executar operações específicas a um tipo de blob, como blobs de blocos.
Azure.Storage.Blobs.Models: todas as outras classes, estruturas e tipos de enumeração utilitários.

Autorizar o acesso e se conectar ao Armazenamento de Blobs

Para conectar um aplicativo ao Armazenamento de Blobs, crie uma instância da classe BlobServiceClient. Esse objeto é seu ponto de partida para interagir com os recursos de dados no nível da conta de armazenamento. Você pode usá-lo para operar na conta de armazenamento e nos respectivos contêineres. Você também pode usar o cliente de serviço para criar clientes de contêiner ou clientes de blob, dependendo do recurso com o qual você precisa trabalhar.

Para saber mais sobre como criar e gerenciar objetos clientes, confira Criar e gerenciar objetos clientes que interagem com recursos de dados.

Você pode autorizar um objeto BlobServiceClient usando um token de autorização do Microsoft Entra, uma chave de acesso de conta ou uma assinatura de acesso compartilhado (SAS).

Para saber mais sobre cada um desses mecanismos de autorização, confira Autorizar o acesso a dados no Armazenamento do Microsoft Azure.

Para autorizar com a ID do Microsoft Entra, você precisará usar uma entidade de segurança. O tipo de entidade de segurança necessário depende do local em que o aplicativo é executado. Use essa tabela como um guia.

Onde o aplicativo é executado	Entidade de segurança	Diretrizes
Computador local (desenvolvimento e teste)	Entidade de serviço	Para saber como registrar o aplicativo, configurar um grupo do Microsoft Entra, atribuir funções e configurar variáveis de ambiente, confira Autorizar o acesso usando entidades de serviço do desenvolvedor
Computador local (desenvolvimento e teste)	Identidade do usuário	Para saber como configurar um grupo do Microsoft Entra, atribuir funções e entrar no Azure, confira Autorizar o acesso usando credenciais de desenvolvedor
Hospedada no Azure	Identidade gerenciada	Para saber como habilitar a identidade gerenciada e atribuir funções, confira Autorizar o acesso de aplicativos hospedados no Azure usando uma identidade gerenciada
Hospedado fora do Azure (por exemplo, aplicativos locais)	Entidade de serviço	Para saber como registrar o aplicativo, atribuir funções e configurar variáveis de ambiente, confira Autorizar o acesso em aplicativos locais usando uma entidade de serviço de aplicativo

Autorizar o acesso usando DefaultAzureCredential

Uma maneira fácil e segura de autorizar o acesso e se conectar ao Armazenamento de Blobs é obter um token OAuth criando uma instância de DefaultAzureCredential. Depois, você pode usar essa credencial para criar um objeto BlobServiceClient.

O exemplo a seguir cria um objeto BlobServiceClient autorizado usando DefaultAzureCredential:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

Se você souber exatamente qual tipo de credencial usará para autenticar usuários, poderá obter um token OAuth usando outras classes na biblioteca de clientes de identidade do Azure para .NET. Essas classes são derivadas da classe TokenCredential.

Crie um URI usando o ponto de extremidade de serviço de blob e o token SAS. Em seguida, crie um BlobServiceClient usando o URI.

public static void GetBlobServiceClientSAS(ref BlobServiceClient blobServiceClient,
    string accountName, string sasToken)
{
    string blobUri = "https://" + accountName + ".blob.core.windows.net";

    blobServiceClient = new BlobServiceClient
    (new Uri($"{blobUri}?{sasToken}"), null);
}

Para saber mais sobre como gerar e gerenciar tokens SAS, confira os seguintes artigos:

Crie um StorageSharedKeyCredential usando o nome da conta de armazenamento e a chave de conta. Em seguida, use esse objeto para inicializar um BlobServiceClient.

public static void GetBlobServiceClient(ref BlobServiceClient blobServiceClient,
    string accountName, string accountKey)
{
    Azure.Storage.StorageSharedKeyCredential sharedKeyCredential =
        new StorageSharedKeyCredential(accountName, accountKey);

    string blobUri = "https://" + accountName + ".blob.core.windows.net";

    blobServiceClient = new BlobServiceClient
        (new Uri(blobUri), sharedKeyCredential);
}

Você também pode criar um BlobServiceClient usando uma cadeia de conexão.

BlobServiceClient blobServiceClient = new BlobServiceClient(connectionString);

Para obter informações sobre como obter chaves de conta e diretrizes de melhores práticas para gerenciar e proteger corretamente suas chaves, consulte Gerenciar chaves de acesso da conta de armazenamento.

Importante

A chave de acesso da conta deve ser usada com cautela. Se a chave de acesso da conta for perdida ou colocada acidentalmente em um local inseguro, o serviço poderá ficar vulnerável. Qualquer pessoa que tenha a chave de acesso pode autorizar solicitações na conta de armazenamento e efetivamente tem acesso a todos os dados. DefaultAzureCredential fornece recursos e benefícios de segurança avançados e é a abordagem recomendada para gerenciar a autorização para os serviços do Azure.

Para saber mais sobre cada um desses mecanismos de autorização, confira Autorizar o acesso a dados no Armazenamento do Microsoft Azure.

Crie seu aplicativo

À medida que você cria aplicativos para trabalhar com recursos de dados no Armazenamento de Blobs do Azure, seu código interage principalmente com três tipos de recursos: contas de armazenamento, contêineres e blobs. Para saber mais sobre esses tipos de recursos, como eles se relacionam entre si e como os aplicativos interagem com os recursos, confira Entender como os aplicativos interagem com os recursos de dados do Armazenamento de Blobs.

Os guias a seguir mostram como trabalhar com recursos de dados e executar ações específicas usando a biblioteca de clientes do Armazenamento do Azure para .NET:

Guia	Descrição
Criar um contêiner	Crie contêineres.
Excluir e restaurar contêineres	Exclua contêineres e, se a exclusão reversível estiver habilitada, restaure os contêineres excluídos.
Listar contêineres	Liste os contêineres em uma conta e as diversas opções disponíveis para personalizar uma listagem.
Gerenciar propriedades e metadados	Obtenha e defina as propriedades e metadados dos contêineres.
Criar e gerenciar concessões de contêiner	Estabeleça e gerencie um bloqueio em um contêiner.
Criar e gerenciar concessões de blob	Estabeleça e gerencie um bloqueio em um blob.
Acrescentar dados a blobs	Saiba como criar um blob de acréscimo e, em seguida, acrescentar dados a esse blob.
Carregar blobs	Saiba como carregar blobs usando cadeias de caracteres, fluxos, caminhos de arquivo e outros métodos.
Baixar blobs	Baixe blobs usando cadeias de caracteres, fluxos e caminhos de arquivo.
Copiar blobs	Copie um blob de uma localização para outra.
Listar blobs	Liste blobs de maneiras diferentes.
Excluir e restauração	Exclua os blobs, e, se a exclusão reversível estiver habilitada, restaure os blobs excluídos.
Encontrar blobs usando marcas	Defina e recupere marcas e use as marcas para localizar blobs.
Gerenciar propriedades e metadados	Obtenha e defina as propriedades e metadados dos blobs.
Definir ou alterar o nível de acesso de um blob	Defina ou altere a camada de acesso para um blob de blocos.

Share via