Partilhar via

Listar blobs com Go

  • Artigo

Este artigo mostra como listar blobs usando o módulo de cliente de Armazenamento do Azure para Go.

Pré-requisitos

Configurar o ambiente

Se você não tiver um projeto existente, esta seção mostra como configurar um projeto para trabalhar com o módulo de cliente de Armazenamento de Blob do Azure para Go. As etapas incluem a instalação do módulo, a adição de import caminhos e a criação de um objeto de cliente autorizado. Para obter detalhes, consulte Introdução ao Armazenamento de Blobs do Azure e Go.

Instalar módulos

Instale o módulo azblob usando o seguinte comando:

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

Para autenticar com o Microsoft Entra ID (recomendado), instale o azidentity módulo usando o seguinte comando:

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Adicionar caminhos de importação

No arquivo de código, adicione os seguintes caminhos de importação:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

Esses caminhos de importação representam o mínimo necessário para começar. Alguns exemplos de código neste artigo podem exigir caminhos de importação adicionais. Para obter detalhes específicos e exemplos de uso, consulte Exemplos de código.

Criar um objeto cliente

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

func getServiceClientTokenCredential(accountURL string) *azblob.Client {
    // Create a new service client with token credential
    credential, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(accountURL, credential, nil)
    handleError(err)

    return client
}

Autorização

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

Sobre as opções de listagem de blob

Ao listar blobs do seu código, você pode especificar muitas 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. E você pode listar blobs em uma estrutura de listagem simples ou hierarquicamente. Uma listagem hierárquica retorna blobs como se estivessem organizados em pastas.

Para listar os blobs em um contêiner usando uma listagem simples, chame o seguinte método:

Para listar os blobs em um contêiner usando uma listagem hierárquica, chame o seguinte método de um objeto de cliente de contêiner:

Gerenciar quantos resultados são retornados

Por padrão, uma operação de listagem retorna até 5000 resultados de cada vez. Para retornar um conjunto menor de resultados, forneça um valor diferente de zero para o MaxResults campo em ListBlobsFlatOptions ou ListBlobsHierarchyOptions.

Filtrar resultados com um prefixo

Para filtrar a lista de blobs retornados, especifique uma cadeia de caracteres ou caractere para o Prefix campo em ListBlobsFlatOptions ou ListBlobsHierarchyOptions. 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.

Incluir metadados de blob ou outras informações

Para incluir metadados de blob com os resultados, defina o Metadata campo como true parte de ListBlobsInclude. O Armazenamento do Azure inclui metadados com cada blob retornado, portanto, você não precisa buscar os metadados do blob separadamente.

Consulte ListBlobsInclude para obter opções adicionais para incluir instantâneos, versões, tags de índice de blob e outras informações com os resultados.

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.

Nota

Os instantâneos de Blob não podem ser listados em uma operação de listagem hierárquica.

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 a seguir lista os blobs no contêiner especificado usando uma listagem simples. Este exemplo inclui instantâneos de blob e versões de blob, se existirem:

func listBlobsFlat(client *azblob.Client, containerName string) {
    // List the blobs in the container
    pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
        Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
    })

    fmt.Println("List blobs flat:")
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println(*blob.Name)
        }
    }
}

A saída da amostra é semelhante a:

List blobs flat:
file4.txt
folderA/file1.txt
folderA/file2.txt
folderA/folderB/file3.txt

O exemplo a seguir lista blobs em um contêiner que começam com um prefixo específico:

func listBlobsFlatOptions(client *azblob.Client, containerName string, prefix string) {
    // List the blobs in the container with a prefix
    pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
        Prefix: to.Ptr(prefix),
    })

    fmt.Println("List blobs with prefix:")
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println(*blob.Name)
        }
    }
}

Ao passar uma string de prefixo de "sample", a saída é semelhante a:

List blobs with prefix:
sample-blob1.txt
sample-blob2.txt
sample-blob3.txt

Nota

A saída de exemplo mostrada pressupõe que você tenha uma conta de armazenamento com um namespace simples. Se você habilitou o recurso de namespace hierárquico para sua conta de armazenamento, os diretórios não são virtuais. Em vez disso, são objetos concretos e independentes. Como resultado, os diretórios aparecem na lista como blobs de comprimento zero.

Para obter uma opção de listagem alternativa ao trabalhar com um namespace hierárquico, consulte NewListPathsPager.

Usar uma listagem hierárquica

Quando você chama uma operação de listagem hierarquicamente, o Armazenamento do Azure retorna os diretórios virtuais e blobs no primeiro nível da hierarquia.

Para listar blobs hierarquicamente, use o seguinte método:

O exemplo a seguir lista os blobs no contêiner especificado usando uma listagem hierárquica. Neste exemplo, o parâmetro prefix é inicialmente definido como uma cadeia de caracteres vazia para listar todos os blobs no contêiner. Em seguida, o exemplo chama a operação de listagem recursivamente para percorrer a hierarquia de diretórios virtuais e listar blobs.

func listBlobsHierarchy(client *azblob.Client, containerName string, prefix string) {
    // Reference the container as a client object
    containerClient := client.ServiceClient().NewContainerClient(containerName)

    pager := containerClient.NewListBlobsHierarchyPager("/", &container.ListBlobsHierarchyOptions{
        Prefix:     to.Ptr(prefix),
        MaxResults: to.Ptr(int32(1)), // MaxResults set to 1 for demonstration purposes
    })

    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        if resp.Segment.BlobPrefixes != nil {
            for _, prefix := range resp.Segment.BlobPrefixes {
                fmt.Println("Virtual directory prefix:", *prefix.Name)

                // Recursively list blobs in the prefix
                listBlobsHierarchy(client, containerName, *prefix.Name)
            }
        }

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println("Blob:", *blob.Name)
        }
    }
}

A saída da amostra é semelhante a:

Virtual directory prefix: folderA/
Blob: folderA/file1.txt
Blob: folderA/file2.txt
Blob: folderA/file3.txt
Virtual directory prefix: folderA/folderB/
Blob: folderA/folderB/file1.txt
Blob: folderA/folderB/file2.txt
Blob: folderA/folderB/file3.txt

Nota

Os exemplos de código neste guia destinam-se a ajudá-lo a começar a usar o Azure Blob Storage and Go. Você deve modificar o tratamento de erros e Context os valores para atender às necessidades do seu aplicativo.

Recursos

Para saber mais sobre como listar blobs usando o módulo de cliente do Armazenamento de Blobs do Azure para Go, consulte os recursos a seguir.

Amostras de código

  • Exibir exemplos de código deste artigo (GitHub)

Operações da API REST

O SDK do Azure para Go contém bibliotecas que se baseiam na API REST do Azure, permitindo que você interaja com operações da API REST por meio de paradigmas Go familiares. Os métodos de biblioteca de cliente para listar blobs usam a seguinte operação de API REST:

Recursos do módulo cliente

Consulte também

Conteúdos relacionados

  • Este artigo faz parte do guia do desenvolvedor do Blob Storage para Go. Para saber mais, consulte a lista completa de artigos do guia do desenvolvedor em Crie seu aplicativo Go.