Get Blob
The Get Blob
operation reads or downloads a blob from the system, including its metadata and properties. You can also call Get Blob
to read a snapshot.
You can construct the Get Blob
request as follows. We recommend that you use HTTPS. Replace myaccount with the name of your storage account:
GET 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.0 HTTP/1.1 |
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:
GET method request URI | HTTP version |
---|---|
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob |
HTTP/1.0 HTTP/1.1 |
For more information, see Use the Azure Storage Emulator for development and testing.
The following additional parameters may be specified 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 be retrieved. 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 present, specifies the version of the blob to be retrieved. |
timeout |
Optional. The timeout parameter is expressed in seconds. For more information, see Set timeouts for Blob Storage operations. |
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. If this header is omitted for an anonymous request, then the service executes the request with version 2009-09-19. For more information, see Versioning for the Azure Storage services. |
Range |
Optional. Return the bytes of the blob only in the specified range. |
x-ms-range |
Optional. Return the bytes of the blob only in the specified range. If both Range and x-ms-range are specified, the service uses the value of x-ms-range . If neither range is specified, the entire blob contents are returned. For more information, see Specify the range header for Blob Storage operations. |
x-ms-lease-id: <ID> |
Optional. If this header is specified, the 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 this header is specified but either of these conditions isn't met, the request fails and the Get Blob operation fails with status code 412 (Precondition Failed). |
x-ms-range-get-content-md5: true |
Optional. When this header is set to true and specified together with the Range header, the service returns the MD5 hash for the range, as long as the range is less than or equal to 4 mebibytes (MiB) in size.If the header is specified without the Range header, the service returns status code 400 (Bad Request).If the header is set to true when the range exceeds 4 MiB, the service returns status code 400 (Bad Request). |
x-ms-range-get-content-crc64: true |
Optional. When this header is set to true and specified together with the Range header, the service returns the CRC64 hash for the range, as long as the range is less than or equal to 4 MiB in size.If the header is specified without the Range header, the service returns status code 400 (Bad Request).If the header is set to true when the range exceeds 4 MiB, the service returns status code 400 (Bad Request).If both the x-ms-range-get-content-md5 and x-ms-range-get-content-crc64 headers are present, the request fails with a 400 (Bad Request).This header is supported in versions 2019-02-02 and later. |
Origin |
Optional. Specifies the origin from which the request is issued. The presence of this header results in cross-origin resource sharing (CORS) headers on the response. |
x-ms-upn |
Optional. Version 2023-11-03 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 read the blob only if a specified condition is met. For more information, see Specify conditional headers for Blob Storage operations.
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 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 |
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 . |
None.
The response includes an HTTP status code, a set of response headers, and the response body, which contains the contents of the blob.
A successful operation to read the full blob returns status code 200 (OK).
A successful operation to read a specified range returns status code 206 (Partial Content).
For more information about status codes, see Status and error codes.
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 |
---|---|
Last-Modified |
The date/time when the blob was last modified. The date format follows RFC 1123. 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. |
x-ms-meta-name:value |
A set of name-value pairs that's associated with this blob as user-defined metadata. |
x-ms-tag-count |
Version 2019-12-12 and later. If the blob has any tags, this header returns the number of tags that are stored on the blob. The header isn't returned if there are no tags on the blob. |
Content-Length |
The number of bytes present in the response body. |
Content-Type |
The content type that's specified for the blob. The default content type is application/octet-stream . |
Content-Range |
Indicates the range of bytes that's returned in the event that the client requested a subset of the blob by setting the Range request header. |
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 blob has an MD5 hash and this Get Blob operation is to read the full 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 hash value even when the Put Blob request doesn't include an MD5 header.If the request is to read a specified range and the x-ms-range-get-content-md5 is set to true , the request returns an MD5 hash for the range, as long as the range size is less than or equal to 4 MiB.If neither of these sets of conditions is true , no value is returned for the Content-MD5 header.If x-ms-range-get-content-md5 is specified without the Range header, the service returns status code 400 (Bad Request).If x-ms-range-get-content-md5 is set to true when the range exceeds 4 MiB, the service returns status code 400 (Bad Request). |
x-ms-content-crc64 |
If the request is to read a specified range and the x-ms-range-get-content-crc64 is set to true , the request returns a CRC64 hash for the range, as long as the range size is less than or equal to 4 MiB. If x-ms-range-get-content-crc64 is specified without the Range header, the service returns status code 400 (Bad Request).If x-ms-range-get-content-crc64 is set to true when the range exceeds 4 MiB, the service returns status code 400 (Bad Request). |
Content-Encoding |
Returns the value that was specified for the Content-Encoding request header. |
Content-Language |
Returns the value that was specified for the Content-Language request header. |
Cache-Control |
Returned if the header was previously specified for the blob. |
Content-Disposition |
Returned for requests against version 2013-08-15 and later. This header returns the value that was specified for the x-ms-blob-content-disposition header.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 the header is set to attachment , it indicates that the user-agent should not display the response. Instead, it shows a Save As dialog with a file name other than the specified blob name. |
x-ms-blob-sequence-number |
The current sequence number for a page blob. This header isn't returned for block blobs or append blobs. |
x-ms-blob-type: <BlockBlob | PageBlob | AppendBlob> |
Returns the blob's type. |
x-ms-copy-completion-time: <datetime> |
Version 2012-02-12 and later. The 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 used 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 the last 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 used Set Blob Properties , Put Blob , or Put Block List . |
x-ms-copy-id: <id> |
Version 2012-02-12 and later. A 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 used 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 bytes that were copied and the total bytes in the source in the last attempted Copy Blob operation where this blob was the destination blob. It can show from 0 to Content-Length bytes copied. 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 used Set Blob Properties , Put Blob , or Put Block List . |
x-ms-copy-source: url |
Version 2012-02-12 and later. A URL of up to 2 KiB in length that specifies the source blob or file 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 used Set Blob Properties , Put Blob , or Put Block List . The URL that's returned in this header contains any request parameters that were used in the copy operation on the source blob, including the shared access signature (SAS) token that was used to access the source blob. |
x-ms-copy-status: <pending | success | aborted | failed> |
Version 2012-02-12 and later. The state of the copy operation that's 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 slow copy progress but don't cause failure.- aborted : Copy was ended by Abort Copy Blob .- failed : Copy failed. See the 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 used Set Blob Properties , Put Blob , or Put Block List . |
x-ms-lease-duration: <infinite | fixed> |
Version 2012-02-12 and later. When a blob is leased, specifies whether the lease is of infinite or fixed duration. |
x-ms-lease-state: <available | leased | expired | breaking | broken> |
Version 2012-02-12 and later. The lease state of the blob. |
x-ms-lease-status:<locked | unlocked> |
The current lease status of the blob. |
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. Included for requests that were made by using 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. |
Accept-Ranges: bytes |
Indicates that the service supports requests for partial blob content. Included for requests that are made by using version 2011-08-18 and later, and for the local storage service in SDK version 1.6 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. This header returns the value of the origin request header in case of a match. |
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. |
Vary |
Returned with the value of the Origin header when CORS rules are specified. See CORS support for the Azure Storage services for details. |
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. This header will be set to true . |
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 by using the specified algorithm. Otherwise, the value is set to false (when the blob is unencrypted, or if only parts of the blob or 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-blob-content-md5 |
Version 2016-05-31 and later. If the blob has an MD5 hash, and if the request contains a range header (Range or x-ms-range), this response header is returned with the value of the whole blob's MD5 value. This value might or might not be equal to the value that's returned in the Content-MD5 header, with the latter calculated from the requested range. |
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, this header isn't present in the response. |
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 if the policy is disabled. For information about setting the storage account's last access time tracking policy, see Blob Service 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 that's 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 in RFC1123 format. |
x-ms-immutability-policy-mode: unlocked/locked |
Version 2020-06-12 and later. Returned if an immutability policy is set on the blob. The values are unlocked and locked . unlocked indicates that 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 is 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 is 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 owning 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 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 hierarchical namespace enabled. Returns the resource type for the path, which can be either file or directory . |
The response body contains the content of the blob.
Status Response:
HTTP/1.1 200 OK
Response Headers:
x-ms-blob-type: BlockBlob
x-ms-lease-status: unlocked
x-ms-lease-state: available
x-ms-meta-m1: v1
x-ms-meta-m2: v2
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Date: <date>
ETag: "0x8CB171DBEAD6A6B"
Vary: Origin
Last-Modified: <date>
x-ms-version: 2015-02-21
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 is required when calling any data access operation in Azure Storage. You can authorize the Get 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.
For a page blob, a Get Blob
operation over a range of pages that do not yet have content or that have been cleared returns zeros for those bytes.
If you call Get Blob
on a page blob with no range specified, the service returns the range of pages up to the specified value for the x-ms-blob-content-length
header. For any pages that lack content, the service returns zeros for those bytes.
For an append blob, the Get Blob
operation returns the x-ms-blob-committed-block-count
header. This header indicates the number of committed blocks in the blob. The x-ms-blob-committed-block-count
header isn't returned for block blobs or page blobs.
A Get Blob
operation is allowed two minutes per MiB to be completed. If the operation is taking longer than two minutes per MiB on average, the operation will time out.
The x-ms-version
header is required to retrieve a blob that belongs to a private container. If the blob belongs to a container that' available for full or partial public access, any client can read it without specifying a version; the service version isn't required for retrieving a blob that belongs to a public container. For more information, see Restrict access to containers and blobs.
A Get Blob
operation on an archived block blob will fail.
Copy operations
To determine whether a Copy Blob
operation has been completed, first check to ensure that the x-ms-copy-id
header value of the destination blob matches the copy ID that was 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. However, 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 Blob Storage versions earlier than 2012-02-12.
Warning
The URL that's returned in the x-ms-copy-source
header contains any request parameters that were used in the copy operation on the source blob. If you use a SAS token to access the source blob, that SAS token will appear in the x-ms-copy-source
header when Get Blob
is called on the destination blob.
When x-ms-copy-status: failed
appears in the response, x-ms-copy-status-description
contains more information about the Copy Blob
failure.
The three fields of every x-ms-copy-status-description
value 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, which is provided by Azure in the <ErrorCode> element. If no <ErrorCode> element appears, a keyword that contains standard error text that's associated with the 3-digit HTTP status code in the HTTP specification is used. See Common REST API error codes. |
Information | A 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 error descriptions in this table can change without warning, even without a version change, so they might not match your text 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 , appears. |
The timeout period limiting all copy operations elapsed. (Currently the timeout period is 2 weeks.) | failed | 500 OperationCancelled "The copy exceeded the maximum allowed time." |
The copy operation failed too often when reading from the source, and 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.
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
requests based on the storage account type:
Operation | Storage account type | Billing category |
---|---|---|
Get 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.
Authorize requests to Azure Storage
Status and error codes
Blob Storage error codes
Set timeouts for Blob Storage operations