Use blob index tags to manage and find data with Go
This article shows how to use blob index tags to manage and find data using the Azure Storage client module for Go.
Prerequisites
- Azure subscription - create one for trial
- Azure storage account - create a storage account
- Go 1.18+
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 work with blob index tags. For authorization with Microsoft Entra ID (recommended), you need Azure RBAC built-in role Storage Blob Data Owner or higher. To learn more, see the authorization guidance for Get Blob Tags, Set Blob Tags, or Find Blobs by Tags.
About blob index tags
Blob index tags categorize data in your storage account using key-value tag attributes. These tags are automatically indexed and exposed as a searchable multi-dimensional index to easily find data. This article shows you how to set, get, and find data using blob index tags.
Blob index tags aren't supported for storage accounts with hierarchical namespace enabled. To learn more about the blob index tag feature along with known issues and limitations, see Manage and find Azure Blob data with blob index tags.
Set tags
You can set index tags if your code has authorized access to blob data through one of the following mechanisms:
- Security principal that is assigned an Azure RBAC role with the Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/write action. The Storage Blob Data Owner is a built-in role that includes this action.
- Shared Access Signature (SAS) with permission to access the blob's tags (
t
permission) - Account key
For more information, see Setting blob index tags.
You can set tags by using the following method:
The tags specified in this method replace any existing tags. If existing values must be preserved, they must be downloaded and included in the call to this method. The following example shows how to set tags:
func setBlobTags(client *azblob.Client, containerName string, blobName string) {
// Reference the blob as a client object
blobClient := client.ServiceClient().NewContainerClient(containerName).NewBlobClient(blobName)
// Get existing tags for the blob if they need to be preserved
resp, err := blobClient.GetTags(context.TODO(), nil)
handleError(err)
tags := make(map[string]string)
for _, v := range resp.BlobTags.BlobTagSet {
tags[*v.Key] = *v.Value
}
// Add or modify blob tags
var updated_tags = make(map[string]*string)
updated_tags["tag1"] = to.Ptr("value1")
updated_tags["tag2"] = to.Ptr("value2")
// Combine existing tags with new tags
for k, v := range updated_tags {
tags[k] = *v
}
// Set blob tags
_, err = blobClient.SetTags(context.TODO(), tags, nil)
handleError(err)
}
You can remove all tags by calling SetTags
with no tags, as shown in the following example:
func clearBlobTags(client *azblob.Client, containerName string, blobName string) {
// Reference the blob as a client object
blobClient := client.ServiceClient().NewContainerClient(containerName).NewBlobClient(blobName)
// Clear blob tags
_, err := blobClient.SetTags(context.TODO(), make(map[string]string), nil)
handleError(err)
}
Get tags
You can get index tags if your code has authorized access to blob data through one of the following mechanisms:
- Security principal that is assigned an Azure RBAC role with the Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/read action. The Storage Blob Data Owner is a built-in role that includes this action.
- Shared Access Signature (SAS) with permission to access the blob's tags (
t
permission) - Account key
For more information, see Getting and listing blob index tags.
You can get tags by using the following method:
The following example shows how to retrieve and iterate over the blob's tags:
func getBlobTags(client *azblob.Client, containerName string, blobName string) {
// Reference the blob as a client object
blobClient := client.ServiceClient().NewContainerClient(containerName).NewBlobClient(blobName)
// Get the blob tags
resp, err := blobClient.GetTags(context.TODO(), nil)
handleError(err)
// Print the blob tags
for _, v := range resp.BlobTags.BlobTagSet {
fmt.Printf("Key: %v, Value: %v\n", *v.Key, *v.Value)
}
}
Filter and find data with blob index tags
You can use index tags to find and filter data if your code has authorized access to blob data through one of the following mechanisms:
- Security principal that is assigned an Azure RBAC role with the Microsoft.Storage/storageAccounts/blobServices/containers/blobs/filter/action action. The Storage Blob Data Owner is a built-in role that includes this action.
- Shared Access Signature (SAS) with permission to filter blobs by tags (
f
permission) - Account key
For more information, see Finding data using blob index tags.
Note
You can't use index tags to retrieve previous versions. Tags for previous versions aren't passed to the blob index engine. For more information, see Conditions and known issues.
You can filter blob data based on index tags by using the following method:
The following example finds and lists all blobs tagged as an image:
func findBlobsByTags(client *azblob.Client, containerName string, blobName string) {
// Reference the container as a client object
containerClient := client.ServiceClient().NewContainerClient(containerName)
// Filter blobs by tags
where := "\"Content\"='image'"
opts := container.FilterBlobsOptions{MaxResults: to.Ptr(int32(10))}
resp, err := containerClient.FilterBlobs(context.TODO(), where, &opts)
handleError(err)
// Print the blobs found
for _, blobItem := range resp.FilterBlobSegment.Blobs {
fmt.Printf("Blob name: %v\n", *blobItem.Name)
}
}
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 use index tags to manage and find data using the Azure Blob Storage client library for Go, see the following resources.
Code samples
- View code samples from this article (GitHub)
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 managing and using blob index tags use the following REST API operations:
- Get Blob Tags (REST API)
- Set Blob Tags (REST API)
- Find Blobs by Tags (REST API)
Client module resources
See also
- Manage and find Azure Blob data with blob index tags
- Use blob index tags to manage and find data on Azure Blob Storage
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.