Del via

Get Blob

  • Artikel

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.

Request

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

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:

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.

URI parameters

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.

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

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

Request body

None.

Response

The response includes an HTTP status code, a set of response headers, and the response body, which contains the contents of the blob.

Status code

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.

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

Response body

The response body contains the content of the blob.

Sample response

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

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.

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

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.

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

See also

Authorize requests to Azure Storage
Status and error codes
Blob Storage error codes
Set timeouts for Blob Storage operations