Snapshot Blob operation creates a read-only snapshot of a blob.
You can construct the
Snapshot Blob request as follows. HTTPS is recommended. Replace myaccount with the name of your storage account:
|PUT method request URI||HTTP version|
Emulated storage service URI
When you make a request against the emulated storage service, specify the emulator hostname and Azure Blob Storage port as
127.0.0.1:10000, followed by the emulated account name:
|PUT method request URI||HTTP version|
For more information, see Use the Azurite emulator for local Azure Storage development.
You can specify the following additional parameter on the request URI.
The following table describes required and optional request headers.
||Required. Specifies the authorization scheme, account name, and signature. For more information, see Authorize requests to Azure Storage.|
||Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authorize requests to Azure Storage.|
||Required for all authorized requests. Specifies the version of the operation to use for this request. For more information, see Versioning for the Azure Storage services.|
||Optional. Specifies a user-defined, name-value pair associated with the blob. If you don't specify any name-value pairs, the operation copies the base blob metadata to the snapshot. If you specify one or more name-value pairs, the snapshot is created with the specified metadata, and metadata isn't copied from the base blob.
Note that beginning with version 2009-09-19, metadata names must adhere to the naming rules for C# identifiers. See Naming and referencing containers, blobs, and metadata for more information.
||Optional. Indicates the encryption scope to use to encrypt the request contents. This header is supported in version 2019-02-02 and later.|
||Optional. If you specify this header, the operation is performed only if both of the following conditions are met:
- The blob's lease is currently active.
- The lease ID specified in the request matches that of the blob.
If this header is specified, and either of these conditions aren't met, the request fails. The
||Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Blob Storage.|
This operation also supports the use of conditional headers to run the operation, only if a specified condition is met. For more information, see Specifying conditional headers for Blob Storage operations.
Request headers (customer-provided encryption keys)
Beginning with version 2019-02-02, you can specify the following headers on the request to encrypt a blob with a customer-provided key. Encryption with a customer-provided key (and the corresponding set of headers) is optional. If a blob has previously been encrypted with a customer-provided key, then these headers must be included on the request to complete the read operation successfully.
||Required. The Base64-encoded AES-256 encryption key.|
||Required. The Base64-encoded SHA256 hash of the encryption key.|
||Required. Specifies the algorithm to use for encryption. The value of this header must be
The response includes an HTTP status code and a set of response headers.
A successful operation returns status code 201 (Created). For information about status codes, see Status and error codes.
The response for this operation includes the following headers. The response can also include additional, standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.
||The last modified time of the snapshot. For more information, see Representation of date-time values in headers.
Note that a snapshot can't be written to, so the last modified time of a particular snapshot never changes. However, the last modified time of the snapshot will differ from that of the base blob if new metadata is supplied with the
||Uniquely identifies the request that was made and can be used for troubleshooting the request. For more information, see Troubleshooting API operations.|
||Indicates the version of Blob Storage that was used to run the request. This header is returned for requests made against version 2009-09-19 and later.|
||A UTC date/time value that indicates the time at which the response was initiated. The service generates this value.|
||Version 2019-02-02 or later. The value of this header is set to
||Version 2019-02-02 or later. Returned if the request used a customer-provided key for encryption. The client can ensure that the contents of the request are successfully encrypted by using the provided key.|
||Version 2019-02-02 or later. Returned if the request used an encryption scope. The client can ensure that the contents of the request are successfully encrypted by using the encryption scope.|
||Version 2019-12-12 and later. Returns an opaque
||Can be used to troubleshoot requests and corresponding responses. The value of this header is equal to the value of the
Authorization is required when calling any data access operation in Azure Storage. You can authorize the
Snapshot Blob operation as described below.
Azure Storage supports using Azure Active Directory (Azure AD) to authorize requests to blob data. With Azure AD, you can use Azure role-based access control (Azure RBAC) to grant permissions to a security principal. The security principal may be a user, group, application service principal, or Azure managed identity. The security principal is authenticated by Azure AD to return an OAuth 2.0 token. The token can then be used to authorize a request against the Blob service.
To learn more about authorization using Azure AD, see Authorize access to blobs using Azure Active Directory.
Listed below are the RBAC action necessary for an Azure AD user, group, or service principal to call the
Snapshot Blob operation, and the least privileged built-in Azure RBAC role that includes this action:
- Azure RBAC action: Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write or Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action
- Least privileged built-in role: Storage Blob Data Contributor
To learn more about assigning roles using Azure RBAC, see Assign an Azure role for access to blob data.
Snapshots provide read-only versions of blobs. After you create a snapshot, you can read, copy, or delete it, but you can't modify it.
A snapshot provides a convenient way to back up blob data. You can use a snapshot to restore a blob to an earlier version by calling Copy Blob, to overwrite a base blob with its snapshot.
When you create a snapshot, Blob Storage returns a
DateTime value that uniquely identifies the snapshot relative to its base blob. You can use this value to perform further operations on the snapshot. Note that you should treat this
DateTime value as opaque.
DateTime value identifies the snapshot on the URI. For example, a base blob and its snapshots have URIs similar to the following:
Note that each time you call the
Snapshot Blob operation, you create a new snapshot, with a unique
DateTime value. A blob can support any number of snapshots. Existing snapshots are never overwritten. You delete them explicitly by calling Delete Blob, and setting the
x-ms-include-snapshots header to the appropriate value.
A successful call to
Snapshot Blob returns a
DateTime value in the
x-ms-snapshot response header. You can then use this
DateTime value to perform read, delete, or copy operations on a particular snapshot version. You can call any Blob Storage operation that's valid for a snapshot by specifying
?snapshot=<DateTime> after the blob name.
When you create a snapshot of a blob, the following system properties are copied to the snapshot with the same values:
x-ms-blob-sequence-number(for page blobs only)
x-ms-blob-committed-block-count(for append blobs only)
x-ms-copy-id(version 2012-02-12 and later)
x-ms-copy-status(version 2012-02-12 and later)
x-ms-copy-source(version 2012-02-12 and later)
x-ms-copy-progress(version 2012-02-12 and later)
x-ms-copy-completion-time(version 2012-02-12 and later)
x-ms-copy-status-description(version 2012-02-12 and later)
The base blob's committed blocklist is also copied to the snapshot, if the blob is a block blob. Any uncommitted blocks aren't copied.
The snapshot blob is always the same size as the base blob at the time the snapshot is taken. The value of the
Content-Length header for the snapshot blob will be the same as that for the base blob.
You can specify one or more new metadata values for the snapshot by specifying the
x-ms-meta-name:value header on the request. If this header isn't specified, the metadata associated with the base blob is copied to the snapshot.
Any tags associated with the base blob are copied to the snapshot. It isn't possible to set new tag values for the snapshot.
You can specify conditional headers on the request to take a snapshot of the blob only if a condition is met. If the specified condition isn't met, the snapshot isn't created. The service returns status code 412 (Precondition Failed), along with additional error information about the unmet condition.
If the base blob has an active lease, you can take a snapshot of the blob as long as either of the following conditions are true of the request:
x-ms-lease-idheader is specified, and the active lease ID for the base blob is included in the request. This condition specifies that the snapshot be created only if the lease is active, and the specified lease ID matches that associated with the blob.
x-ms-lease-idheader isn't specified at all, in which case the exclusive-write lease is ignored.
Note that a lease associated with the base blob isn't copied to the snapshot. Snapshots can't be leased.
When you copy a base blob by using the Copy Blob operation, any snapshots of the base blob aren't copied to the destination blob. When a destination blob is overwritten with a copy, any snapshots associated with the destination blob stay intact under its name.
You can copy a snapshot blob over its base blob to restore an earlier version of a blob. The snapshot remains, but the base blob is overwritten with a copy that can be both read and written.
Promoting a snapshot doesn't incur an additional charge for storage resources. This is because blocks or pages are shared between the snapshot and the base blob.
You can set a blob tier on a snapshot, beginning with REST version 2019-12-12. If a tier is set on a root blob, then all snapshots inherit the tier from the base blob. Taking a snapshot on an archived blob will fail. Explicitly setting the tier on an object results in billing for the full size of the object. Taking a snapshot of a blob that has the tier set results in full copy billing of the root blob and the snapshot. For detailed information about block blob level tiering, see Hot, cool, and archive storage tiers.
There are a few differences between Azure Premium Storage accounts and standard storage accounts, in terms of snapshots:
The number of snapshots per page blob in a Premium Storage account is limited to 100. If that limit is exceeded, the
Snapshot Bloboperation returns error code 409 (Snapshot Count Exceeded).
You can take a snapshot of a page blob in a Premium Storage account once every ten minutes. If that rate is exceeded, the
Snapshot Bloboperation returns error code 409 (Snapshot Operation Rate Exceeded).
You can't read a snapshot of a page blob in a Premium Storage account by using Get Blob. In this situation, the service returns error code 400 (Invalid Operation). However, you can call Get Blob Properties and Get Blob Metadata against a snapshot.
To read a snapshot, you can use the Copy Blob operation to copy a snapshot to another page blob in the account. The destination blob for the copy operation must not have any existing snapshots. If the destination blob does have snapshots, then
Copy Blobreturns error code 409 (SnapshotsPresent).
For more information, see Using Blob Storage operations with Azure Premium Storage.
When versioning is enabled, creating a snapshot of a blob also generates a new version and saves the previous version of the base blob. The
x-ms-version-id parameter returns an opaque
DateTime value for the new version of the blob.
Authorize requests to Azure Storage