gocloud.dev: gocloud.dev/blob/azureblob Index | Examples | Files

package azureblob

import "gocloud.dev/blob/azureblob"

Package azureblob provides a blob implementation that uses Azure Storage’s BlockBlob. Use OpenBucket to construct a *blob.Bucket.


For blob.OpenBucket, azureblob registers for the scheme "azblob". The default URL opener will use credentials from the environment variables AZURE_STORAGE_ACCOUNT, AZURE_STORAGE_KEY, and AZURE_STORAGE_SAS_TOKEN. AZURE_STORAGE_ACCOUNT is required, along with one of the other two. To customize the URL opener, or for more details on the URL format, see URLOpener. See https://gocloud.dev/concepts/urls/ for background information.


Go CDK supports all UTF-8 strings; to make this work with providers lacking full UTF-8 support, strings must be escaped (during writes) and unescaped (during reads). The following escapes are performed for azureblob:

- Blob keys: ASCII characters 0-31, 92 ("\"), and 127 are escaped to
  "__0x<hex>__". Additionally, the "/" in "../" and a trailing "/" in a
  key (e.g., "foo/") are escaped in the same way.
- Metadata keys: Per https://docs.microsoft.com/en-us/azure/storage/blobs/storage-properties-metadata,
  Azure only allows C# identifiers as metadata keys. Therefore, characters
  other than "[a-z][A-z][0-9]_" are escaped using "__0x<hex>__". In addition,
  characters "[0-9]" are escaped when they start the string.
  URL encoding would not work since "%" is not valid.
- Metadata values: Escaped using URL encoding.


azureblob exposes the following types for As:

- Bucket: *azblob.ContainerURL
- Error: azblob.StorageError
- ListObject: azblob.BlobItem for objects, azblob.BlobPrefix for "directories"
- ListOptions.BeforeList: *azblob.ListBlobsSegmentOptions
- Reader: azblob.DownloadResponse
- Reader.BeforeRead: *azblob.BlockBlobURL, *azblob.BlobAccessConditions
- Attributes: azblob.BlobGetPropertiesResponse
- CopyOptions.BeforeCopy: azblob.Metadata, *azblob.ModifiedAccessConditions, *azblob.BlobAccessConditions
- WriterOptions.BeforeWrite: *azblob.UploadStreamToBlockBlobOptions


// This example is used in https://gocloud.dev/howto/blob/open-bucket/#azure

// import _ "gocloud.dev/blob/azureblob"

// Variables set up elsewhere:
ctx := context.Background()

// blob.OpenBucket creates a *blob.Bucket from a URL.
// This URL will open the container "my-container" using default
// credentials found in the environment variables
bucket, err := blob.OpenBucket(ctx, "azblob://my-container")
if err != nil {
defer bucket.Close()



Package Files



const Scheme = "azblob"

Scheme is the URL scheme gcsblob registers its URLOpener under on blob.DefaultMux.


var DefaultIdentity = wire.NewSet(
    wire.Bind(new(azblob.Credential), new(azblob.SharedKeyCredential)),

DefaultIdentity is a Wire provider set that provides an Azure storage account name, key, and SharedKeyCredential from environment variables.

var SASTokenIdentity = wire.NewSet(

SASTokenIdentity is a Wire provider set that provides an Azure storage account name, SASToken, and anonymous credential from environment variables.

var Set = wire.NewSet(

Set holds Wire providers for this package.

func NewCredential Uses

func NewCredential(accountName AccountName, accountKey AccountKey) (*azblob.SharedKeyCredential, error)

NewCredential creates a SharedKeyCredential.

func NewPipeline Uses

func NewPipeline(credential azblob.Credential, opts azblob.PipelineOptions) pipeline.Pipeline

NewPipeline creates a Pipeline for making HTTP requests to Azure.

func OpenBucket Uses

func OpenBucket(ctx context.Context, pipeline pipeline.Pipeline, accountName AccountName, containerName string, opts *Options) (*blob.Bucket, error)

OpenBucket returns a *blob.Bucket backed by Azure Storage Account. See the package documentation for an example and https://godoc.org/github.com/Azure/azure-storage-blob-go/azblob for more details.


// This example is used in https://gocloud.dev/howto/blob/open-bucket/#azure-ctor

// Variables set up elsewhere:
ctx := context.Background()

const (
    // Fill in with your Azure Storage Account and Access Key.
    accountName azureblob.AccountName = "my-account"
    accountKey  azureblob.AccountKey  = "my-account-key"
    // Fill in with the storage container to access.
    containerName = "my-container"

// Create a credentials object.
credential, err := azureblob.NewCredential(accountName, accountKey)
if err != nil {

// Create a Pipeline, using whatever PipelineOptions you need.
pipeline := azureblob.NewPipeline(credential, azblob.PipelineOptions{})

// Create a *blob.Bucket.
// The credential Option is required if you're going to use blob.SignedURL.
bucket, err := azureblob.OpenBucket(ctx, pipeline, accountName, containerName,
    &azureblob.Options{Credential: credential})
if err != nil {
defer bucket.Close()


const (
    // Your Azure Storage Account and SASToken.
    accountName = azureblob.AccountName("my-account")
    sasToken    = azureblob.SASToken("my-SAS-token")
    // The storage container to access.
    containerName = "my-container"

// Since we're using a SASToken, we can use anonymous credentials.
credential := azblob.NewAnonymousCredential()

// Create a Pipeline, using whatever PipelineOptions you need.
pipeline := azureblob.NewPipeline(credential, azblob.PipelineOptions{})

// Create a *blob.Bucket.
// Note that we're not supplying azureblob.Options.Credential, so SignedURL
// won't work. To use SignedURL, you need a real credential (see the other
// example).
ctx := context.Background()
b, err := azureblob.OpenBucket(ctx, pipeline, accountName, containerName, &azureblob.Options{SASToken: sasToken})
if err != nil {
defer b.Close()

// Now we can use b to read or write files to the container.
data, err := b.ReadAll(ctx, "my-key")
if err != nil {
_ = data

type AccountKey Uses

type AccountKey string

AccountKey is an Azure storage account key (primary or secondary).

func DefaultAccountKey Uses

func DefaultAccountKey() (AccountKey, error)

DefaultAccountKey loads the Azure storage account key (primary or secondary) from the AZURE_STORAGE_KEY environment variable.

type AccountName Uses

type AccountName string

AccountName is an Azure storage account name.

func DefaultAccountName Uses

func DefaultAccountName() (AccountName, error)

DefaultAccountName loads the Azure storage account name from the AZURE_STORAGE_ACCOUNT environment variable.

type Options Uses

type Options struct {
    // Credential represents the authorizer for SignedURL.
    // Required to use SignedURL.
    Credential *azblob.SharedKeyCredential

    // SASToken can be provided along with anonymous credentials to use
    // delegated privileges.
    // See https://docs.microsoft.com/en-us/azure/storage/common/storage-dotnet-shared-access-signature-part-1#shared-access-signature-parameters.
    SASToken SASToken

Options sets options for constructing a *blob.Bucket backed by Azure Block Blob.

type SASToken Uses

type SASToken string

SASToken is an Azure shared access signature. https://docs.microsoft.com/en-us/azure/storage/common/storage-dotnet-shared-access-signature-part-1

func DefaultSASToken Uses

func DefaultSASToken() (SASToken, error)

DefaultSASToken loads a Azure SAS token from the AZURE_STORAGE_SAS_TOKEN environment variable.

type URLOpener Uses

type URLOpener struct {
    // AccountName must be specified.
    AccountName AccountName

    // Pipeline must be set to a non-nil value.
    Pipeline pipeline.Pipeline

    // Options specifies the options to pass to OpenBucket.
    Options Options

URLOpener opens Azure URLs like "azblob://mybucket".

The URL host is used as the bucket name.

No query parameters are supported.

func (*URLOpener) OpenBucketURL Uses

func (o *URLOpener) OpenBucketURL(ctx context.Context, u *url.URL) (*blob.Bucket, error)

OpenBucketURL opens a blob.Bucket based on u.

Package azureblob imports 21 packages (graph) and is imported by 10 packages. Updated 2019-05-16. Refresh now. Tools for package owners.