List blobs with Go

  • Article

This article shows how to list blobs using the Azure Storage client module for Go.

Prerequisites

Set up your environment

If you don't have an existing project, this section shows how to set up a project to work with the Azure Blob Storage client module for Go. The steps include module installation, adding import paths, and creating an authorized client object. For details, see Get started with Azure Blob Storage and Go.

Install modules

Install the azblob module using the following command:

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

To authenticate with Microsoft Entra ID (recommended), install the azidentity module using the following command:

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

Add import paths

In your code file, add the following import paths:

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

These import paths represent the minimum needed to get started. Some code examples in this article might require additional import paths. For specific details and example usage, see Code samples.

Create a client object

To connect an app to Blob Storage, create a client object using azblob.NewClient. The following example shows how to create a client object using DefaultAzureCredential for authorization:

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
}

Authorization

The authorization mechanism must have the necessary permissions to upload a blob. For authorization with Microsoft Entra ID (recommended), you need Azure RBAC built-in role Storage Blob Data Reader or higher. To learn more, see the authorization guidance for List Blobs (REST API).

About blob listing options

When you list blobs from your code, you can specify many options to manage how results are returned from Azure Storage. You can specify the number of results to return in each set of results, and then retrieve the subsequent sets. You can specify a prefix to return blobs whose names begin with that character or string. And you can list blobs in a flat listing structure, or hierarchically. A hierarchical listing returns blobs as though they were organized into folders.

To list the blobs in a container using a flat listing, call the following method:

To list the blobs in a container using a hierarchical listing, call the following method from a container client object:

Manage how many results are returned

By default, a listing operation returns up to 5000 results at a time. To return a smaller set of results, provide a nonzero value for the MaxResults field in ListBlobsFlatOptions or ListBlobsHierarchyOptions.

Filter results with a prefix

To filter the list of blobs returned, specify a string or character for the Prefix field in ListBlobsFlatOptions or ListBlobsHierarchyOptions. The prefix string can include one or more characters. Azure Storage then returns only the blobs whose names start with that prefix.

Include blob metadata or other information

To include blob metadata with the results, set the Metadata field to true as part of ListBlobsInclude. Azure Storage includes metadata with each blob returned, so you don't need to fetch the blob metadata separately.

See ListBlobsInclude for additional options to include snapshots, versions, blob index tags, and other information with the results.

Flat listing versus hierarchical listing

Blobs in Azure Storage are organized in a flat paradigm, rather than a hierarchical paradigm (like a classic file system). However, you can organize blobs into virtual directories in order to mimic a folder structure. A virtual directory forms part of the name of the blob and is indicated by the delimiter character.

To organize blobs into virtual directories, use a delimiter character in the blob name. The default delimiter character is a forward slash (/), but you can specify any character as the delimiter.

If you name your blobs using a delimiter, then you can choose to list blobs hierarchically. For a hierarchical listing operation, Azure Storage returns any virtual directories and blobs beneath the parent object. You can call the listing operation recursively to traverse the hierarchy, similar to how you would traverse a classic file system programmatically.

Note

Blob snapshots cannot be listed in a hierarchical listing operation.

Use a flat listing

By default, a listing operation returns blobs in a flat listing. In a flat listing, blobs aren't organized by virtual directory.

The following example lists the blobs in the specified container using a flat listing. This example includes blob snapshots and blob versions, if they exist:

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)
        }
    }
}

Sample output is similar to:

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

The following example lists blobs in a container that begin with a specific prefix:

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)
        }
    }
}

When passing a prefix string of "sample", output is similar to:

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

Note

The sample output shown assumes that you have a storage account with a flat namespace. If you've enabled the hierarchical namespace feature for your storage account, directories are not virtual. Instead, they are concrete, independent objects. As a result, directories appear in the list as zero-length blobs.

For an alternative listing option when working with a hierarchical namespace, see NewListPathsPager.

Use a hierarchical listing

When you call a listing operation hierarchically, Azure Storage returns the virtual directories and blobs at the first level of the hierarchy.

To list blobs hierarchically, use the following method:

The following example lists the blobs in the specified container using a hierarchical listing. In this example, the prefix parameter is initially set to an empty string to list all blobs in the container. The example then calls the listing operation recursively to traverse the virtual directory hierarchy and list 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)
        }
    }
}

Sample output is similar to:

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

Note

The code samples in this guide are intended to help you get started with Azure Blob Storage and Go. You should modify error handling and Context values to meet the needs of your application.

Resources

To learn more about how to list blobs using the Azure Blob Storage client module for Go, see the following resources.

Code samples

REST API operations

The Azure SDK for Go contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar Go paradigms. The client library methods for listing blobs use the following REST API operation:

Client module resources

See also

Related content

  • This article is part of the Blob Storage developer guide for Go. To learn more, see the full list of developer guide articles at Build your Go app.