Announcing the stable release of the Azure Blob Storage client library for Go

Sandeep Sen

March 8th, 20230 0

The Azure SDK for Go team at Microsoft is excited to announce the stable release of the Azure Blob Storage client library for Go. Azure Blob Storage is a secure object storage solution for the cloud. Azure Blob Storage is optimized for storing massive amounts of unstructured data—data that doesn’t adhere to a particular data model or definition, such as text or binary data.

NOTE: If you’re using the legacy Azure Blob Storage library for Go and would like to upgrade, see the migration guide.

Install the package

The Azure Blob Storage client library is named azblob. To install the latest version of azblob, use the go get command. You can use the Azure Identity library to authenticate the client application.

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

# Optionally, if you also want to use Azure Identity for authentication
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

We assume that you have:

An Azure subscription with an Azure Blob Storage container.
A working development environment for Go version 1.18 or above.

For instructions on creating an Azure Blob Storage container, follow this step-by-step guide.

Create a client

Client is a type that exposes methods that invoke service operations. A single Client type is shareable between multiple goroutines simultaneously and safely.

Azure Blob storage service offers three types of resources, the storage account that has one or more containers and one or more blobs in a container. Instances of the azblob.Client type provide methods to manipulate containers and blobs within a storage account. You must specify the storage account when you create azblob.Client.

You can create a client using an Azure Blob Storage connection string (obtained via the Azure portal) or with a TokenCredential type, such as DefaultAzureCredential from the Azure Identity library.

NOTE: We recommend you to use TokenCredential type for authentication, connection string authentication is not recommended.

Use the `DefaultAzureCredential` token credential (Recommended)

The DefaultAzureCredential combines several credential types into one easy-to-use type. It can authenticate using the Azure CLI, managed identities, and more. For more information, see the azidentity documentation.

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

func main() {
    tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)
    if err != nil {
        //TODO: handle error
        panic(err)
    }

    client, err := azblob.NewClient("<Azure Storage URL ex: https://my-blob.blob.core.windows.net/>", tokenCredential, nil)
    if err != nil {
        //TODO: handle error
        panic(err)
    }
}

Use Azure Blob Storage connection string

Azure Blob Storage also supports authentication using a connection string, which you can get from the Azure portal.

package main

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

func main() {
    serviceClient, err := azblob.NewClientFromConnectionString("<Azure Storage Connection String>", nil)
    if err != nil {
        //TODO: handle error
        panic(err)
    }
}

Container operations

The azblob.Client type exposes container operations that manipulate the lifecycle of the Azure Storage container.

Create a container

CreateContainer is a method that creates a new container under the specified account. This method returns a client for interacting with the newly created container. If a container with the same name already exists, the method call raises a ResourceExistsError.

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

func handleError(err error) {
    if err != nil {
        log.Fatal(err.Error())
    }
}

func main() {
    accountName, ok := os.LookupEnv("AZURE_STORAGE_ACCOUNT_NAME")
    if !ok {
        panic("AZURE_STORAGE_ACCOUNT_NAME could not be found")
    }
    serviceURL := fmt.Sprintf("https://%s.blob.core.windows.net/", accountName)

    cred, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(serviceURL, cred, nil)
    handleError(err)

    resp, err := client.CreateContainer(context.TODO(), "testcontainer", &azblob.CreateContainerOptions{
        Metadata: map[string]*string{"hello": to.Ptr("world")},
    })
    handleError(err)
    fmt.Println(resp)
}

Delete a container

DeleteContainer is a container lifecycle method that marks the specified container for deletion. During garbage collection, Azure deletes the container and any blobs within it. If the container is missing, the method call raises a ResourceNotFoundError.

package main

import (
    "context"
    "fmt"
    "log"
    "os"

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

func handleError(err error) {
    if err != nil {
        log.Fatal(err.Error())
    }
}

func main() {
    accountName, ok := os.LookupEnv("AZURE_STORAGE_ACCOUNT_NAME")
    if !ok {
        panic("AZURE_STORAGE_ACCOUNT_NAME could not be found")
    }
    serviceURL := fmt.Sprintf("https://%s.blob.core.windows.net/", accountName)

    cred, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(serviceURL, cred, nil)
    handleError(err)

    resp, err := client.DeleteContainer(context.TODO(), "testcontainer", nil)
    handleError(err)
    fmt.Println(resp)
}

Blob operations

The azblob.Client type exposes these operations that interact with the blobs that reside inside the Azure Storage container. These operations require a valid Azure Storage container name that you pass as a parameter.

Upload blob to a container

UploadFile uploads a file in blocks to a blob inside the Azure Storage container that you pass as a parameter.

package main

import (
    "context"
    "fmt"
    "log"
    "os"

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

func handleError(err error) {
    if err != nil {
        log.Fatal(err.Error())
    }
}

func main() {
    // Set up file to upload
    fileSize := 8 * 1024 * 1024
    fileName := "test_upload_file.txt"
    fileData := make([]byte, fileSize)
    err := os.WriteFile(fileName, fileData, 0666)
    handleError(err)

    // Open the file to upload
    fileHandler, err := os.Open(fileName)
    handleError(err)

    // close the file after it is no longer required.
    defer func(file *os.File) {
        err = file.Close()
        handleError(err)
    }(fileHandler)

    // delete the local file if required.
    defer func(name string) {
        err = os.Remove(name)
        handleError(err)
    }(fileName)

    accountName, ok := os.LookupEnv("AZURE_STORAGE_ACCOUNT_NAME")
    if !ok {
        panic("AZURE_STORAGE_ACCOUNT_NAME could not be found")
    }
    serviceURL := fmt.Sprintf("https://%s.blob.core.windows.net/", accountName)

    cred, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(serviceURL, cred, nil)
    handleError(err)

    // Upload the file to a block blob
    _, err = client.UploadFile(context.TODO(), "testcontainer", "virtual/dir/path/"+fileName, fileHandler,
        &azblob.UploadFileOptions{
            BlockSize:   int64(1024),
            Concurrency: uint16(3),
            // If Progress is non-nil, this function is called periodically as bytes are uploaded.
            Progress: func(bytesTransferred int64) {
                fmt.Println(bytesTransferred)
            },
        })
    handleError(err)
}

Download blob from a container

DownloadFile downloads a blob from the Azure Storage container that you pass as a parameter to a local file. If the size doesn’t match, the method truncates the destination file.

package main

import (
    "context"
    "fmt"
    "log"
    "os"

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

func handleError(err error) {
    if err != nil {
        log.Fatal(err.Error())
    }
}

func main() {
    // Set up file to download the blob to
    destFileName := "test_download_file.txt"
    destFile, err := os.Create(destFileName)
    handleError(err)
    defer func(destFile *os.File) {
        err = destFile.Close()
        handleError(err)
    }(destFile)

    accountName, ok := os.LookupEnv("AZURE_STORAGE_ACCOUNT_NAME")
    if !ok {
        panic("AZURE_STORAGE_ACCOUNT_NAME could not be found")
    }
    serviceURL := fmt.Sprintf("https://%s.blob.core.windows.net/", accountName)

    cred, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(serviceURL, cred, nil)
    handleError(err)

    // Perform download

    _, err = client.DownloadFile(context.TODO(), "testcontainer", "virtual/dir/path/"+destFileName, destFile,
        &azblob.DownloadFileOptions{
            // If Progress is non-nil, this function is called periodically as bytes are uploaded.
            Progress: func(bytesTransferred int64) {
                fmt.Println(bytesTransferred)
            },
        })

    // Assert download was successful
    handleError(err)
}

Delete blob in a container

DeleteBlob marks the specified blob or snapshot in the Azure Storage container for deletion. Azure deletes the blob later during garbage collection. Deleting a blob also deletes all its snapshots. For more information, see the delete blob documentation.

import (
    "context"
    "fmt"
    "log"
    "os"

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

func handleError(err error) {
    if err != nil {
        log.Fatal(err.Error())
    }
}

func main() {
    accountName, ok := os.LookupEnv("AZURE_STORAGE_ACCOUNT_NAME")
    if !ok {
        panic("AZURE_STORAGE_ACCOUNT_NAME could not be found")
    }
    serviceURL := fmt.Sprintf("https://%s.blob.core.windows.net/", accountName)

    cred, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(serviceURL, cred, nil)
    handleError(err)

    resp, err := client.DeleteBlob(context.TODO(), "testcontainer", "testblob", nil)
    handleError(err)
    fmt.Println(resp)
}

Summary

The Azure Blob Storage for Go library allows users to manipulate blobs and containers in Azure Storage. To learn more, see our documentation. You can also find more examples either on pkg.go.dev or in our GitHub repository.

Feedback

We’d love to hear about your experiences using the Azure SDK for Go. Send us your feedback on our Slack Channel or at the #golang-friends channel on the Microsoft Open Source Discord Server.

For feature requests, bug reports, or general support, open an issue in the Azure SDK for Go repository on GitHub. For more information on how we triage issues, see the Azure SDK GitHub Issue Support Process.

Announcing the stable release of the Azure Blob Storage client library for Go

Install the package

Create a client

Use the `DefaultAzureCredential` token credential (Recommended)

Use Azure Blob Storage connection string

Container operations

Create a container

Delete a container

Blob operations

Upload blob to a container

Download blob from a container

Delete blob in a container

Summary

Feedback

Sandeep Sen Product Manager, Azure SDK

0 comments

Announcing the stable release of the Azure Blob Storage client library for Go

Install the package

Create a client

Use the DefaultAzureCredential token credential (Recommended)

Use Azure Blob Storage connection string

Container operations

Create a container

Delete a container

Blob operations

Upload blob to a container

Download blob from a container

Delete blob in a container

Summary

Feedback

Sandeep Sen Product Manager, Azure SDK

Read next

0 comments

Use the `DefaultAzureCredential` token credential (Recommended)