Get started with Azure Blob Storage and Go

Article
11/11/2024

This article shows you how to connect to Azure Blob Storage by using the Azure Blob Storage client module for Go. Once connected, use the developer guides to learn how your code can operate on containers, blobs, and features of the Blob Storage service.

If you're looking to start with a complete example, see Quickstart: Azure Blob Storage client library for Go.

API reference documentation | Library source code | Package (pkg.go.dev)

Prerequisites

Azure subscription - create one for trial
Azure storage account - create a storage account
Go 1.18+

Set up your project

This section walks you through preparing a project to work with the Azure Blob Storage client module for Go.

From your GOPATH, 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

Then open your code file and add the necessary import paths. In this example, we add the following to our .go file:

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

Blob client module information:

azblob: Contains the methods that you can use to operate on the service, containers, and blobs.

Authorize access and connect to Blob Storage

To connect an app to Blob Storage, create a client object using azblob.NewClient. This object is your starting point to interact with data resources at the storage account level. You can use it to operate on the storage account and its containers.

To learn more about creating and managing client objects, including best practices, see Create and manage client objects that interact with data resources.

You can authorize a client object using a Microsoft Entra authorization token (recommended), an account access key, or a shared access signature (SAS).

To authorize with Microsoft Entra ID, you need to use a security principal. The following articles provide guidance on different authentication scenarios:

Authorize access using DefaultAzureCredential

An easy and secure way to authorize access and connect to Blob Storage is to obtain an OAuth token by creating a DefaultAzureCredential instance. You can then use that credential to create the client object using azblob.NewClient.

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
}

To use a shared access signature (SAS) token, append the token to the account URL string and create the client object using azblob.NewClientWithNoCredential.

func getServiceClientSAS(accountURL string, sasToken string) *azblob.Client {
    // Create a new service client with an existing SAS token

    // Append the SAS to the account URL with a "?" delimiter
    accountURLWithSAS := fmt.Sprintf("%s?%s", accountURL, sasToken)

    client, err := azblob.NewClientWithNoCredential(accountURLWithSAS, nil)
    handleError(err)

    return client
}

Note

For scenarios where shared access signatures (SAS) are used, Azure recommends using a user delegation SAS. A user delegation SAS is secured with Microsoft Entra credentials instead of the account key. For more information, see Grant limited access to data with shared access signatures (SAS).

To use a storage account shared key, provide the key as a string and initialize a client object using azblob.NewClientWithSharedKeyCredential.

func getServiceClientSharedKey(accountName string, accountKey string) *azblob.Client {
    // Create a new service client with shared key credential
    credential, err := azblob.NewSharedKeyCredential(accountName, accountKey)
    handleError(err)

    accountURL := fmt.Sprintf("https://%s.blob.core.chinacloudapi.cn", accountName)

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

    return client
}

You can also create a client object using a connection string.

func getServiceClientConnectionString(connectionString string) *azblob.Client {
    // Create a new service client with connection string
    client, err := azblob.NewClientFromConnectionString(connectionString, nil)
    handleError(err)

    return client
}

For information about how to obtain account keys and best practice guidelines for properly managing and safeguarding your keys, see Manage storage account access keys.

Important

The account access key should be used with caution. If your account access key is lost or accidentally placed in an insecure location, your service may become vulnerable. Anyone who has the access key is able to authorize requests against the storage account, and effectively has access to all the data. DefaultAzureCredential provides enhanced security features and benefits and is the recommended approach for managing authorization to Azure services.

Build your app

As you build apps to work with data resources in Azure Blob Storage, your code primarily interacts with three resource types: storage accounts, containers, and blobs. To learn more about these resource types, how they relate to one another, and how apps interact with resources, see Understand how apps interact with Blob Storage data resources.

The following guides show you how to access data and perform specific actions using the Azure Blob Storage client module for Go:

Guide	Description
Configure a retry policy	Implement retry policies for client operations.
Copy blobs	Copy a blob from one location to another.
Create a container	Create containers.
Delete and restore blobs	Delete blobs, and if soft-delete is enabled, restore deleted blobs.
Delete and restore containers	Delete containers, and if soft-delete is enabled, restore deleted containers.
Download blobs	Download blobs by using strings, streams, and file paths.
Find blobs using tags	Set and retrieve tags, and use tags to find blobs.
List blobs	List blobs in different ways.
List containers	List containers in an account and the various options available to customize a listing.
Manage properties and metadata (blobs)	Manage container properties and metadata.
Manage properties and metadata (containers)	Manage container properties and metadata.
Upload blobs	Learn how to upload blobs by using strings, streams, file paths, and other methods.