azblob
packagemodule
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
README¶
Azure Blob Storage module for Go
Service Version: 2023-11-03
Azure Blob Storage is Microsoft's object storage solution for the cloud. BlobStorage is optimized for storing massive amounts of unstructured data - data that does not adhere to a particular data model ordefinition, such as text or binary data. For more information, seeIntroduction to Azure Blob Storage.
Use the Azure Blob Storage client modulegithub.com/Azure/azure-sdk-for-go/sdk/storage/azblob to:
- Authenticate clients with Azure Blob Storage
- Manipulate containers and blobs in an Azure storage account
Key links:
Source code |API reference documentation |REST API documentation |Product documentation |Samples
Getting started
Prerequisites
- Supported version of Go -Install Go
- Azure subscription -Create a free account
- Azure storage account - To create a storage account, use tools including theAzure portal,Azure PowerShell, or theAzure CLI.Here's an example using the Azure CLI:
az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRSInstall the package
Install the Azure Blob Storage client module for Go withgo get:
go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblobIf you plan to authenticate with Azure Active Directory (recommended), also install theazidentity module.
go get github.com/Azure/azure-sdk-for-go/sdk/azidentityAuthenticate the client
To interact with the Azure Blob Storage service, you'll need to create an instance of theazblob.Client type. Theazidentity 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 Directorycred, err := azidentity.NewDefaultAzureCredential(nil)// TODO: handle err// create an azblob.Client for the specified storage account that uses the above credentialclient, err := azblob.NewClient("https://MYSTORAGEACCOUNT.blob.core.windows.net/", cred, nil)// TODO: handle errLearn more about enabling Azure Active Directory for authentication with Azure Storage:
Other options for authentication include connection strings, shared key, shared access signatures (SAS), and anonymous public access. Use the appropriate client constructor function for the authentication mechanism you wish to use. For examples, see:
Key concepts
Blob Storage is designed for:
- Serving images or documents directly to a browser.
- Storing files for distributed access.
- Streaming video and audio.
- Writing to log files.
- Storing data for backup and restore, disaster recovery, and archiving.
- Storing data for analysis by an on-premises or Azure-hosted service.
Blob Storage offers three types of resources:
- Thestorage account
- One or morecontainers in a storage account
- One or moreblobs in a container
Instances of theazblob.Client type provide methods for manipulating containers and blobs within a storage account.The storage account is specified when theazblob.Client is constructed.
Specialized clients
The Azure Blob Storage client module for Go also provides specialized clients in various subpackages. Use these clients when you need to interact with a specific kind of blob. Learn more aboutblock blobs, append blobs, and page blobs.
Theblob package contains APIs common to all blob types. This includes APIs for deleting and undeleting a blob, setting metadata, and more.
Thelease package contains clients for managing leases on blobs and containers. See theREST API reference for general information on leases.
Thecontainer package contains APIs specific to containers. This includes APIs for setting access policies or properties, and more.
Theservice package contains APIs specific to the Blob service. This includes APIs for manipulating containers, retrieving account information, and more.
Thesas package contains utilities to aid in the creation and manipulation of shared access signature (SAS) tokens.See the package's documentation for more information.
Goroutine safety
We guarantee that all client instance methods are goroutine-safe and independent of each other (seeguideline). This ensures that the recommendation to reuse client instances is always safe, even across goroutines.
Blob metadata
Blob metadata name-value pairs are valid HTTP headers and should adhere to all restrictions governing HTTP headers. Metadata names must be valid HTTP header names, may contain only ASCII characters, and should be treated as case-insensitive. Base64-encode or URL-encode metadata values containing non-ASCII characters.
Additional concepts
Client options |Accessing the response |Handling failures |Logging
Examples
Upload a blob
const (account = "https://MYSTORAGEACCOUNT.blob.core.windows.net/"containerName = "sample-container"blobName = "sample-blob"sampleFile = "path/to/sample/file")// authenticate with Azure Active Directorycred, err := azidentity.NewDefaultAzureCredential(nil)// TODO: handle error// create a client for the specified storage accountclient, err := azblob.NewClient(account, cred, nil)// TODO: handle error// open the file for readingfile, err := os.OpenFile(sampleFile, os.O_RDONLY, 0)// TODO: handle errordefer file.Close()// upload the file to the specified container with the specified blob name_, err = client.UploadFile(context.TODO(), containerName, blobName, file, nil)// TODO: handle errorDownload a blob
// this example accesses a public blob via anonymous access, so no credentials are requiredclient, err := azblob.NewClientWithNoCredential("https://azurestoragesamples.blob.core.windows.net/", nil)// TODO: handle error// create or open a local file where we can download the blobfile, err := os.Create("cloud.jpg")// TODO: handle errordefer file.Close()// download the blob_, err = client.DownloadFile(context.TODO(), "samples", "cloud.jpg", file, nil)// TODO: handle errorEnumerate blobs
const (account = "https://MYSTORAGEACCOUNT.blob.core.windows.net/"containerName = "sample-container")// authenticate with Azure Active Directorycred, err := azidentity.NewDefaultAzureCredential(nil)// TODO: handle error// create a client for the specified storage accountclient, err := azblob.NewClient(account, cred, nil)// TODO: handle error// blob listings are returned across multiple pagespager := client.NewListBlobsFlatPager(containerName, nil)// continue fetching pages until no more remainfor pager.More() { // advance to the next pagepage, err := pager.NextPage(context.TODO())// TODO: handle error// print the blob names for this pagefor _, blob := range page.Segment.BlobItems {fmt.Println(*blob.Name)}}Troubleshooting
All Blob service operations will return an*azcore.ResponseError on failure with apopulatedErrorCode field. Many of these errors are recoverable.Thebloberror package provides the possible Storage error codesalong with helper facilities for error handling.
const (connectionString = "<connection_string>"containerName = "sample-container")// create a client with the provided connection stringclient, err := azblob.NewClientFromConnectionString(connectionString, nil)// TODO: handle error// try to delete the container, avoiding any potential race conditions with an in-progress or completed deletion_, err = client.DeleteContainer(context.TODO(), containerName, nil)if bloberror.HasCode(err, bloberror.ContainerBeingDeleted, bloberror.ContainerNotFound) {// ignore any errors if the container is being deleted or already has been deleted} else if err != nil {// TODO: some other error}Next steps
Get started with ourBlob samples. They contain complete examples of the above snippets and more.
Contributing
See theStorage CONTRIBUTING.md for details on building,testing, and contributing to this library.
This project welcomes contributions and suggestions. Most contributions requireyou to agree to a Contributor License Agreement (CLA) declaring that you havethe right to, and actually do, grant us the rights to use your contribution. Fordetails, visitcla.microsoft.com.
This project has adopted theMicrosoft Open Source Code of Conduct.For more information see theCode of Conduct FAQor contactopencode@microsoft.com with anyadditional questions or comments.
Documentation¶
Overview¶
Example¶
This example is a quick-starter and demonstrates how to get started using the Azure Blob Storage SDK for Go.
package mainimport ("context""fmt""io""log""os""strings""github.com/Azure/azure-sdk-for-go/sdk/azcore/to""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob")func handleError(err error) {if err != nil {log.Fatal(err.Error())}}func main() {// Your account name and key can be obtained from the Azure Portal.accountName, ok := os.LookupEnv("AZURE_STORAGE_ACCOUNT_NAME")if !ok {panic("AZURE_STORAGE_ACCOUNT_NAME could not be found")}accountKey, ok := os.LookupEnv("AZURE_STORAGE_PRIMARY_ACCOUNT_KEY")if !ok {panic("AZURE_STORAGE_PRIMARY_ACCOUNT_KEY could not be found")}cred, err := azblob.NewSharedKeyCredential(accountName, accountKey)handleError(err)// The service URL for blob endpoints is usually in the form: http(s)://<account>.blob.core.windows.net/client, err := azblob.NewClientWithSharedKeyCredential(fmt.Sprintf("https://%s.blob.core.windows.net/", accountName), cred, nil)handleError(err)// ===== 1. Create a container =====containerName := "testcontainer"containerCreateResp, err := client.CreateContainer(context.TODO(), containerName, nil)handleError(err)fmt.Println(containerCreateResp)// ===== 2. Upload and Download a block blob =====blobData := "Hello world!"blobName := "HelloWorld.txt"uploadResp, err := client.UploadStream(context.TODO(),containerName,blobName,strings.NewReader(blobData),&azblob.UploadStreamOptions{Metadata: map[string]*string{"Foo": to.Ptr("Bar")},Tags: map[string]string{"Year": "2022"},})handleError(err)fmt.Println(uploadResp)// Download the blob's contents and ensure that the download worked properlyblobDownloadResponse, err := client.DownloadStream(context.TODO(), containerName, blobName, nil)handleError(err)// Use the bytes.Buffer object to read the downloaded data.// RetryReaderOptions has a lot of in-depth tuning abilities, but for the sake of simplicity, we'll omit those here.reader := blobDownloadResponse.BodydownloadData, err := io.ReadAll(reader)handleError(err)if string(downloadData) != blobData {log.Fatal("Uploaded data should be same as downloaded data")}err = reader.Close()if err != nil {return}// ===== 3. List blobs =====// List methods returns a pager object which can be used to iterate over the results of a paging operation.// To iterate over a page use the NextPage(context.Context) to fetch the next page of results.// PageResponse() can be used to iterate over the results of the specific page.pager := client.NewListBlobsFlatPager(containerName, nil)for pager.More() {resp, err := pager.NextPage(context.TODO())handleError(err)for _, v := range resp.Segment.BlobItems {fmt.Println(*v.Name)}}// Delete the blob._, err = client.DeleteBlob(context.TODO(), containerName, blobName, nil)handleError(err)// Delete the container._, err = client.DeleteContainer(context.TODO(), containerName, nil)handleError(err)}Example (Blob_AccessConditions)¶
This example shows how to perform operations on blob conditionally.
package mainimport ("context""fmt""log""os""strings""time""github.com/Azure/azure-sdk-for-go/sdk/azcore""github.com/Azure/azure-sdk-for-go/sdk/azcore/streaming""github.com/Azure/azure-sdk-for-go/sdk/azcore/to""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/blob""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/blockblob")func handleError(err error) {if err != nil {log.Fatal(err.Error())}}func main() {accountName, accountKey := os.Getenv("AZURE_STORAGE_ACCOUNT_NAME"), os.Getenv("AZURE_STORAGE_ACCOUNT_KEY")credential, err := azblob.NewSharedKeyCredential(accountName, accountKey)handleError(err)blockBlob, err := blockblob.NewClientWithSharedKeyCredential(fmt.Sprintf("https://%s.blob.core.windows.net/mycontainer/Data.txt", accountName), credential, nil)handleError(err)// This function displays the results of an operationshowResult := func(response *blob.DownloadStreamResponse, err error) {if err != nil {log.Fatalf("Failure: %s\n", err.Error())} else {err := response.Body.Close()if err != nil {log.Fatal(err)}// The client must close the response body when finished with itfmt.Printf("Success: %v\n", response)}// Close the responseif err != nil {return}fmt.Printf("Success: %v\n", response)}showResultUpload := func(response blockblob.UploadResponse, err error) {if err != nil {log.Fatalf("Failure: %s\n", err.Error())}fmt.Printf("Success: %v\n", response)}// Create the blobupload, err := blockBlob.Upload(context.TODO(), streaming.NopCloser(strings.NewReader("Text-1")), nil)showResultUpload(upload, err)// Download blob content if the blob has been modified since we uploaded it (fails):downloadResp, err := blockBlob.DownloadStream(context.TODO(),&azblob.DownloadStreamOptions{AccessConditions: &blob.AccessConditions{ModifiedAccessConditions: &blob.ModifiedAccessConditions{IfModifiedSince: upload.LastModified,},},},)showResult(&downloadResp, err)// Download blob content if the blob hasn't been modified in the last 24 hours (fails):downloadResp, err = blockBlob.DownloadStream(context.TODO(),&azblob.DownloadStreamOptions{AccessConditions: &blob.AccessConditions{ModifiedAccessConditions: &blob.ModifiedAccessConditions{IfUnmodifiedSince: to.Ptr(time.Now().UTC().Add(time.Hour * -24))},},},)showResult(&downloadResp, err)// Upload new content if the blob hasn't changed since the version identified by ETag (succeeds):showResultUpload(blockBlob.Upload(context.TODO(),streaming.NopCloser(strings.NewReader("Text-2")),&blockblob.UploadOptions{AccessConditions: &blob.AccessConditions{ModifiedAccessConditions: &blob.ModifiedAccessConditions{IfMatch: upload.ETag},},},))// Download content if it has changed since the version identified by ETag (fails):downloadResp, err = blockBlob.DownloadStream(context.TODO(),&azblob.DownloadStreamOptions{AccessConditions: &blob.AccessConditions{ModifiedAccessConditions: &blob.ModifiedAccessConditions{IfNoneMatch: upload.ETag}},})showResult(&downloadResp, err)// Upload content if the blob doesn't already exist (fails):showResultUpload(blockBlob.Upload(context.TODO(),streaming.NopCloser(strings.NewReader("Text-3")),&blockblob.UploadOptions{AccessConditions: &blob.AccessConditions{ModifiedAccessConditions: &blob.ModifiedAccessConditions{IfNoneMatch: to.Ptr(azcore.ETagAny)},},}))}Example (Blob_Client_Download)¶
This example shows how to download a large stream with intelligent retries. Specifically, ifthe connection fails while reading, continuing to read from this stream initiates a newGetBlob call passing a range that starts from the last byte successfully read before the failure.
package mainimport ("context""fmt""io""log""os""github.com/Azure/azure-sdk-for-go/sdk/azcore/streaming""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/blob")func handleError(err error) {if err != nil {log.Fatal(err.Error())}}func main() {// From the Azure portal, get your Storage account blob service URL endpoint.accountName, accountKey := os.Getenv("AZURE_STORAGE_ACCOUNT_NAME"), os.Getenv("AZURE_STORAGE_ACCOUNT_KEY")// Create a blobClient object to a blob in the container (we assume the container & blob already exist).blobURL := fmt.Sprintf("https://%s.blob.core.windows.net/mycontainer/BigBlob.bin", accountName)credential, err := azblob.NewSharedKeyCredential(accountName, accountKey)handleError(err)blobClient, err := blob.NewClientWithSharedKeyCredential(blobURL, credential, nil)handleError(err)contentLength := int64(0) // Used for progress reporting to report the total number of bytes being downloaded.// Download returns an intelligent retryable stream around a blob; it returns an io.ReadCloser.dr, err := blobClient.DownloadStream(context.TODO(), nil)handleError(err)rs := dr.Body// NewResponseBodyProgress wraps the GetRetryStream with progress reporting; it returns an io.ReadCloser.stream := streaming.NewResponseProgress(rs,func(bytesTransferred int64) {fmt.Printf("Downloaded %d of %d bytes.\n", bytesTransferred, contentLength)},)defer func(stream io.ReadCloser) {err := stream.Close()if err != nil {log.Fatal(err)}}(stream) // The client must close the response body when finished with itfile, err := os.Create("BigFile.bin") // Create the file to hold the downloaded blob contents.handleError(err)defer func(file *os.File) {err := file.Close()if err != nil {}}(file)written, err := io.Copy(file, stream) // Write to the file by reading from the blob (with intelligent retries).handleError(err)fmt.Printf("Wrote %d bytes.\n", written)}Example (Client_CreateContainer)¶
package mainimport ("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)}Example (Client_DeleteBlob)¶
package mainimport ("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)}Example (Client_DeleteContainer)¶
package mainimport ("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)}Example (Client_DownloadFile)¶
package mainimport ("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 todestFileName := "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 successfulhandleError(err)}Example (Client_DownloadStream)¶
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)// Download the blobdownloadResponse, err := client.DownloadStream(ctx, "testcontainer", "test_download_stream.bin", nil)handleError(err)// Assert that the content is correctactualBlobData, err := io.ReadAll(downloadResponse.Body)handleError(err)fmt.Println(len(actualBlobData))Example (Client_NewClient)¶
package mainimport ("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() {// this example uses Azure Active Directory (AAD) to authenticate with Azure Blob StorageaccountName, 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)// https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#DefaultAzureCredentialcred, err := azidentity.NewDefaultAzureCredential(nil)handleError(err)client, err := azblob.NewClient(serviceURL, cred, nil)handleError(err)fmt.Println(client.URL())}Example (Client_NewClientFromConnectionString)¶
package mainimport ("fmt""log""os""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob")func handleError(err error) {if err != nil {log.Fatal(err.Error())}}func main() {// this example uses a connection string to authenticate with Azure Blob StorageconnectionString, ok := os.LookupEnv("AZURE_STORAGE_CONNECTION_STRING")if !ok {log.Fatal("the environment variable 'AZURE_STORAGE_CONNECTION_STRING' could not be found")}serviceClient, err := azblob.NewClientFromConnectionString(connectionString, nil)handleError(err)fmt.Println(serviceClient.URL())}Example (Client_NewClientWithSharedKeyCredential)¶
package mainimport ("fmt""log""os""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob")func handleError(err error) {if err != nil {log.Fatal(err.Error())}}func main() {// this example uses a shared key to authenticate with Azure Blob StorageaccountName, ok := os.LookupEnv("AZURE_STORAGE_ACCOUNT_NAME")if !ok {panic("AZURE_STORAGE_ACCOUNT_NAME could not be found")}accountKey, ok := os.LookupEnv("AZURE_STORAGE_ACCOUNT_KEY")if !ok {panic("AZURE_STORAGE_ACCOUNT_KEY could not be found")}serviceURL := fmt.Sprintf("https://%s.blob.core.windows.net/", accountName)// shared key authentication requires the storage account name and access keycred, err := azblob.NewSharedKeyCredential(accountName, accountKey)handleError(err)serviceClient, err := azblob.NewClientWithSharedKeyCredential(serviceURL, cred, nil)handleError(err)fmt.Println(serviceClient.URL())}Example (Client_NewListBlobsPager)¶
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)pager := client.NewListBlobsFlatPager("testcontainer", &azblob.ListBlobsFlatOptions{Include: container.ListBlobsInclude{Deleted: true, Versions: true},})for pager.More() {resp, err := pager.NextPage(ctx)handleError(err) // if err is not nil, break the loop.for _, _blob := range resp.Segment.BlobItems {fmt.Printf("%v", _blob.Name)}}Example (Client_NewListContainersPager)¶
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)pager := client.NewListContainersPager(&azblob.ListContainersOptions{Include: azblob.ListContainersInclude{Metadata: true, Deleted: true},})for pager.More() {resp, err := pager.NextPage(ctx)handleError(err) // if err is not nil, break the loop.for _, _container := range resp.ContainerItems {fmt.Printf("%v", _container)}}Example (Client_UploadFile)¶
package mainimport ("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 uploadfileSize := 8 * 1024 * 1024fileName := "test_upload_file.txt"fileData := make([]byte, fileSize)err := os.WriteFile(fileName, fileData, 0666)handleError(err)// Open the file to uploadfileHandler, 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)}Example (Client_UploadStream)¶
package mainimport ("bytes""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)// Set up test blobcontainerName := "testcontainer"bufferSize := 8 * 1024 * 1024blobName := "test_upload_stream.bin"blobData := make([]byte, bufferSize)blobContentReader := bytes.NewReader(blobData)// Perform UploadStreamresp, err := client.UploadStream(context.TODO(), containerName, blobName, blobContentReader,&azblob.UploadStreamOptions{Metadata: map[string]*string{"hello": to.Ptr("world")},})// Assert that upload was successfulhandleError(err)fmt.Println(resp)}Example (Client_anonymous_NewClientWithNoCredential)¶
package mainimport ("fmt""log""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob")func handleError(err error) {if err != nil {log.Fatal(err.Error())}}func main() {// this example uses anonymous access to access a public blobserviceClient, err := azblob.NewClientWithNoCredential("https://azurestoragesamples.blob.core.windows.net/samples/cloud.jpg", nil)handleError(err)fmt.Println(serviceClient.URL())}Example (ProgressUploadDownload)¶
package mainimport ("bytes""context""fmt""log""os""strings""github.com/Azure/azure-sdk-for-go/sdk/azcore/streaming""github.com/Azure/azure-sdk-for-go/sdk/azcore/to""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/blob""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/blockblob""github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/container")func handleError(err error) {if err != nil {log.Fatal(err.Error())}}func main() {// Create a credentials object with your Azure Storage Account name and key.accountName, accountKey := os.Getenv("AZURE_STORAGE_ACCOUNT_NAME"), os.Getenv("AZURE_STORAGE_ACCOUNT_KEY")credential, err := azblob.NewSharedKeyCredential(accountName, accountKey)handleError(err)// From the Azure portal, get your Storage account blob service URL endpoint.containerURL := fmt.Sprintf("https://%s.blob.core.windows.net/mycontainer", accountName)// Create an serviceClient object that wraps the service URL and a request pipeline to making requests.containerClient, err := container.NewClientWithSharedKeyCredential(containerURL, credential, nil)handleError(err)// Here's how to create a blob with HTTP headers and metadata (I'm using the same metadata that was put on the container):blobClient := containerClient.NewBlockBlobClient("Data.bin")// requestBody is the stream of data to writerequestBody := streaming.NopCloser(strings.NewReader("Some text to write"))// Wrap the request body in a RequestBodyProgress and pass a callback function for progress reporting.requestProgress := streaming.NewRequestProgress(streaming.NopCloser(requestBody), func(bytesTransferred int64) {fmt.Printf("Wrote %d of %d bytes.", bytesTransferred, requestBody)})_, err = blobClient.Upload(context.TODO(), requestProgress, &blockblob.UploadOptions{HTTPHeaders: &blob.HTTPHeaders{BlobContentType: to.Ptr("text/html; charset=utf-8"),BlobContentDisposition: to.Ptr("attachment"),},})handleError(err)// Here's how to read the blob's data with progress reporting:get, err := blobClient.DownloadStream(context.TODO(), nil)handleError(err)// Wrap the response body in a ResponseBodyProgress and pass a callback function for progress reporting.responseBody := streaming.NewResponseProgress(get.Body,func(bytesTransferred int64) {fmt.Printf("Read %d of %d bytes.", bytesTransferred, *get.ContentLength)},)downloadedData := &bytes.Buffer{}_, err = downloadedData.ReadFrom(responseBody)if err != nil {return}err = responseBody.Close()if err != nil {return}fmt.Printf("Downloaded data: %s\n", downloadedData.String())}Index¶
- Constants
- type AccessConditions
- type CPKInfo
- type CPKScopeInfo
- type Client
- func NewClient(serviceURL string, cred azcore.TokenCredential, options *ClientOptions) (*Client, error)
- func NewClientFromConnectionString(connectionString string, options *ClientOptions) (*Client, error)
- func NewClientWithNoCredential(serviceURL string, options *ClientOptions) (*Client, error)
- func NewClientWithSharedKeyCredential(serviceURL string, cred *SharedKeyCredential, options *ClientOptions) (*Client, error)
- func (c *Client) CreateContainer(ctx context.Context, containerName string, o *CreateContainerOptions) (CreateContainerResponse, error)
- func (c *Client) DeleteBlob(ctx context.Context, containerName string, blobName string, ...) (DeleteBlobResponse, error)
- func (c *Client) DeleteContainer(ctx context.Context, containerName string, o *DeleteContainerOptions) (DeleteContainerResponse, error)
- func (c *Client) DownloadBuffer(ctx context.Context, containerName string, blobName string, buffer []byte, ...) (int64, error)
- func (c *Client) DownloadFile(ctx context.Context, containerName string, blobName string, file *os.File, ...) (int64, error)
- func (c *Client) DownloadStream(ctx context.Context, containerName string, blobName string, ...) (DownloadStreamResponse, error)
- func (c *Client) NewListBlobsFlatPager(containerName string, o *ListBlobsFlatOptions) *runtime.Pager[ListBlobsFlatResponse]
- func (c *Client) NewListContainersPager(o *ListContainersOptions) *runtime.Pager[ListContainersResponse]
- func (c *Client) ServiceClient() *service.Client
- func (c *Client) URL() string
- func (c *Client) UploadBuffer(ctx context.Context, containerName string, blobName string, buffer []byte, ...) (UploadBufferResponse, error)
- func (c *Client) UploadFile(ctx context.Context, containerName string, blobName string, file *os.File, ...) (UploadFileResponse, error)
- func (c *Client) UploadStream(ctx context.Context, containerName string, blobName string, body io.Reader, ...) (UploadStreamResponse, error)
- type ClientOptions
- type CreateContainerOptions
- type CreateContainerResponse
- type DeleteBlobOptions
- type DeleteBlobResponse
- type DeleteContainerOptions
- type DeleteContainerResponse
- type DeleteSnapshotsOptionType
- type DownloadBufferOptions
- type DownloadFileOptions
- type DownloadStreamOptions
- type DownloadStreamResponse
- type HTTPRange
- type ListBlobsFlatOptions
- type ListBlobsFlatResponse
- type ListBlobsFlatSegmentResponse
- type ListBlobsInclude
- type ListContainersInclude
- type ListContainersOptions
- type ListContainersResponse
- type ListContainersSegmentResponse
- type ObjectReplicationPolicy
- type PublicAccessType
- type RetryReaderOptions
- type SharedKeyCredential
- type URLParts
- type UploadBufferOptions
- type UploadBufferResponse
- type UploadFileOptions
- type UploadFileResponse
- type UploadResponse
- type UploadStreamOptions
- type UploadStreamResponse
Examples¶
- Package
- Package (Blob_AccessConditions)
- Package (Blob_Client_Download)
- Package (Client_CreateContainer)
- Package (Client_DeleteBlob)
- Package (Client_DeleteContainer)
- Package (Client_DownloadFile)
- Package (Client_DownloadStream)
- Package (Client_NewClient)
- Package (Client_NewClientFromConnectionString)
- Package (Client_NewClientWithSharedKeyCredential)
- Package (Client_NewListBlobsPager)
- Package (Client_NewListContainersPager)
- Package (Client_UploadFile)
- Package (Client_UploadStream)
- Package (Client_anonymous_NewClientWithNoCredential)
- Package (ProgressUploadDownload)
Constants¶
const (// EventUpload is used for logging events related to upload operation.EventUpload =exported.EventUpload// EventSubmitBatch is used for logging events related to submit blob batch operation.EventSubmitBatch =exported.EventSubmitBatch)
Variables¶
This section is empty.
Functions¶
This section is empty.
Types¶
typeAccessConditions¶added inv0.5.0
type AccessConditions =exported.BlobAccessConditions
AccessConditions identifies blob-specific access conditions which you optionally set.
typeCPKInfo¶added inv1.0.0
CPKInfo contains a group of parameters for client provided encryption key.
typeCPKScopeInfo¶added inv1.0.0
type CPKScopeInfo =container.CPKScopeInfo
CPKScopeInfo contains a group of parameters for the ContainerClient.Create method.
typeClient¶added inv0.5.0
type Client struct {// contains filtered or unexported fields}Client represents a URL to an Azure Storage blob; the blob may be a block blob, append blob, or page blob.
funcNewClient¶added inv0.5.0
func NewClient(serviceURLstring, credazcore.TokenCredential, options *ClientOptions) (*Client,error)
NewClient creates an instance of Client with the specified values.
- serviceURL - the URL of the storage account e.g. https://<account>.blob.core.windows.net/
- cred - an Azure AD credential, typically obtained via the azidentity module
- options - client options; pass nil to accept the default values
funcNewClientFromConnectionString¶added inv0.5.0
func NewClientFromConnectionString(connectionStringstring, options *ClientOptions) (*Client,error)
NewClientFromConnectionString creates an instance of Client with the specified values.
- connectionString - a connection string for the desired storage account
- options - client options; pass nil to accept the default values
funcNewClientWithNoCredential¶added inv0.5.0
func NewClientWithNoCredential(serviceURLstring, options *ClientOptions) (*Client,error)
NewClientWithNoCredential creates an instance of Client with the specified values.This is used to anonymously access a storage account or with a shared access signature (SAS) token.
- serviceURL - the URL of the storage account e.g. https://<account>.blob.core.windows.net/?<sas token>
- options - client options; pass nil to accept the default values
funcNewClientWithSharedKeyCredential¶added inv0.5.0
func NewClientWithSharedKeyCredential(serviceURLstring, cred *SharedKeyCredential, options *ClientOptions) (*Client,error)
NewClientWithSharedKeyCredential creates an instance of Client with the specified values.
- serviceURL - the URL of the storage account e.g. https://<account>.blob.core.windows.net/
- cred - a SharedKeyCredential created with the matching storage account and access key
- options - client options; pass nil to accept the default values
func (*Client)CreateContainer¶added inv0.5.0
func (c *Client) CreateContainer(ctxcontext.Context, containerNamestring, o *CreateContainerOptions) (CreateContainerResponse,error)
CreateContainer is a lifecycle method to creates a new container under the specified account.If the container with the same name already exists, a ContainerAlreadyExists Error will be raised.This method returns a client with which to interact with the newly created container.
func (*Client)DeleteBlob¶added inv0.5.0
func (c *Client) DeleteBlob(ctxcontext.Context, containerNamestring, blobNamestring, o *DeleteBlobOptions) (DeleteBlobResponse,error)
DeleteBlob marks the specified blob or snapshot for deletion. The blob is later deleted during garbage collection.Note that deleting a blob also deletes all its snapshots.For more information, seehttps://docs.microsoft.com/rest/api/storageservices/delete-blob.
func (*Client)DeleteContainer¶added inv0.5.0
func (c *Client) DeleteContainer(ctxcontext.Context, containerNamestring, o *DeleteContainerOptions) (DeleteContainerResponse,error)
DeleteContainer is a lifecycle method that marks the specified container for deletion.The container and any blobs contained within it are later deleted during garbage collection.If the container is not found, a ResourceNotFoundError will be raised.
func (*Client)DownloadBuffer¶added inv0.5.0
func (c *Client) DownloadBuffer(ctxcontext.Context, containerNamestring, blobNamestring, buffer []byte, o *DownloadBufferOptions) (int64,error)
DownloadBuffer downloads an Azure blob to a buffer with parallel.
func (*Client)DownloadFile¶added inv0.5.0
func (c *Client) DownloadFile(ctxcontext.Context, containerNamestring, blobNamestring, file *os.File, o *DownloadFileOptions) (int64,error)
DownloadFile downloads an Azure blob to a local file.The file would be truncated if the size doesn't match.
func (*Client)DownloadStream¶added inv0.5.0
func (c *Client) DownloadStream(ctxcontext.Context, containerNamestring, blobNamestring, o *DownloadStreamOptions) (DownloadStreamResponse,error)
DownloadStream reads a range of bytes from a blob. The response also includes the blob's properties and metadata.For more information, seehttps://docs.microsoft.com/rest/api/storageservices/get-blob.
func (*Client)NewListBlobsFlatPager¶added inv0.5.0
func (c *Client) NewListBlobsFlatPager(containerNamestring, o *ListBlobsFlatOptions) *runtime.Pager[ListBlobsFlatResponse]
NewListBlobsFlatPager returns a pager for blobs starting from the specified Marker. Use an emptyMarker to start enumeration from the beginning. Blob names are returned in lexicographic order.For more information, seehttps://docs.microsoft.com/rest/api/storageservices/list-blobs.
func (*Client)NewListContainersPager¶added inv0.5.0
func (c *Client) NewListContainersPager(o *ListContainersOptions) *runtime.Pager[ListContainersResponse]
NewListContainersPager operation returns a pager of the containers under the specified account.Use an empty Marker to start enumeration from the beginning. Container names are returned in lexicographic order.For more information, seehttps://docs.microsoft.com/rest/api/storageservices/list-containers2.
func (*Client)ServiceClient¶added inv0.6.0
ServiceClient returns the embedded service client for this client.
func (*Client)UploadBuffer¶added inv0.5.0
func (c *Client) UploadBuffer(ctxcontext.Context, containerNamestring, blobNamestring, buffer []byte, o *UploadBufferOptions) (UploadBufferResponse,error)
UploadBuffer uploads a buffer in blocks to a block blob.
func (*Client)UploadFile¶added inv0.5.0
func (c *Client) UploadFile(ctxcontext.Context, containerNamestring, blobNamestring, file *os.File, o *UploadFileOptions) (UploadFileResponse,error)
UploadFile uploads a file in blocks to a block blob.
func (*Client)UploadStream¶added inv0.5.0
func (c *Client) UploadStream(ctxcontext.Context, containerNamestring, blobNamestring, bodyio.Reader, o *UploadStreamOptions) (UploadStreamResponse,error)
UploadStream copies the file held in io.Reader to the Blob at blockBlobClient.A Context deadline or cancellation will cause this to error.
typeClientOptions¶
type ClientOptionsbase.ClientOptions
ClientOptions contains the optional parameters when creating a Client.
typeCreateContainerOptions¶
type CreateContainerOptions =service.CreateContainerOptions
CreateContainerOptions contains the optional parameters for the ContainerClient.Create method.
typeCreateContainerResponse¶added inv0.5.0
type CreateContainerResponse =service.CreateContainerResponse
CreateContainerResponse contains the response from method container.Client.Create.
typeDeleteBlobOptions¶
type DeleteBlobOptions =blob.DeleteOptions
DeleteBlobOptions contains the optional parameters for the Client.Delete method.
typeDeleteBlobResponse¶added inv0.5.0
type DeleteBlobResponse =blob.DeleteResponse
DeleteBlobResponse contains the response from method blob.Client.Delete.
typeDeleteContainerOptions¶
type DeleteContainerOptions =service.DeleteContainerOptions
DeleteContainerOptions contains the optional parameters for the container.Client.Delete method.
typeDeleteContainerResponse¶added inv0.5.0
type DeleteContainerResponse =service.DeleteContainerResponse
DeleteContainerResponse contains the response from method container.Client.Delete
typeDeleteSnapshotsOptionType¶
type DeleteSnapshotsOptionType =generated.DeleteSnapshotsOptionType
DeleteSnapshotsOptionType defines values for DeleteSnapshotsOptionType.
const (DeleteSnapshotsOptionTypeIncludeDeleteSnapshotsOptionType =generated.DeleteSnapshotsOptionTypeIncludeDeleteSnapshotsOptionTypeOnlyDeleteSnapshotsOptionType =generated.DeleteSnapshotsOptionTypeOnly)
funcPossibleDeleteSnapshotsOptionTypeValues¶
func PossibleDeleteSnapshotsOptionTypeValues() []DeleteSnapshotsOptionType
PossibleDeleteSnapshotsOptionTypeValues returns the possible values for the DeleteSnapshotsOptionType const type.
typeDownloadBufferOptions¶added inv0.5.0
type DownloadBufferOptions =blob.DownloadBufferOptions
DownloadBufferOptions identifies options used by the DownloadBuffer and DownloadFile functions.
typeDownloadFileOptions¶added inv0.5.0
type DownloadFileOptions =blob.DownloadFileOptions
DownloadFileOptions identifies options used by the DownloadBuffer and DownloadFile functions.
typeDownloadStreamOptions¶added inv0.5.0
type DownloadStreamOptions =blob.DownloadStreamOptions
DownloadStreamOptions contains the optional parameters for the Client.DownloadStream method.
typeDownloadStreamResponse¶added inv0.5.0
type DownloadStreamResponse =blob.DownloadStreamResponse
DownloadStreamResponse wraps AutoRest generated BlobDownloadResponse and helps to provide info for retry.
typeHTTPRange¶added inv0.5.0
HTTPRange defines a range of bytes within an HTTP resource, starting at offset andending at offset+count. A zero-value HTTPRange indicates the entire resource. An HTTPRangewhich has an offset and zero value count indicates from the offset to the resource's end.
typeListBlobsFlatOptions¶added inv0.5.0
type ListBlobsFlatOptions =container.ListBlobsFlatOptions
ListBlobsFlatOptions contains the optional parameters for the container.Client.ListBlobFlatSegment method.
typeListBlobsFlatResponse¶added inv0.5.0
type ListBlobsFlatResponse =container.ListBlobsFlatResponse
ListBlobsFlatResponse contains the response from method container.Client.ListBlobFlatSegment.
typeListBlobsFlatSegmentResponse¶
type ListBlobsFlatSegmentResponse =generated.ListBlobsFlatSegmentResponse
ListBlobsFlatSegmentResponse - An enumeration of blobs
typeListBlobsInclude¶added inv0.5.0
type ListBlobsInclude =container.ListBlobsInclude
ListBlobsInclude indicates what additional information the service should return with each blob.
typeListContainersInclude¶added inv0.5.0
type ListContainersInclude =service.ListContainersInclude
ListContainersInclude indicates what additional information the service should return with each container.
typeListContainersOptions¶
type ListContainersOptions =service.ListContainersOptions
ListContainersOptions contains the optional parameters for the container.Client.ListContainers operation
typeListContainersResponse¶added inv0.5.0
type ListContainersResponse =service.ListContainersResponse
ListContainersResponse contains the response from method service.Client.ListContainersSegment.
typeListContainersSegmentResponse¶
type ListContainersSegmentResponse =generated.ListContainersSegmentResponse
ListContainersSegmentResponse - An enumeration of containers
typeObjectReplicationPolicy¶
type ObjectReplicationPolicy =blob.ObjectReplicationPolicy
ObjectReplicationPolicy are deserialized attributes
typePublicAccessType¶
type PublicAccessType =generated.PublicAccessType
PublicAccessType defines values for AccessType - private (default) or blob or container.
const (PublicAccessTypeBlobPublicAccessType =generated.PublicAccessTypeBlobPublicAccessTypeContainerPublicAccessType =generated.PublicAccessTypeContainer)
funcPossiblePublicAccessTypeValues¶
func PossiblePublicAccessTypeValues() []PublicAccessType
PossiblePublicAccessTypeValues returns the possible values for the PublicAccessType const type.
typeRetryReaderOptions¶
type RetryReaderOptions =blob.RetryReaderOptions
RetryReaderOptions contains properties which can help to decide when to do retry.
typeSharedKeyCredential¶
type SharedKeyCredential =exported.SharedKeyCredential
SharedKeyCredential contains an account's name and its primary or secondary key.
funcNewSharedKeyCredential¶
func NewSharedKeyCredential(accountName, accountKeystring) (*SharedKeyCredential,error)
NewSharedKeyCredential creates an immutable SharedKeyCredential containing thestorage account's name and either its primary or secondary key.
typeURLParts¶added inv0.5.0
URLParts object represents the components that make up an Azure Storage Container/Blob URL.NOTE: Changing any SAS-related field requires computing a new SAS signature.
typeUploadBufferOptions¶added inv0.5.0
type UploadBufferOptions =blockblob.UploadBufferOptions
UploadBufferOptions provides set of configurations for UploadBuffer operation
typeUploadBufferResponse¶added inv0.5.0
type UploadBufferResponse =blockblob.UploadBufferResponse
UploadBufferResponse contains the response from method Client.UploadBuffer/Client.UploadFile.
typeUploadFileOptions¶added inv0.5.0
type UploadFileOptions =blockblob.UploadFileOptions
UploadFileOptions provides set of configurations for UploadFile operation
typeUploadFileResponse¶added inv0.5.0
type UploadFileResponse =blockblob.UploadFileResponse
UploadFileResponse contains the response from method Client.UploadBuffer/Client.UploadFile.
typeUploadResponse¶added inv0.5.0
type UploadResponse =blockblob.CommitBlockListResponse
UploadResponse contains the response from method blockblob.Client.CommitBlockList.
typeUploadStreamOptions¶added inv0.4.0
type UploadStreamOptions =blockblob.UploadStreamOptions
UploadStreamOptions provides set of configurations for UploadStream operation
typeUploadStreamResponse¶added inv0.5.0
type UploadStreamResponse =blockblob.CommitBlockListResponse
UploadStreamResponse contains the response from method Client.CommitBlockList.
Source Files
Directories