Set Blob Properties

Article
09/19/2023

The Set Blob Properties operation sets system properties on the blob.

Request

The Set Blob Properties request may be constructed as follows. We recommend that you use HTTPS. Replace myaccount with the name of your storage account:

PUT method request URI	HTTP version
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=properties`	HTTP/1.1

Emulated Storage Service URI

When you're making a request against the emulated storage service, specify the emulator hostname and Blob Storage port as 127.0.0.1:10000, followed by the emulated storage account name:

PUT method request URI	HTTP version
`http://127.0.0.1:10000/ devstoreaccount1/mycontainer/myblob?comp=properties`	HTTP/1.1

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

URI parameters

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

Parameter	Description
`timeout`	Optional. The `timeout` parameter is expressed in seconds. For more information, see Set time-outs for Blob Storage operations.

Request headers (all blob types)

The following table describes required and optional request headers for all blob types.

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-blob-cache-control`	Optional. Modifies the cache control string for the blob. If this property isn't specified on the request, the property is cleared for the blob. Subsequent calls to Get Blob Properties don't return this property, unless it's explicitly set on the blob again.
`x-ms-blob-content-type`	Optional. Sets the blob’s content type. If this property isn't specified on the request, the property is cleared for the blob. Subsequent calls to Get Blob Properties don't return this property, unless it's explicitly set on the blob again.
`x-ms-blob-content-md5`	Optional. Sets the blob's MD5 hash. If this property isn't specified on the request, the property is cleared for the blob. Subsequent calls to Get Blob Properties don't return this property, unless it's explicitly set on the blob again.
`x-ms-blob-content-encoding`	Optional. Sets the blob's content encoding. If this property isn't specified on the request, the property is cleared for the blob. Subsequent calls to Get Blob Properties don't return this property, unless it's explicitly set on the blob again.
`x-ms-blob-content-language`	Optional. Sets the blob's content language. If this property isn't specified on the request, the property is cleared for the blob. Subsequent calls to Get Blob Properties don't return this property, unless it's explicitly set on the blob again.
`x-ms-lease-id:<ID>`	Required if the blob has an active lease. To perform this operation on a blob with an active lease, specify the valid lease ID for this header.
`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.
`x-ms-blob-content-disposition`	Optional. Sets the blob’s `Content-Disposition` header. Available for version 2013-08-15 and later. The `Content-Disposition` response header field conveys additional information about how to process the response payload, and it can be used to attach additional metadata. For example, if it's set to `attachment`, it indicates that the user-agent shouldn't display the response, but instead show a Save As dialog with a file name other than the specified blob name. The response from the Get Blob and Get Blob Properties operations includes the `content-disposition` header.
`Origin`	Optional. Specifies the origin from which the request is issued. The presence of this header results in cross-origin resource sharing headers on the response. For more information, see CORS (cross-origin resource sharing) support for the Azure Storage services.

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

Request headers (page blobs only)

The following table describes request headers that apply only to operations on page blobs:

Request header	Description
`x-ms-blob-content-length: byte value`	Optional. Resizes a page blob to the specified size. If the specified value is less than the current size of the blob, all page blobs with values that are greater than the specified value are cleared. This property can't be used to change the size of a block blob or an append blob. Setting this property for a block blob or an append blob returns status code 400 (Bad Request).
`x-ms-sequence-number-action: {max, update, increment}`	Optional, but required if the `x-ms-blob-sequence-number` header is set for the request. This property applies to page blobs only. This property indicates how the service should modify the blob's sequence number. Specify one of the following options for this property: - `max`: Sets the sequence number to be the higher of the value included with the request and the value currently stored for the blob. - `update`: Sets the sequence number to the value that's included with the request. - `increment`: Increments the value of the sequence number by 1. If you're specifying this option, don't include the `x-ms-blob-sequence-number header`. Doing so returns status code 400 (Bad Request).
`x-ms-blob-sequence-number: <num>`	Optional, but required if the `x-ms-sequence-number-action` property is set to `max` or `update`. This property applies to page blobs only. The property sets the blob's sequence number. The sequence number is a user-controlled property that you can use to track requests and manage concurrency issues. For more information, see the Put Page operation. Use this property together with `x-ms-sequence-number-action` to update the blob's sequence number to either the specified value or the higher of the values specified with the request or currently stored with the blob. This header should not be specified if `x-ms-sequence-number-action` is set to `increment`, in which case the service automatically increments the sequence number by one. To set the sequence number to a value of your choosing, this property must be specified on the request together with `x-ms-sequence-number-action`.

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).

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.

Syntax	Description
`ETag`	Contains a value that you can use to perform operations conditionally. See Specify conditional headers for Blob Storage operations for more information. If the request version is 2011-08-18 or later, the ETag value is enclosed in quotation marks.
`Last-Modified`	The date/time that the blob was last modified. The date format follows RFC 1123. For more information, see Represent date/time values in headers. Any write operation on the blob (including updates on the blob's metadata or properties) changes the last modified time of the blob.
`x-ms-blob-sequence-number`	If the blob is a page blob, the blob's current sequence number is returned with this header.
`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`	Indicates the Blob Storage version that was used to execute the request. This header is returned for requests that were made against version 2009-09-19 and later.
`Date`	A UTC date/time value that's generated by the service, which indicates the time when the response was initiated.
`Access-Control-Allow-Origin`	Returned if the request includes an `Origin` header and CORS is enabled with a matching rule. If there's a match, this header returns the value of the origin request header.
`Access-Control-Expose-Headers`	Returned if the request includes an `Origin` header and CORS is enabled with a matching rule. Returns the list of response headers that are to be exposed to the client or issuer of the request.
`Access-Control-Allow-Credentials`	Returned if the request includes an `Origin` header and CORS is enabled with a matching rule that doesn't allow all origins. The header will be set to `true`.
`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.

Response body

None.

Authorization

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

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, or service principal to call the Set Blob Properties operation, and the least privileged built-in Azure RBAC role that includes this action:

Azure RBAC action: Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
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 Set Blob Properties 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 Set Blob Properties operation using a SAS token delegated to a container or blob resource requires the 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 Set Blob Properties operation using a SAS token delegated to a container or blob resource requires the 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
Set Blob Properties	Blob (b)	Object (o)	Write (w)

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

Remarks

The semantics for updating a blob's properties are as follows:

A page blob's sequence number is updated only if the request meets either of the following conditions:
- The request sets the x-ms-sequence-number-action to max or update, and it specifies a value for the x-ms-blob-sequence-number header.
- The request sets the x-ms-sequence-number-action to increment, which indicates that the service should increment the sequence number by one.
A page blob's size is modified only if the request specifies a value for the x-ms-content-length header.
To change a page blob's size in a premium storage account, the new size must not exceed the content length that's allowed by the existing tier. Call Set Blob Tier before you resize the blob. For a list of tiers and allowed content length, see High-performance premium storage and managed disks for VMs.
If a request sets only x-ms-blob-sequence-number or x-ms-content-length, none of the blob's other properties is modified.
If one or more of the following properties is set in the request, all the properties are set together. If a value isn't provided for a property when at least one of them is set, that property is cleared for the blob.
- x-ms-blob-cache-control
- x-ms-blob-content-type
- x-ms-blob-content-md5
- x-ms-blob-content-encoding
- x-ms-blob-content-language
- x-ms-blob-content-disposition

Note

For a shared access signature (SAS), you can override certain properties stored for the blob by specifying query parameters as part of the shared access signature. These properties include the cache-control, content-type, content-encoding, content-language, and content-disposition properties. For more information, see Create a service SAS.

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 Set Blob Properties requests based on the storage account type:

Operation	Storage account type	Billing category
Set Blob Properties	Premium block blob Standard general-purpose v2	Other operations
Set Blob Properties	Standard general-purpose v1	Write operations

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