CloudBlob.GetSharedAccessSignature Method (SharedAccessPolicy, String)

Storage Client Library NET API

[This topic is part of the Microsoft Azure Storage Client Library 1.7, which has been deprecated. See Storage Client Library for the latest version.]

Returns a shared access signature for the blob, with the specified container-level access policy.

Namespace: Microsoft.WindowsAzure.StorageClient
Assembly: Microsoft.WindowsAzure.StorageClient (in Microsoft.WindowsAzure.StorageClient.dll)

Usage

Visual Basic
Dim instance As CloudBlob
Dim policy As SharedAccessPolicy
Dim groupPolicyIdentifier As String
Dim returnValue As String

returnValue = instance.GetSharedAccessSignature(policy, groupPolicyIdentifier)

Syntax

Visual Basic
Public Function GetSharedAccessSignature ( _
	policy As SharedAccessPolicy, _
	groupPolicyIdentifier As String _
) As String
C#
public string GetSharedAccessSignature (
	SharedAccessPolicy policy,
	string groupPolicyIdentifier
)
C++
public:
String^ GetSharedAccessSignature (
	SharedAccessPolicy^ policy, 
	String^ groupPolicyIdentifier
)
J#
JScript

Parameters

policy

Type: Microsoft.WindowsAzure.StorageClient.SharedAccessPolicy

The access policy for the shared access signature.

groupPolicyIdentifier

Type: System.String

A container-level access policy.

Return Value

Type: System.String

A shared access signature.

Example

The following code example creates a shared access signature for a blob. It then uses the signature to create a service client based on the shared access credentials, and uses the client to perform a write operation and a read operation against the blob.

C# Copy Code
static void WriteToBlobViaSAS2(Uri blobEndpoint, string accountName, string accountKey)
{
    // Create a service client for credentialed access to the Blob.
    CloudBlobClient blobClient = new CloudBlobClient(blobEndpoint, new StorageCredentialsAccountAndKey(accountName, accountKey));

    // Create a CloudBlobContainer reference object.
    CloudBlobContainer container = blobClient.GetContainerReference("mySASContainer");

    // Create a new blob container in the cloud if the CloudBlobContainer reference
    // doesn't reference an existing container.
    container.CreateIfNotExist();

    // Create a BlobContainerPermissions dictionary object.
    // This holds a collection of individual SharedAccessPolicy objects.
    BlobContainerPermissions containerPermissions = new BlobContainerPermissions();

    // Create a SharedAccessPolicy object.
    SharedAccessPolicy myCAPolicy = new SharedAccessPolicy();

    // Initialize the SharedAccessPolicy object.
    // Configure the policy to go into effect an hour from now, 
    // to remain in effect for a ten-hour duration,
    // and grant read/write permissions to the data.
    myCAPolicy.SharedAccessStartTime  = DateTime.UtcNow.AddHours(1);
    myCAPolicy.SharedAccessExpiryTime = DateTime.UtcNow.AddHours(11);
    myCAPolicy.Permissions = SharedAccessPermissions.Write | SharedAccessPermissions.Read;

    // Add this SharedAccessPolicy object to the BlobContainerPermissions dictionary.
    containerPermissions.SharedAccessPolicies.Add("myContainerPolicy", myCAPolicy);

    // Restrict anonymous access to the container contents.
    containerPermissions.PublicAccess = BlobContainerPublicAccessType.Off;

    // Apply the collection of shared access policies (in this case, only one policy)
    // to the container.
    container.SetPermissions(containerPermissions);

    // Create a blob reference object.
    CloudBlob blob = blobClient.GetBlobReference("mySASContainer/myBlob.txt");

    // Upload text to the blob.
    // This creates a new blob if the CloudBlob reference doesn’t reference an existing blob.
    blob.UploadText("a text blob");

    // Create a shared access signature to use for delegated access to the blob.
    // Note that this call passes in an empty access policy so that the shared access signature 
    // will use the 'myContainerPolicy' shared access policy defined for the container.
    string signature = blob.GetSharedAccessSignature(new SharedAccessPolicy(), "myContainerPolicy");

    // Use the shared access signature to get another reference to the blob.
    CloudBlob blobSAS = new CloudBlob("http://storagesample.blob.core.windows.net/mySASContainer/myBlob.txt",
                                      new StorageCredentialsSharedAccessSignature(signature));

    // Update the contents of the blob.
    blobSAS.UploadText("A text blob updated using a shared access signature");

    // Output the contents of the blob.
    Console.WriteLine(blobSAS.DownloadText());
}

Exceptions

Exception typeCondition
InvalidOperationException

Thrown if the current credentials don't support creating a shared access signature.

NotSupportedException

Thrown if blob is a snapshot.

Remarks

A shared access signature is a token that provides delegated access to blob resources. You can provide this token to clients in order to grant them specific permissions to resources for a controlled period of time. A shared access signature created for a blob resource can grant access just to the content and metadata of that blob.

A shared access signature created for a container resource can grant access to the content and metadata of any blob in the container, and to the list of blobs in the container. To create a shared access signature for a container, see the GetSharedAccessSignature method of the CloudBlobContainer object.

The parameters of the shared access signature that govern access are:

  • The start time at which the signature becomes valid.

  • The time at which it expires.

  • The permissions that it grants.

These parameters are specified in an access policy, represented by the SharedAccessPolicy class. There are three ways to specify an access policy:

  • You can specify it on a single shared access signature. In this case, the interval over which the signature may be valid is limited to one hour.

  • You can specify it by creating a container-level access policy, which can be associated with one or more shared access signatures. This approach has the advantage of making it possible to revoke a shared access signature, if it should be compromised. To specify that the access policy should be used by the signature, call the overload that includes the groupPolicyIdentifier parameter.

  • You can also specify some parameters of the access policy on the signature and some on a container-level access policy. Note that you cannot specify the same parameter in both places; doing so results in an error (HTTPStatusCode.BadRequest).

Note that when you regenerate your account key, any shared access signature generated using the original key is no longer valid.

For more information on shared access signatures, see Creating a Shared Access Signature. For details on container-level access policies, see Specifying a Container-Level Access Policy.


Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Development Platforms

Windows Vista, Windows 7, Windows Server 2008, Windows 8.1, Windows Server 2012 R2, Windows 8 and Windows Server 2012

Change History

See Also