Listar blobs com o .NET

Este artigo mostra como listar blobs usando a biblioteca cliente Armazenamento do Azure para .NET.

Pré-requisitos

• Subscrição do Azure - crie uma gratuitamente
• Conta de armazenamento do Azure - criar uma conta de armazenamento
• SDK .NET mais recente para seu sistema operacional. Certifique-se de obter o SDK e não o tempo de execução.

Configurar o ambiente

Se você não tiver um projeto existente, esta seção mostra como configurar um projeto para trabalhar com a biblioteca de cliente do Armazenamento de Blobs do Azure para .NET. As etapas incluem a instalação do pacote, a adição de using diretivas e a criação de um objeto de cliente autorizado. Para obter detalhes, consulte Introdução ao Armazenamento de Blobs do Azure e ao .NET.

Instalar pacotes

No diretório do projeto, instale pacotes para o Armazenamento de Blobs do Azure e as bibliotecas de cliente do Azure Identity usando o dotnet add package comando. 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

Adicionar using diretivas

Adicione estas using diretivas no topo do seu ficheiro de código:

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

Alguns exemplos de código neste artigo podem exigir diretivas adicionais using .

Criar um objeto cliente

Para conectar um aplicativo ao Armazenamento de Blob, crie uma instância de BlobServiceClient. O exemplo a seguir mostra como criar um objeto cliente usando DefaultAzureCredential para autorização:

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

    return client;
}

Pode registar um cliente de serviço para injeção de dependência numa aplicação .NET.

Você também pode criar objetos de cliente para contêineres ou blobs específicos. Para saber mais sobre como criar e gerenciar objetos de cliente, consulte Criar e gerenciar objetos de cliente que interagem com recursos de dados.

Autorização

O mecanismo de autorização deve ter as permissões necessárias para listar um blob. Para a autorização com o Microsoft Entra ID (recomendada), precisa da função incorporada do Azure RBAC Storage Blob Data Reader ou superior. Para saber mais, consulte as diretrizes de autorização para Listar Blobs (API REST).

Acerca das opções de listagem de blobs

Ao listar blobs do seu código, você pode especificar várias opções para gerenciar como os resultados são retornados do Armazenamento do Azure. Você pode especificar o número de resultados a serem retornados em cada conjunto de resultados e, em seguida, recuperar os conjuntos subsequentes. Você pode especificar um prefixo para retornar blobs cujos nomes comecem com esse caractere ou cadeia de caracteres. Podes listar blobs numa estrutura de listagem plana ou hierarquicamente. Uma listagem hierárquica retorna blobs como se estivessem organizados em pastas.

Para listar os blobs em uma conta de armazenamento, chame um destes métodos:

• BlobContainerClient.GetBlobs
• BlobContainerClient.GetBlobsAsync
• BlobContainerClient.GetBlobsByHierarchy
• BlobContainerClient.GetBlobsByHierarchyAsync

Gerenciar quantos resultados são retornados

Por padrão, uma operação de listagem retorna até 5000 resultados de cada vez, mas você pode especificar o número de resultados que deseja que cada operação de listagem retorne. Os exemplos apresentados neste artigo mostram como retornar resultados em páginas. Para saber mais sobre conceitos de paginação, consulte Paginação com o SDK do Azure para .NET.

Filtrar resultados com um prefixo

Para filtrar a lista de blobs, especifique uma cadeia de caracteres para o prefix parâmetro. A cadeia de caracteres de prefixo pode incluir um ou mais caracteres. Em seguida, o Armazenamento do Azure retorna apenas os blobs cujos nomes começam com esse prefixo.

Metadados devolvidos

Pode devolver os metadados do blob com os resultados ao especificar o valor Metadata para a enumeração BlobTraits.

Listagem simples versus listagem hierárquica

Os blobs no Armazenamento do Azure são organizados em um paradigma simples, em vez de um paradigma hierárquico (como um sistema de arquivos clássico). No entanto, você pode organizar blobs em diretórios virtuais para imitar uma estrutura de pastas. Um diretório virtual faz parte do nome do blob e é indicado pelo caractere delimitador.

Para organizar blobs em diretórios virtuais, use um caractere delimitador no nome do blob. O caractere delimitador padrão é uma barra (/), mas você pode especificar qualquer caractere como o delimitador.

Se você nomear seus blobs usando um delimitador, poderá optar por listá-los hierarquicamente. Para uma operação de listagem hierárquica, o Armazenamento do Azure retorna todos os diretórios virtuais e blobs abaixo do objeto pai. Você pode chamar a operação de listagem recursivamente para percorrer a hierarquia, semelhante a como você atravessaria um sistema de arquivos clássico programaticamente.

Usar uma listagem simples

Por padrão, uma operação de listagem retorna blobs em uma listagem simples. Em uma listagem simples, os blobs não são organizados por diretório virtual.

O exemplo seguinte lista os blobs no contentor especificado usando uma listagem plana, com um tamanho de segmento opcional especificado, e escreve o nome do blob numa janela de consola.

private static async Task ListBlobsFlatListing(BlobContainerClient blobContainerClient, 
                                               int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = blobContainerClient.GetBlobsAsync()
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobItem> blobPage in resultSegment)
        {
            foreach (BlobItem blobItem in blobPage.Values)
            {
                Console.WriteLine("Blob name: {0}", blobItem.Name);
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

A saída de amostra é semelhante a:

Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

Usar uma listagem hierárquica

Quando chama uma operação de listagem hierárquica, o Armazenamento do Azure devolve os diretórios virtuais e os blobs no primeiro nível da hierarquia.

Para listar blobs hierarquicamente, chame o método BlobContainerClient.GetBlobsByHierarchy ou o método BlobContainerClient.GetBlobsByHierarchyAsync .

O exemplo seguinte lista os blobs no contentor especificado usando uma listagem hierárquica, com um tamanho de segmento opcional especificado, e escreve o nome do blob na janela da consola.

private static async Task ListBlobsHierarchicalListing(BlobContainerClient container, 
                                                       string prefix, 
                                                       int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = container.GetBlobsByHierarchyAsync(prefix:prefix, delimiter:"/")
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobHierarchyItem> blobPage in resultSegment)
        {
            // A hierarchical listing may return both virtual directories and blobs.
            foreach (BlobHierarchyItem blobhierarchyItem in blobPage.Values)
            {
                if (blobhierarchyItem.IsPrefix)
                {
                    // Write out the prefix of the virtual directory.
                    Console.WriteLine("Virtual directory prefix: {0}", blobhierarchyItem.Prefix);

                    // Call recursively with the prefix to traverse the virtual directory.
                    await ListBlobsHierarchicalListing(container, blobhierarchyItem.Prefix, null);
                }
                else
                {
                    // Write out the name of the blob.
                    Console.WriteLine("Blob name: {0}", blobhierarchyItem.Blob.Name);
                }
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

A saída de amostra é semelhante a:

Virtual directory prefix: FolderA/
Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt

Virtual directory prefix: FolderA/FolderB/
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt

Virtual directory prefix: FolderA/FolderB/FolderC/
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

Listar versões ou instantâneos de blobs

Para listar versões ou instantâneos de blobs, especifique o parâmetro BlobStates com o campo Version ou Snapshot. O serviço devolve versões e snapshots do mais antigo ao mais recente.

O exemplo de código seguinte mostra como listar as versões de blob.

private static void ListBlobVersions(BlobContainerClient blobContainerClient, 
                                           string blobName)
{
    try
    {
        // Call the listing operation, specifying that blob versions are returned.
        // Use the blob name as the prefix. 
        var blobVersions = blobContainerClient.GetBlobs
            (BlobTraits.None, BlobStates.Version, prefix: blobName)
            .OrderByDescending(version => version.VersionId).Where(blob => blob.Name == blobName);

        // Construct the URI for each blob version.
        foreach (var version in blobVersions)
        {
            BlobUriBuilder blobUriBuilder = new BlobUriBuilder(blobContainerClient.Uri)
            {
                BlobName = version.Name,
                VersionId = version.VersionId
            };

            if ((bool)version.IsLatestVersion.GetValueOrDefault())
            {
                Console.WriteLine("Current version: {0}", blobUriBuilder);
            }
            else
            {
                Console.WriteLine("Previous version: {0}", blobUriBuilder);
            }
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

Listar blobs no formato Apache Arrow (pré-visualização)

Esta funcionalidade baseia-se na API existente List Blobs . Em vez de usar o XML predefinido, utiliza o formato Apache Arrow, compacto e colunar, como formato de resposta na transmissão. Ativa-o definindo uma única opção na chamada de listagem de contentores. O SDK .NET decodifica o Apache Arrow nos bastidores e ainda assim devolve os mesmos BlobItem objetos. Esta abordagem melhora o desempenho da listagem e reduz a utilização da CPU no cliente durante a enumeração de contentores de grande dimensão. Preserva o contrato de resposta em que as candidaturas dependem.

Para solicitar resultados formatados em Apache Arrow, defina a propriedade ResponseFormat de GetBlobsOptions para StorageResponseFormat.Arrow, depois passe as opções para a sobrecarga BlobContainerClient.GetBlobs que aceite GetBlobsOptions. Ao usar a saída do Apache Arrow, também pode definir as propriedades StartFrom e EndBefore para controlar o intervalo de caminhos devolvidos.

O exemplo seguinte lista os blobs num contentor e solicita os resultados no formato Apache Arrow:

using Azure.Storage;
using Azure.Storage.Blobs.Models;

GetBlobsOptions options = new GetBlobsOptions
{
    Prefix = "FolderA/",
    ResponseFormat = StorageResponseFormat.Arrow
};

foreach (BlobItem blobItem in containerClient.GetBlobs(options))
{
    Console.WriteLine("Blob name: " + blobItem.Name);
}

Recursos

Para saber mais sobre como listar blobs usando a biblioteca cliente Armazenamento de Blobs do Azure para .NET, consulte os seguintes recursos.

Operações da API REST

O SDK do Azure para .NET contém bibliotecas que são construídas sobre a API REST do Azure. Ao utilizar estas bibliotecas, pode interagir com operações da API REST através de paradigmas .NET familiares. Os métodos de biblioteca de cliente para listar blobs usam a seguinte operação de API REST:

• Listagem de Blobs (API REST)

Recursos da biblioteca do cliente

• Documentação de referência da biblioteca cliente
• Código fonte da biblioteca cliente
• Pacote (NuGet)

Consulte também

• Enumerando recursos de Blob
• Controlo de versões do Blob

Conteúdos relacionados

• Este artigo faz parte do guia para programadores do Armazenamento de Blobs para .NET. Para saber mais, consulte a lista completa de artigos do guia do desenvolvedor em Crie seu aplicativo .NET.