Κοινή χρήση μέσω

Set Blob Properties

  • Άρθρο

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.

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

To learn more about assigning roles using Azure RBAC, see Assign an Azure role for access to blob data.

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.

See also