azfile

README

Azure File Storage SDK for Go

Service Version: 2023-11-03

Azure File Shares offers fully managed file shares in the cloud that are accessible via the industry standard Server Message Block (SMB) protocol. Azure file shares can be mounted concurrently by cloud or on-premises deployments of Windows, Linux, and macOS. Additionally, Azure file shares can be cached on Windows Servers with Azure File Sync for fast access near where the data is being used.

Source code | API reference documentation | REST API documentation | Product documentation

Getting started

Install the package

Install the Azure File Storage SDK for Go with go get:

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

If you plan to authenticate with Azure Active Directory (recommended), also install the azidentity module.

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

Prerequisites

A supported Go version (the Azure SDK supports the two most recent Go releases).

You need an Azure subscription and a Storage Account to use this package.

To create a new Storage Account, you can use the Azure Portal, Azure PowerShell, or the Azure CLI. Here's an example using the Azure CLI:

az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS

Authenticate the client

The Azure File Storage SDK for Go allows you to interact with four types of resources: the storage account itself, file shares, directories, and files. Interaction with these resources starts with an instance of a client. To create a client object, you will need the storage account's file service URL and a credential that allows you to access the storage account. The azidentity module makes it easy to add Azure Active Directory support for authenticating Azure SDK clients with their corresponding Azure services.

// create a credential for authenticating with Azure Active Directory
cred, err := azidentity.NewDefaultAzureCredential(nil)
// TODO: handle err

// create service.Client for the specified storage account that uses the above credential
client, err := service.NewClient("https://<my-storage-account-name>.file.core.windows.net/", cred, &service.ClientOptions{FileRequestIntent: to.Ptr(service.ShareTokenIntentBackup)})
// TODO: handle err

Learn more about enabling Azure Active Directory for authentication with Azure Storage: Authorize access to blobs using Azure Active Directory

Other options for authentication include connection strings, shared key, and shared access signatures (SAS). Use the appropriate client constructor function for the authentication mechanism you wish to use.

Key concepts

Azure file shares can be used to:

• Completely replace or supplement traditional on-premises file servers or NAS devices.
• "Lift and shift" applications to the cloud that expect a file share to store file application or user data.
• Simplify new cloud development projects with shared application settings, diagnostic shares, and Dev/Test/Debug tool file shares.

Goroutine safety

We guarantee that all client instance methods are goroutine-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across goroutines.

Additional concepts

Client options | Accessing the response | Handling failures | Logging

Examples

Create a share and upload a file

const (
shareName = "sample-share"
dirName   = "sample-dir"
fileName  = "sample-file"
)

// Get a connection string to our Azure Storage account.  You can
// obtain your connection string from the Azure Portal (click
// Access Keys under Settings in the Portal Storage account blade)
// or using the Azure CLI with:
//
//     az storage account show-connection-string --name <account_name> --resource-group <resource_group>
//
// And you can provide the connection string to your application
// using an environment variable.
connectionString := "<connection_string>"

// Path to the local file to upload
localFilePath := "<path_to_local_file>"

// Get reference to a share and create it
shareClient, err := share.NewClientFromConnectionString(connectionString, shareName, nil)
// TODO: handle error
_, err = shareClient.Create(context.TODO(), nil)
// TODO: handle error

// Get reference to a directory and create it
dirClient := shareClient.NewDirectoryClient(dirName)
_, err = dirClient.Create(context.TODO(), nil)
// TODO: handle error

// open the file for reading
file, err := os.OpenFile(localFilePath, os.O_RDONLY, 0)
// TODO: handle error
defer file.Close()

// get the size of file
fInfo, err := file.Stat()
// TODO: handle error
fSize := fInfo.Size()

// create the file
fClient := dirClient.NewFileClient(fileName)
_, err = fClient.Create(context.TODO(), fSize, nil)
// TODO: handle error

// upload the file
err = fClient.UploadFile(context.TODO(), file, nil)
// TODO: handle error

Download a file

const (
shareName = "sample-share"
dirName   = "sample-dir"
fileName  = "sample-file"
)

connectionString := "<connection_string>"

// Path to the save the downloaded file
localFilePath := "<path_to_local_file>"

// Get reference to the share
shareClient, err := share.NewClientFromConnectionString(connectionString, shareName, nil)
// TODO: handle error

// Get reference to the directory
dirClient := shareClient.NewDirectoryClient(dirName)

// Get reference to the file
fClient := dirClient.NewFileClient(fileName)

// create or open a local file where we can download the Azure File
file, err := os.Create(localFilePath)
// TODO: handle error
defer file.Close()

// Download the file
_, err = fClient.DownloadFile(context.TODO(), file, nil)
// TODO: handle error

Traverse a share

const shareName = "sample-share"

connectionString := "<connection_string>"

// Get reference to the share
shareClient, err := share.NewClientFromConnectionString(connectionString, shareName, nil)
// TODO: handle error

// Track the remaining directories to walk, starting from the root
var dirs []*directory.Client
dirs = append(dirs, shareClient.NewRootDirectoryClient())
for len(dirs) > 0 {
    dirClient := dirs[0]
    dirs = dirs[1:]

    // Get all the next directory's files and subdirectories
    pager := dirClient.NewListFilesAndDirectoriesPager(nil)
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        // TODO: handle error

        for _, d := range resp.Segment.Directories {
            fmt.Println(*d.Name)
            // Keep walking down directories
            dirs = append(dirs, dirClient.NewSubdirectoryClient(*d.Name))
        }

        for _, f := range resp.Segment.Files {
            fmt.Println(*f.Name)
        }
    }
}

Troubleshooting

All File service operations will return an *azcore.ResponseError on failure with a populated ErrorCode field. Many of these errors are recoverable. The fileerror package provides the possible Storage error codes along with various helper facilities for error handling.

const (
	connectionString = "<connection_string>"
	shareName    = "sample-share"
)

// create a client with the provided connection string
client, err := service.NewClientFromConnectionString(connectionString, nil)
// TODO: handle error

// try to delete the share, avoiding any potential race conditions with an in-progress or completed deletion
_, err = client.DeleteShare(context.TODO(), shareName, nil)

if fileerror.HasCode(err, fileerror.ShareBeingDeleted, fileerror.ShareNotFound) {
    // ignore any errors if the share is being deleted or already has been deleted
} else if err != nil {
    // TODO: some other error
}

Next steps

Get started with our File samples. They contain complete examples of the above snippets and more.

Contributing

See the Storage CONTRIBUTING.md for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Documentation

Index

• Constants

Constants

const (
	// EventUpload is used for logging events related to upload operation.
	EventUpload = exported.EventUpload
)