Споделяне чрез

Get Blob Properties

  • Статия

The Get Blob Properties operation returns all user-defined metadata, standard HTTP properties, and system properties for the blob. It doesn't return the content of the blob.

Request

You can construct the Get Blob Properties request as follows. We recommend that you use HTTPS. Replace myaccount with the name of your storage account.

HEAD method request URI HTTP version
https://myaccount.blob.core.windows.net/mycontainer/myblob

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

https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>		 HTTP/1.1

Emulated storage service URI

When you're making 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 storage account name:

HEAD method request URI HTTP version
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob HTTP/1.1

For more information, see Use the Azure Storage Emulator for development and testing.

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 it's present, specifies the blob snapshot to retrieve. For more information about working with blob snapshots, see Create a snapshot of a blob.
versionid Optional. Version 2019-12-12 and later. The versionid parameter is an opaque DateTime value that, when it's present, specifies the version of the blob to retrieve.
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. Optional for anonymous requests. Specifies the version of the operation to use for this request. For more information, see Versioning for the Azure Storage services.
x-ms-lease-id: <ID> Optional. If this header is specified, the Get Blob Properties operation is performed only if both of the following conditions are met:

- The blob's lease is currently active.
- The lease ID that's specified in the request matches the lease ID of the blob.

If either of these conditions isn't met, the request fails, and the Get Blob Properties operation fails with status code 412 (Precondition Failed).
x-ms-upn Optional. Version 2020-06-12 and later. Valid for accounts with hierarchical namespace enabled. If true, the user identity values that are returned in the x-ms-owner, x-ms-group and x-ms-acl response headers will be transformed from Microsoft Entra object IDs to User Principal Names. If the value is false, they're returned as Microsoft Entra object IDs. The default value is false. Note that group and application object IDs are not translated, because they don't have unique friendly names.
x-ms-client-request-id Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit, which is recorded in the analytics logs when storage analytics logging is enabled. We highly recommend that you use this header when you're correlating client-side activities with requests that are received by the server. For more information, see About Azure Storage Analytics logging.

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

Request headers (customer-provided encryption keys)

As of version 2019-02-02, you can specify the following headers on the request to read a blob that's encrypted 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, you must include these headers on the request so that the read operation can be completed successfully.

Request header Description
x-ms-encryption-key Required. The Base64-encoded AES-256 encryption key.
x-ms-encryption-key-sha256 Optional. 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 200 (OK).

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

Response headers

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

Response header Description
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 operation that modifies the blob, including an update of the blob's metadata or properties, changes the last modified time of the blob.
x-ms-creation-time Version 2017-11-09 and later. The date/time when the blob was created. The date format follows RFC 1123. For more information, see Represent date/time values in headers.
x-ms-meta-name:value A set of name-value pairs that correspond to the user-defined metadata that's associated with this blob.
x-ms-tag-count Version 2019-12-12 and later. If the blob has any tags, returns the number of tags stored on the blob. This header isn't returned if there are no tags on the blob.
x-ms-blob-type:<BlockBlob\|PageBlob\|AppendBlob> The blob type.
x-ms-copy-completion-time:<datetime> Version 2012-02-12 and later. Conclusion time of the last attempted Copy Blob operation where this blob was the destination blob. This value can specify the time of a completed, aborted, or failed copy attempt. This header doesn't appear if a copy is pending, if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a concluded Copy Blob operation that uses Set Blob Properties, Put Blob, or Put Block List.
x-ms-copy-status-description: <error string> Version 2012-02-12 and later. Appears only when x-ms-copy-status is failed or pending. Describes the cause of a fatal or non-fatal copy operation failure. This header doesn't appear if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a concluded Copy Blob operation that uses Set Blob Properties, Put Blob, or Put Block List.
x-ms-copy-id: <id> Version 2012-02-12 and later. The string identifier for the last attempted Copy Blob operation, where this blob was the destination blob. This header doesn't appear if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a concluded Copy Blob operation that uses Set Blob Properties, Put Blob, or Put Block List.
x-ms-copy-progress: <bytes copied/bytes total> Version 2012-02-12 and later. Contains the number of copied bytes and the total bytes in the source in the last attempted Copy Blob operation, where this blob was the destination blob. Can show from 0 to Content-Length copied bytes. This header doesn't appear if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a concluded Copy Blob operation that uses Set Blob Properties, Put Blob, or Put Block List.
x-ms-copy-source: url Version 2012-02-12 and later. A URL up to 2 KiB in length that specifies the source blob that was used in the last attempted Copy Blob operation, where this blob was the destination blob. This header doesn't appear if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a concluded Copy Blob operation that uses Set Blob Properties, Put Blob, or Put Block List.
x-ms-copy-status: <pending \| success \| aborted \| failed> Version 2012-02-12 and later. The state of the copy operation identified by x-ms-copy-id, with these values:

- success: Copy completed successfully.
- pending: Copy is in progress. Check x-ms-copy-status-description if intermittent, non-fatal errors impede copy progress but don’t cause failure.
- aborted: Copy was ended by Abort Copy Blob.
- failed: Copy failed. See x-ms-copy-status-description for failure details.

This header doesn't appear if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a completed Copy Blob operation that uses Set Blob Properties, Put Blob, or Put Block List.
x-ms-incremental-copy: true Version 2016-05-31 and later. Included if the blob is an incremental copy blob.
x-ms-copy-destination-snapshot:<datetime> Version 2016-05-31 and later. Included if the blob is an incremental copy blob or incremental copy snapshot, if x-ms-copy-status is success. Snapshot time of the last successful incremental copy snapshot for this blob.
x-ms-lease-duration: <infinite \| fixed> When a blob is leased, specifies whether the lease is of infinite or fixed duration. Included for requests that use version 2012-02-12 and later.
x-ms-lease-state: <available \| leased \| expired \| breaking \| broken> The lease state of the blob. Included for requests that use version 2012-02-12 and later.
x-ms-lease-status:<locked\| unlocked> The lease status of the blob.
Content-Length The size of the blob in bytes. For a page blob, this header returns the value of the x-ms-blob-content-length header that's stored with the blob.
Content-Type The content type that's specified for the blob. If no content type is specified, the default content type is application/octet-stream.
Etag The ETag contains a value that you can use to perform operations conditionally. For more information, see Specify conditional headers for Blob Storage operations. If the request version is 2011-08-18 or later, the ETag value is enclosed in quotation marks.
Content-MD5 If the Content-MD5 header has been set for the blob, this response header is returned so that the client can check for message content integrity.

In version 2012-02-12 and later, Put Blob sets a block blob’s MD5 value even when the Put Blob request doesn’t include an MD5 header.
Content-Encoding If the Content-Encoding request header has previously been set for the blob, that value is returned in this header.
Content-Language If the Content-Language request header has previously been set for the blob, that value is returned in this header.
Content-Disposition If the Content-Disposition request header has previously been set for the blob, that value is returned in this header, for requests against version 2013-08-15 and later.

The Content-Disposition response header field conveys additional information about how to process the response payload, and also can be used to attach additional metadata. For example, if the header is set to attachment, it indicates that the user-agent should not display the response, but instead show a Save As dialog.
Cache-Control If the Cache-Control request header has previously been set for the blob, that value is returned in this header.
x-ms-blob-sequence-number The current sequence number for a page blob.

This header isn't returned for block blobs or append blobs.

This header isn't returned for block blobs.
x-ms-request-id This header uniquely identifies the request that was made, and you can use it to troubleshoot the request. For more information, see Troubleshoot API Operations.
x-ms-version Indicates the Blob Storage version that's being used to execute the request. This header is returned for requests that are made against version 2009-09-19 and later.

This header is also returned for anonymous requests without a specified version if the container was marked for public access by using Blob Storage version 2009-09-19.
Date A UTC date/time value generated by the service that indicates the time when the response was initiated.
Accept-Ranges: bytes Indicates that the service supports requests for partial blob content. Included for requests made using version 2013-08-15 and later.
x-ms-blob-committed-block-count The number of committed blocks present in the blob. This header is returned only for append blobs.
x-ms-server-encrypted: true/false Version 2015-12-11 and later. The value of this header is set to true if the blob data and application metadata are completely encrypted using the specified algorithm. Otherwise, the value is set to false (when the blob is unencrypted, or if only parts of the blob/application metadata are encrypted).
x-ms-encryption-key-sha256 Version 2019-02-02 and later. This header is returned if the blob is encrypted with a customer-provided key.
x-ms-encryption-context Version 2021-08-06 and later. If the encryption context property value is set it will return the set value. Valid only when Hierarchical Namespace is enabled for the account.
x-ms-encryption-scope Version 2019-02-02 and later. This header is returned if the blob is encrypted with an encryption scope.
x-ms-access-tier Version 2017-04-17 and later. The tier of page blob on a Premium Storage account or tier of a block blob in a Blob Storage or general purpose v2 account. For a list of allowed premium page blob tiers, see High-performance Premium Storage and managed disks for VMs. For blob storage or general purpose v2 account, valid values are Hot, Cool, Cold, and Archive. Note: Cold tier is supported for version 2021-12-02 and later. For detailed information about standard blob account block blob level tiering see Hot, cool and archive storage tiers.
x-ms-access-tier-inferred: true Version 2017-04-17 and later. For page blobs on a Premium Storage account only. If the access tier isn't explicitly set on the blob, the tier is inferred based on its content length, and this header is returned with a value of true. For block blobs on Blob Storage or a general purpose v2 account, if the blob doesn't have the access tier set, you can infer the tier from the storage account properties. This header is set only if the block blob tier is inferred.
x-ms-archive-status Version 2017-04-17 and later. For blob storage or general purpose v2 account, valid values are rehydrate-pending-to-hot, rehydrate-pending-to-cool, and rehydrate-pending-to-cold. If the blob is being rehydrated and is incomplete, this header is returned, which both indicates that the rehydrate is pending and displays the destination tier. For detailed information about standard blob account block blob-level tiering, see Hot, cool, and archive storage tiers.
x-ms-access-tier-change-time Version 2017-04-17 and later. Indicates the last time the tier was changed on the object. This header is returned only if a tier on block blob was ever set. The date format follows RFC 1123. For more information, see Represent date/time values in headers. For more information about standard blob account block blob-level tiering, see Hot, cool, and archive storage tiers.
x-ms-client-request-id Can be used to troubleshoot requests and their 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 is at most 1,024 visible ASCII characters. If the x-ms-client-request-id header isn't present in the request, this header isn't present in the response.
x-ms-rehydrate-priority Version 2019-12-12 and later. If an object is in rehydrate pending state then this header is returned with priority of rehydrate. Valid values are High/Standard. For detailed information about standard blob account block blob level tiering see Hot, cool and archive storage tiers.
x-ms-or-{policy-id}_{rule-id} Version 2019-12-12 and later, returned only for block blobs. policy-id is a GUID value that represents the identifier of an object replication policy on the storage account. rule-id is a GUID value that represents the identifier of a policy rule on the blob container. If the account is ObjectReplication-enabled, the value of this header represents the replication status of blob with the given policy and rule identifiers, either complete or failed.
x-ms-or-policy-id Version 2019-12-12 and later, returned only for block blobs. If the account is ObjectReplication-enabled, the value of this header represents the policy that governs the replication.
x-ms-last-access-time Version 2020-02-10 and later. Indicates the last time when the blob's data was accessed based on the storage account's last access time tracking policy. The header isn't returned if the storage account doesn't have a last access time tracking policy, or the policy is disabled. For information about setting the storage account's last access time tracking policy, see Blob Storage API.
x-ms-blob-sealed Version 2019-12-12 and later, returned only for append blobs. If the append blob has been sealed, the value would be true. For more information, see Append Blob Seal
x-ms-immutability-policy-until-date Version 2020-06-12 and later. Specifies the 'retention until' date set on the blob. This is the date until which the blob can be protected from being modified or deleted. Returned only if an immutability policy is set on the blob. The value of this header is RFC1123 format.
x-ms-immutability-policy-mode: unlocked/locked Version 2020-06-12 and later. The immutability policy mode, returned if an immutability policy is set on the blob. Values are unlocked/locked. unlocked indicates the user may change the policy by increasing or decreasing the retention-until date. locked indicates that these actions are prohibited.
x-ms-legal-hold: true/false Version 2020-06-12 and later. This header isn't returned if there's no legal hold on the blob. The value of this header is set to true if the blob contains a legal hold and its value is true. Otherwise, the value is set to false if the blob contains a legal hold and its value false.
x-ms-owner Version 2020-06-12 and later. Only for accounts with hierarchical namespace enabled. Returns the owner user of the file or directory.
x-ms-group Version 2020-06-12 and later. Only for accounts with hierarchical namespace enabled. Returns the owner group of the file or directory.
x-ms-permissions Version 2020-06-12 and later. Only for accounts with hierarchical namespace enabled. Returns the permissions that are set for user, group, and other on the file or directory. Each individual permission is in [r,w,x,-]{3} format.
x-ms-acl Version 2023-11-03 and later. Only for accounts with hierarchical namespace enabled. Returns the combined list of access and default access control list that are set for user, group and other on the file or directory. Each access control entry (ACE) consists of a scope, a type, a user or group identifier, and permissions in the format [scope]:[type]:[id]:[permissions]. The default scope indicates that the ACE belongs to the default ACL for a directory; otherwise scope is implicit and the ACE belongs to the access ACL. Each individual permission is in [r,w,x,-]{3} format.
x-ms-resource-type Version 2020-10-02 and later. Only for accounts with a hierarchical namespace enabled. Returns the resource type for the path, which can be either file or directory.
x-ms-expiry-time Version 2020-02-10 and later. Only for accounts with a hierarchical namespace enabled. Returns the expiration time that's set on the blob. Is returned only for files that have an expiration time set.

Response body

None.

Sample response

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
x-ms-meta-Name: myblob.txt  
x-ms-meta-DateUploaded: <date>  
x-ms-blob-type: AppendBlob  
x-ms-lease-status: unlocked  
x-ms-lease-state: available  
Content-Length: 11  
Content-Type: text/plain; charset=UTF-8  
Date: <date>  
ETag: "0x8CAE97120C1FF22"  
Accept-Ranges: bytes  
x-ms-blob-committed–block-count: 1  
x-ms-version: 2015-02-21  
Last-Modified: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-copy-id: 36650d67-05c9-4a24-9a7d-a2213e53caf6  
x-ms-copy-source: <url>  
x-ms-copy-status: success  
x-ms-copy-progress: 11/11  
x-ms-copy-completion-time: <date>

Authorization

Authorization is required when calling any data access operation in Azure Storage. You can authorize the Get 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 Get 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

To determine whether a Copy Blob operation has finished, first check to ensure that the x-ms-copy-id header value matches the copy ID that's provided by the original call to Copy Blob. A match ensures that another application didn't abort the copy and start a new Copy Blob operation. Next, check for the x-ms-copy-status: success header. But be aware that all write operations on a blob except Lease, Put Page, and Put Block operations remove all x-ms-copy-* properties from the blob. These properties are also not copied by Copy Blob operations that use earlier versions than 2012-02-12.

x-ms-copy-status-description contains more information about the Copy Blob failure. The x-ms-copy-status-description values are described in the following table:

Component Description
HTTP status code A standard 3-digit integer that specifies the failure.
Error code A keyword that describes the error that's provided by Azure in the <ErrorCode> element. If no <ErrorCode> element appears, a keyword with standard error text that's associated with the 3-digit HTTP status code in the HTTP specification is used. For more information, see Common REST API error codes.
Information Detailed description of the failure, enclosed in quotation marks.

The x-ms-copy-status and x-ms-copy-status-description values of common failure scenarios are described in the following table:

Important

The following error descriptions can change without warning, even without a version change, so the text might not match exactly.

Scenario x-ms-copy-status value x-ms-copy-status-description value
Copy operation completed successfully. success empty
User aborted copy operation before it completed. aborted empty
A failure occurred when reading from the source blob during a copy operation, but the operation will be retried. pending 502 BadGateway "Encountered a retryable error when reading the source. Will retry. Time of failure: <time>"
A failure occurred when writing to the destination blob of a copy operation, but the operation will be retried. pending 500 InternalServerError "Encountered a retryable error. Will retry. Time of failure: <time>"
An unrecoverable failure occurred when reading from the source blob of a copy operation. failed 404 ResourceNotFound "Copy failed when reading the source." Note: When the service reports this underlying error, it returns ResourceNotFound in the <ErrorCode> element. If no <ErrorCode> element appeared in the response, a standard string representation of the HTTP status, such as NotFound, would appear.
The timeout period limiting all copy operations elapsed. (Currently, the timeout period is two weeks.) failed 500 OperationCancelled "The copy exceeded the maximum allowed time."
The copy operation failed too often when reading from the source, and it didn’t meet a minimum ratio of attempts to successes. (This timeout prevents retrying a very poor source over two weeks before failing). failed 500 OperationCancelled "The copy failed when reading the source."

x-ms-last-access-time tracks the time when the blob's data was accessed, based on the storage account's last access time tracking policy. Accessing a blob's metadata doesn't change its last access time.

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

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

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

See also

Authorize requests to Azure Storage
Status and error codes
Blob Storage error codes