Set Blob Tier

The Set Blob Tier operation sets the access tier on a blob. The operation is allowed on a page blob in a premium storage account and on a block blob in a blob storage or general purpose v2 account. A premium page blob's tier (P1, P2, P3, P4, and so on) determines the allowed size, input/output operations per second (IOPS), and bandwidth of the blob. A block blob's tier determines the Hot, Cool, Cold, or Archive storage type. This operation doesn't update the blob's ETag.

Note

The Cold tier is currently in preview.

For detailed information about block blob-level tiering, see Hot, cool, and archive storage tiers.

Request

You can construct the Set Blob Tier request as follows. We recommend that you use HTTPS. Replace myaccount with the name of your storage account, and replace myblob with the blob name for which the tier is to be changed.

Method Request URI HTTP version
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=tier HTTP/1.1

URI parameters

You can specify the following additional parameters on the request URI:

Parameter Description
snapshot Optional. The snapshot parameter is an opaque DateTime value that, when present, specifies the blob snapshot to set a tier on. For more information about working with blob snapshots, see Create a snapshot of a blob
versionid Optional for version 2019-12-12 and later. The versionid parameter is an opaque DateTime value that, when present, specifies the version of the blob to set a tier on.
timeout Optional. The timeout parameter is expressed in seconds. For more information, see Set time-outs for Blob Storage operations.

Request headers

The required and optional request headers are described in the following table:

Request header Description
Authorization Required. Specifies the authorization scheme, storage 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-access-tier Required. Indicates the tier to be set on the blob. For a list of allowed premium page blob tiers, see High-performance premium storage and managed disks for virtual machines (VMs). For a blob storage or general purpose v2 account, valid values are Hot, Cool, Cold, or archive. Note: The Cold tier is currently in preview and supported for version 2021-12-02 and later. For detailed information about standard blob account blob-level tiering see Hot, cool, and archive storage tiers.
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-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 enabled. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see About Storage Analytics logging.
x-ms-rehydrate-priority Optional. Indicates the priority with which to rehydrate an archived blob. Supported on version 2019-02-02 and later for block blobs. Valid values are High or Standard. The priority can be set on a blob only once for versions earlier than 2020-06-12; this header is ignored on subsequent requests. The default priority setting is Standard.

As of version 2020-06-12, you can update the rehydration priority after it has been set. You can change the priority setting from Standard to High by calling Set Blob Tier, with this header set to High and by setting x-ms-access-tier to the same value to which it was previously set. The priority setting can't be lowered from High to Standard.

This operation also supports the use of conditional headers to tier the blob only if a specified condition is met. For more information, see Specify conditional headers for Blob Storage operations.

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 200 (OK) if the new tier takes effect immediately, or status code 202 (Accepted) if the transition to the new tier is pending.

For premium storage accounts, the page blob operation returns status code 200 (OK).

For block blobs, the HTTP status codes that are returned, based on the current and requested tiers of the blob, are described in the following table:

Tier Set to hot tier Set to cool tier Set to cold tier Set to archive tier
Blob in hot tier 200 200 200 200
Blob in cool tier 200 200 200 200
Blob in cold tier 200 200 200 200
Blob in archive tier 202 202 202 200
Blob in archive tier, rehydrating to hot 202 409 409 409
Blob in archive tier, rehydrating to cool 409 202 409 409
Blob in archive tier, rehydrating to cold 409 409 202 409

For more information about status codes, see Status and error codes.

Response headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response header Description
x-ms-request-id Uniquely identifies the request that was made and can be used to troubleshoot the request. For more information, see Troubleshoot API operations.
x-ms-version The Blob Storage version that was used to execute the request. This header is returned for requests made against version 2009-09-19 and later.
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 and the value contains no more than 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.

Authorization

This operation can be called only by the storage account owner and by anyone with a shared access signature with permissions to write to this blob or its container.

Remarks

Setting a blob's tier for page blobs in premium accounts has the following restrictions:

Setting the block blob's tier on a Blob Storage or general purpose v2 account has the following restrictions:

  • Setting a tier on a snapshot is allowed as of REST version 2019-12-12.
  • Snapshots that are tiered to archive can't be rehydrated back into the snapshot. That is, the snapshot can't be brought back to a hot or cool tier. The only way to retrieve the data from an archive snapshot or version is to copy it to a new blob.
  • If the version is a root blob, it can be rehydrated back to hot or cool.
  • Snapshots or versions in an archive state aren't allowed to be promoted to root.
  • When versioning is enabled, the deletion of a root blob when it's in a rehydrate-pending state will result in the cancellation of the rehydration, and the version will be in an archive state.
  • If a blob is overwritten when it's in a rehydrate-pending and soft-deleted state, it will result in the cancellation of the rehydration, and the version of the soft-deleted snapshot will be in an archive state.

The list of supported tiers isn't restricted by the request version, and new tiers can be added in the future.

Note

For detailed information about block blob level tiering see Hot, cool, and archive storage tiers.

See also

Authorize requests to Azure Storage
Status and error codes
Blob Storage error codes
Set time-outs for Blob Storage operations