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/azidentityWe 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
TokenCredentialtype 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.
0 comments