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.

NOTE: SignedURLs for PUT created with this package are not fully portable; they will not work unless the PUT request includes a "x-ms-blob-type" header set to "BlockBlob". See https://stackoverflow.com/questions/37824136/put-on-sas-blob-url-without-specifying-x-ms-blob-type-header.

URLs

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.

Escaping

Go CDK supports all UTF-8 strings; to make this work with services 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.

As

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

Code:

// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
// PRAGMA: On gocloud.dev, add a blank import: _ "gocloud.dev/blob/azureblob"
// PRAGMA: On gocloud.dev, hide lines until the next blank line.
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
// AZURE_STORAGE_ACCOUNT plus at least one of AZURE_STORAGE_KEY
// and AZURE_STORAGE_SAS_TOKEN.
bucket, err := blob.OpenBucket(ctx, "azblob://my-container")
if err != nil {
    log.Fatal(err)
}
defer bucket.Close()

Index

Examples

Package Files

azureblob.go

Constants

const Scheme = "azblob"

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

Variables

var DefaultIdentity = wire.NewSet(
    DefaultAccountName,
    DefaultAccountKey,
    NewCredential,
    wire.Bind(new(azblob.Credential), new(*azblob.SharedKeyCredential)),
    wire.Value(azblob.PipelineOptions{}),
)

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

var SASTokenIdentity = wire.NewSet(
    DefaultAccountName,
    DefaultSASToken,
    azblob.NewAnonymousCredential,
    wire.Value(azblob.PipelineOptions{}),
)

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

var Set = wire.NewSet(
    NewPipeline,
    wire.Struct(new(Options), "Credential", "SASToken"),
    wire.Struct(new(URLOpener), "AccountName", "Pipeline", "Options"),
)

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.

Code:

// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
// PRAGMA: On gocloud.dev, hide lines until the next blank line.
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 {
    log.Fatal(err)
}

// 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 {
    log.Fatal(err)
}
defer bucket.Close()

Code:

const (
    // Your Azure Storage Account.
    accountName = azureblob.AccountName("my-account")

    // Your Azure AAD Service Principal with access to the storage account.
    // https://docs.microsoft.com/en-us/azure/storage/common/storage-auth-aad-app
    clientID     = "123"
    clientSecret = "456"
    tenantID     = "789"

    // The storage container to access.
    containerName = "my-container"
)

// Get an Oauth2 token for the account for use with Azure Storage.
ccc := auth.NewClientCredentialsConfig(clientID, clientSecret, tenantID)

// Set the target resource to the Azure storage. This is available as a
// constant using "azure.PublicCloud.ResourceIdentifiers.Storage".
ccc.Resource = "https://storage.azure.com/"
token, err := ccc.ServicePrincipalToken()
if err != nil {
    log.Fatal(err)
}

// Refresh OAuth2 token.
if err := token.RefreshWithContext(context.Background()); err != nil {
    log.Fatal(err)
}

// Create the credential using the OAuth2 token.
credential := azblob.NewTokenCredential(token.OAuthToken(), nil)

// 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, new(azureblob.Options))
if err != nil {
    log.Fatal(err)
}
defer b.Close()

Code:

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 {
    log.Fatal(err)
}
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 {
    log.Fatal(err)
}
_ = 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.StorageAccountCredential

    // 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 20 packages. Updated 2019-10-02. Refresh now. Tools for package owners.