Snapshot Blob

Artikkeli
11/07/2023

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

Authorization is required when calling any data access operation in Azure Storage. You can authorize the Snapshot Blob operation as described below.

Important

Microsoft recommends using Microsoft Entra ID with managed identities to authorize requests to Azure Storage. Microsoft Entra ID provides superior security and ease of use compared to Shared Key authorization.

Azure Storage supports using Microsoft Entra ID to authorize requests to blob data. With Microsoft Entra ID, 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 Microsoft Entra ID 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 Microsoft Entra ID, see Authorize access to blobs using Microsoft Entra ID.

Permissions

Listed below are the RBAC action necessary for a Microsoft Entra user, group, managed identity, 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.

A shared access signature (SAS) provides secure delegated access to resources in a storage account. With a SAS, you have granular control over how a client can access data. You can specify what resource the client may access, what permissions they have to those resources, and how long the SAS is valid.

The Snapshot Blob operation supports three types of shared access signatures: user delegation SAS, service SAS, and account SAS.

As a security best practice, we recommend that you use Microsoft Entra credentials rather than the storage account key, which can be more easily compromised. If your application design requires shared access signatures, use Microsoft Entra credentials to create a user delegation SAS, when possible.

When Shared Key access is disallowed for the storage account, a service SAS token or an account SAS token will not be permitted on a request to Blob Storage. To learn more, see Understand how disallowing Shared Key affects SAS tokens.

User delegation SAS

A user delegation SAS is secured with Microsoft Entra credentials and also by the permissions specified for the SAS.

Calling the Snapshot Blob operation using a SAS token delegated to a container or blob resource requires the Create (c) or Write (w) permission as part of the user delegation SAS token.

To learn more about the user delegation SAS, see Create a user delegation SAS.

Service SAS

A service SAS is secured with the storage account key. A service SAS delegates access to a resource in a single Azure Storage service, such as blob storage.

Calling the Snapshot Blob operation using a SAS token delegated to a container or blob resource requires the Create (c) or Write (w) permission as part of the service SAS token.

To learn more about the service SAS, see Create a service SAS.

Account SAS

An account SAS is secured with the storage account key. An account SAS delegates access to resources in one or more of the storage services. All of the operations available via a service or user delegation SAS are also available via an account SAS.

The following table indicates the signed resource type and signed permissions to specify when delegating access:

Operation	Signed service	Signed resource type	Signed permission
Snapshot Blob	Blob (b)	Object (o)	Create (c) or Write (w)

To learn more about the account SAS, see Create an account SAS.

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 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:

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.

Billing

Pricing requests can originate from clients that use Blob Storage APIs, either directly through the Blob Storage REST API, or from an Azure Storage client library. These requests accrue charges per transaction. The type of transaction affects how the account is charged. For example, read transactions accrue to a different billing category than write transactions. The following table shows the billing category for Snapshot Blob requests based on the storage account type:

Operation	Storage account type	Billing category
Snapshot Blob	Premium block blob Standard general-purpose v2 Standard general-purpose v1	Read operations

To learn about pricing for the specified billing category, see Azure Blob Storage Pricing.

Jaa