Snapshot Blob

The Snapshot Blob operation creates a read-only snapshot of a blob.

Request

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
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=snapshot HTTP/1.1

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
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=snapshot HTTP/1.1

For more information, see Use the Azurite emulator for local Azure Storage development.

URI parameters

You can specify the following additional parameter on the request URI.

Parameter Description
timeout Optional. The timeout parameter is expressed in seconds. For more information, see Setting timeouts for Blob Storage operations.

Request headers

The following table describes required and optional request headers.

Request header Description
Authorization Required. Specifies the authorization scheme, account name, and signature. For more information, see Authorize requests to Azure Storage.
Date or x-ms-date Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authorize requests to Azure Storage.
x-ms-version 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.
x-ms-meta-name:value 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.
If-Modified-Since Optional. A DateTime value. Specify this conditional header to take a snapshot of the blob, only if it has been modified since the specified date/time. If the base blob hasn't been modified, Blob Storage returns status code 412 (Precondition Failed).
If-Unmodified-Since Optional. A DateTime value. Specify this conditional header to take a snapshot of the blob, only if it hasn't been modified since the specified date/time. If the base blob has been modified, Blob Storage returns status code 412 (Precondition Failed).
If-Match Optional. An ETag value. Specify an ETag value for this conditional header to take a snapshot of the blob, only if its ETag value matches the value specified. If the values don't match, Blob Storage returns status code 412 (Precondition Failed).
If-None-Match Optional. An ETag value.

Specify an ETag value for this conditional header to take a snapshot of the blob, only if its ETag value doesn't match the value specified. If the values are identical, Blob Storage returns status code 412 (Precondition Failed).
x-ms-encryption-scope Optional. Indicates the encryption scope to use to encrypt the request contents. This header is supported in version 2019-02-02 and later.
x-ms-lease-id:<ID> 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 Snapshot Blob operation fails with status code 412 (Precondition Failed).
x-ms-client-request-id 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.

Request header Description
x-ms-encryption-key Required. The Base64-encoded AES-256 encryption key.
x-ms-encryption-key-sha256 Required. The Base64-encoded SHA256 hash of the encryption key.
x-ms-encryption-algorithm: AES256 Required. Specifies the algorithm to use for encryption. The value of this header must be AES256.

Request body

None.

Response

The response includes an HTTP status code and a set of response headers.

Status code

A successful operation returns status code 201 (Created). For information about status codes, see Status and error codes.

Response headers

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.

Syntax Description
x-ms-snapshot: <DateTime> Returns a DateTime value that uniquely identifies the snapshot. The value of this header indicates the snapshot version, and you can use it in subsequent requests to access the snapshot. Note that this value is opaque.
ETag The ETag of the snapshot. If the request version is 2011-08-18 or later, the ETag value will be in quotes. Note that a snapshot can't be written to, so the ETag of a particular snapshot never changes. However, the ETag of the snapshot will differ from that of the base blob if new metadata is supplied with the Snaphot Blob request. If no metadata is specified with the request, the ETag of the snapshot will be identical to that of the base blob, at the time the snapshot was taken.
Last-Modified 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 Snaphot Blob request. If no metadata is specified with the request, the last modified time of the snapshot will be identical to that of the base blob, at the time the snapshot was taken.
x-ms-request-id Uniquely identifies the request that was made and can be used for troubleshooting the request. For more information, see Troubleshooting API operations.
x-ms-version 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.
Date A UTC date/time value that indicates the time at which the response was initiated. The service generates this value.
x-ms-request-server-encrypted: true/false Version 2019-02-02 or later. The value of this header is set to true, if the contents of the request are successfully encrypted by using the specified algorithm. Otherwise, the value is set to false.
x-ms-encryption-key-sha256 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.
x-ms-encryption-scope 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.
x-ms-version-id: <DateTime> Version 2019-12-12 and later. Returns an opaque DateTime value that uniquely identifies the blob. The value of this header indicates the version of the blob, and you can use it in subsequent requests to access the blob.
x-ms-client-request-id Can be used to troubleshoot requests and corresponding responses. The value of this header is equal to the value of the x-ms-client-request-id header, if it's present in the request. The value is at most 1,024 visible ASCII characters. If the x-ms-client-request-id header isn't present in the request, it won't be present in the response.

Response body

None.

Authorization

Only the account owner can call this operation.

Remarks

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.

The DateTime value identifies the snapshot on the URI. For example, a base blob and its snapshots have URIs similar to the following:

  • Base blob: http://myaccount.blob.core.windows.net/mycontainer/myblob

  • Snapshot: http://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>

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:

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-Length

  • Cache-Control

  • Content-MD5

  • 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 block list 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:

  • The conditional x-ms-lease-id header 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.

  • The x-ms-lease-id header 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.

Note

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 Blob operation 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 Blob operation 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 Blob returns 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.

See also

Creating a snapshot of a blob

Authorize requests to Azure Storage

Status and error codes

Blob Storage error codes