Listar contêineres de blob com Go

  • Artigo

Ao listar contêineres em uma conta de Armazenamento do Microsoft Azure do seu código, você pode especificar várias opções para gerenciar o modo como os resultados são retornados do Armazenamento do Microsoft Azure. Esse artigo mostra como listar contêineres usando o módulo de cliente do Armazenamento do Azure para Go.

Pré-requisitos

Configure seu ambiente

Se você não tiver um projeto existente, esta seção mostrará como configurar um projeto para trabalhar com o módulo de cliente do Armazenamento de Blobs do Azure para Go. As etapas incluem a instalação do módulo, a adição de caminhos import e a criação de um objeto 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 módulo azidentity usando o comando a seguir:

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 uso de exemplo, consulte Exemplos de código.

Criar um objeto cliente

Para conectar um aplicativo ao Armazenamento de Blobs, 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 precisa ter as permissões necessárias para listar contêineres de blob. Para autorização com o Microsoft Entra ID (recomendado), você precisa da função interna de Colaborador de Dados de Blob de Armazenamento ou superior do RBAC do Azure. Para saber mais, consulte as diretrizes de autorização para Listar Contêineres (API REST).

Sobre as opções de listagem de contêineres

Ao listar contêineres do código, você pode especificar 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ê também pode filtrar os resultados por um prefixo e retornar metadados de contêiner com os resultados. Essas opções são descritas nas seções a seguir.

Para listar contêineres em uma conta de armazenamento, chame o seguinte método:

Esse método retorna um Pager, que permite que seu aplicativo processe uma página de resultados de cada vez. Os contêineres são ordenados lexicograficamente pelo nome.

Você pode especificar opções para listar contêineres usando o struct ListContainersOptions. Esse struct inclui campos para gerenciar o número de resultados, filtrar por prefixo e incluir informações de contêiner usando ListContainersInclude.

Gerenciar quantos resultados são retornados

Por padrão, uma operação de listagem retorna até 5.000 resultados por vez. Para retornar um conjunto menor de resultados, forneça um valor diferente de zero para o campo MaxResults no struct ListContainersOptions.

Filtrar resultados com um prefixo

Para filtrar a lista de contêineres, especifique uma cadeia de caracteres ou um caractere para o campo Prefix em ListContainersOptions. A cadeia de caracteres de prefixo pode incluir um ou mais caracteres. O Armazenamento do Azure então retorna somente os contêineres cujos nomes começam com esse prefixo.

Incluir metadados de contêiner

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

Incluir contêineres excluídos

Para incluir contêineres excluídos com os resultados, defina o campo Deleted como true como parte de ListContainersInclude.

Exemplos de código

O exemplo a seguir lista todos os contêineres e metadados:

func listContainers(client *azblob.Client) {
    // List the containers in the storage account and include metadata
    pager := client.NewListContainersPager(&azblob.ListContainersOptions{
        Include: azblob.ListContainersInclude{Metadata: true},
    })

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

        for _, container := range resp.ContainerItems {
            fmt.Println(*container.Name)
            for k, v := range container.Metadata {
                fmt.Printf("%v: %v\n", k, *v)
            }
        }
    }
}

O seguinte exemplo lista apenas contêineres que começam com um prefixo especificado:

func listContainersWithPrefix(client *azblob.Client, prefix string) {
    // List the containers in the storage account with a prefix
    pager := client.NewListContainersPager(&azblob.ListContainersOptions{
        Prefix: &prefix,
    })

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

        for _, container := range resp.ContainerItems {
            fmt.Println(*container.Name)
        }
    }
}

Você também pode especificar um limite para o número de resultados por página. Este exemplo passa um valor para MaxResults e pagina os resultados:

func listContainersWithMaxResults(client *azblob.Client, maxResults int32) {
    // List the containers in the storage account with a maximum number of results
    pager := client.NewListContainersPager(&azblob.ListContainersOptions{
        MaxResults: &maxResults,
    })

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

        // Show page number to demonstrate pagination with max results
        i++
        fmt.Printf("Page %d:\n", i)

        for _, container := range resp.ContainerItems {
            fmt.Println(*container.Name)
        }
    }
}

Observação

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

Recursos

Para saber mais sobre como listar contêineres usando ao módulo de clientes do Armazenamento de Blobs do Azure para Go, consulte os recursos a seguir.

Exemplos de código

Operações da API REST

O SDK do Azure para linguagem Go contém bibliotecas que se baseiam na API REST do Azure, permitindo a interação com as operações de API REST por meio de paradigmas conhecidos do Go. Os métodos da biblioteca de clientes para listar contêineres usam a seguinte operação de API REST:

Recursos do módulo de cliente

Confira também

Conteúdo relacionado

  • Este artigo faz parte do guia para desenvolvedores do Armazenamento de Blobs para Go. Para saber mais, veja a lista completa de artigos do guia do desenvolvedor em Criar seu aplicativo Go.