Biblioteca de clientes de Blobs de Armazenamento do Azure para .NET – versão 12.19.0

Artigo
11/06/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 é uma solução de armazenamento de objetos da Microsoft para a nuvem. O armazenamento de Blobs é otimizado para armazenar grandes quantidades de dados não estruturados. Dados não estruturados são dados que não estão de acordo com uma definição ou um modelo de dados específico, como texto ou dados binários.

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

Introdução

Instalar o pacote

Instale a biblioteca de clientes de Blobs de Armazenamento do Azure para .NET com o NuGet:

dotnet add package Azure.Storage.Blobs

Pré-requisitos

Você precisa de uma assinatura do Azure e uma Conta de Armazenamento para usar esse pacote.

Para criar uma nova Conta de Armazenamento, você pode usar o Portal do Azure, Azure PowerShell ou a CLI do Azure. Aqui, está um exemplo usando 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 de Armazenamento de Blobs do Azure, você precisará criar uma instância da classe BlobServiceClient. A biblioteca de Identidade do Azure facilita a adição do suporte do Azure Active Directory para autenticar clientes do SDK do Azure com seus serviços correspondentes do Azure.

// 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 habilitar o Azure Active Directory para autenticação com o Armazenamento do Azure em nossa documentação e nossos exemplos.

Principais conceitos

O Armazenamento de Blobs foi projetado para:

Fornecimento de imagens ou de documentos diretamente a um navegador.
Armazenamento de arquivos para acesso distribuído.
Transmissão por streaming de áudio e vídeo.
Gravando nos arquivo de log.
Armazenamento de dados de backup e restauração, recuperação de desastres e arquivamento.
Armazenamento de dados para análise por um serviço local ou hospedado no Azure.

O Armazenamento de Blobs oferece três tipos de recursos:

A conta de armazenamento usada por meio de BlobServiceClient
Um contêiner na conta de armazenamento usada por meio de BlobContainerClient
Um blob em um contêiner usado por meio de BlobClient

Saiba mais sobre as opções de autenticação (incluindo Cadeias de Conexão, Chave Compartilhada, Assinaturas de Chave Compartilhada, Active Directory e acesso público anônimo)em nossos exemplos.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Exemplos

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

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

Enumerando 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

Damos suporte total a 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);

Solução de problemas

Todas as operações do serviço Blob lançarão uma RequestFailedException em caso de falha com s úteisErrorCode. Muitos desses 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
}

Próximas etapas

Introdução aos nossos exemplos de Blob:

Olá, Mundo: carregar, baixar e listar blobs (ou de forma assíncrona)
Autenticação: autentique-se com cadeias de conexão, acesso público, chaves compartilhadas, assinaturas de acesso compartilhado e Azure Active Directory.

Participante

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

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões