你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

获取 Blob

Get Blob 操作从系统读取或下载 Blob,包括其元数据和属性。 也可以调用Get Blob 读取快照。

请求

可以按如下方式构建Get Blob请求。 建议使用 HTTPS。 将 myaccount 替换为存储帐户的名称:

GET 方法请求 URI HTTP 版本
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

模拟存储服务 URI

在针对模拟的存储服务发出请求时,请将模拟器主机名和 BLOB 服务端口指定为 127.0.0.1:10000,后跟模拟的存储帐户名称:

GET 方法请求 URI HTTP 版本
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob HTTP/1.0

HTTP/1.1

有关详细信息,请参阅Using the Azure 存储 Emulator for Development and Testing

URI 参数

可以在请求 URI 上指定以下附加参数。

参数 说明
snapshot 可选。 snapshot 参数是一个不透明的 DateTime 值;如果存在,则指定要检索的 Blob 快照。 有关使用 Blob 快照的信息,请参阅 创建 Blob 的快照
versionid 可选,版本 2019-12-12 及更高版本。 versionid 参数是一个不透明值,当存在该值时,该值指定要 DateTime 检索的 Blob 的版本。
timeout 可选。 timeout 参数以秒表示。 有关详细信息,请参阅为 Blob 服务操作设置超时

请求标头

下表介绍必需的和可选的请求标头。

请求标头 说明
Authorization 必需。 指定授权方案、帐户名称和签名。 有关详细信息,请参阅授权请求Azure 存储。
Datex-ms-date 必需。 指定请求的协调世界时 (UTC)。 有关详细信息,请参阅授权请求Azure 存储。
x-ms-version 对于所有授权请求是必需的,对于匿名请求是可选的。 指定用于此请求的操作的版本。 有关详细信息,请参阅Azure 存储 服务 的版本控制
Range 可选。 仅返回指定范围内的 Blob 字节数。
x-ms-range 可选。 仅返回指定范围内的 Blob 字节数。 如果指定了 Rangex-ms-range,服务将使用 x-ms-range 值。 如果都不指定,将返回整个 Blob 内容。 有关详细信息 ,请参阅指定 Blob 服务操作的范围 标头。
x-ms-lease-id: <ID> 可选。 如果指定了此标头,只有在符合下面的两个条件时,才会执行此操作:

- Blob 的租约当前处于活动状态。
- 请求中指定的租约 ID 与 Blob 的租用 ID 匹配。

如果指定了此标头并且不符合这两个条件,请求将失败,并且Get Blob 操作失败并返回状态代码 412(前提条件失败)。
x-ms-range-get-content-md5: true 可选。 当此标头设置为 且与 标头一起指定时,只要范围小于或等于 4 MiB,服务就返回该范围的 true Range MD5 哈希。

如果不带 Range 标头指定此标头,则服务返回状态码 400(错误请求)。

如果当范围大小超过 4 MiB 时,此标头设置为 ,则服务返回状态代码 true 400 (错误请求) 。
x-ms-range-get-content-crc64: true 可选。 当此标头设置为 且与 标头一起指定时,只要范围小于或等于 4 MiB,服务将返回范围的 true Range CRC64 哈希。

如果不带 Range 标头指定此标头,则服务返回状态码 400(错误请求)。

如果当范围大小超过 4 MiB 时,此标头设置为 ,则服务返回状态代码 true 400 (错误请求) 。

如果 同时存在 和 标头,则请求将失败,错误请求数为 x-ms-range-get-content-md5 x-ms-range-get-content-crc64 400 (错误) 。

2019-02-02 或更高版本支持此标头。
Origin 可选。 指定从中发出请求的来源。 如果存在此标头,则会在响应中产生跨域资源共享 (CORS) 标头。
x-ms-client-request-id 可选。 提供客户端生成的不透明值,其字符限制为 1 KiB,启用存储分析日志记录时,该值记录在分析日志中。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息,请参阅关于存储 Analytics 日志记录Azure 日志记录:使用日志跟踪存储请求

此操作还支持使用条件标头,以便在符合指定条件时才读取 Blob。 有关详细信息,请参阅为 Blob 服务操作指定条件标头

请求标头 (客户提供的加密密钥)

从版本 2019-02-02 开始,可以在请求中指定以下标头,以读取使用客户提供的密钥加密的 blob。 使用客户提供的密钥和 (标头集进行加密) 可选。 如果 Blob 以前已使用客户提供的密钥进行加密,则必须在请求中包含这些标头,以成功完成读取操作。

请求标头 说明
x-ms-encryption-key 必需。 Base64 编码的 AES-256 加密密钥。
x-ms-encryption-key-sha256 可选。 加密密钥的 Base64 编码 SHA256 哈希。
x-ms-encryption-algorithm: AES256 必需。 指定用于加密的算法。 此标头的值必须为 AES256

请求正文

无。

响应

响应包括 HTTP 状态代码、一组响应标头和响应正文,响应正文包含 Blob 内容。

状态代码

读取完整 Blob 的操作若成功,将返回状态代码 200(正常)。

读取指定范围的操作若成功,则返回状态代码 206 (Partial Content)。

有关状态代码的信息,请参阅 状态和错误代码

响应标头

此操作的响应包括以下标头。 该响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范

语法 说明
Last-Modified 上次修改 Blob 的日期/时间。 日期格式遵循 RFC 1123。

任何修改 Blob 的操作(包括 Blob 元数据或属性更新)都会更改 Blob 的上次修改时间。
x-ms-creation-time 版本 2017-11-09 及更高版本。 创建 Blob 的日期/时间。 日期格式遵循 RFC 1123。
x-ms-meta-name:value 一组作为用户定义元数据、与 Blob 关联的名称-值对。
x-ms-tag-count 版本 2019-12-12 或更高版本。 如果 Blob 具有任何标记,则返回存储在 blob 上的标记数。 如果 Blob 上没有标记,则不返回此标头。
Content-Length 响应正文中存在的字节数。
Content-Type 为 Blob 指定的内容类型。 默认内容类型为 application/octet-stream
Content-Range 指示客户端通过指定 Range 请求标头请求 Blob 子集时返回的字节范围。
ETag ETag 包含一个值,你可以使用该值有条件地执行操作。 有关详细信息 ,请参阅为 Blob 服务操作指定 条件标头。 如果请求版本为 2011-08-18 和更高版本,ETag 值将用引号引起来。
Content-MD5 如果 Blob 有 MD5 哈希并且此Get Blob 操作读取完整 Blob,则返回此响应标头,以便客户端检查消息内容完整性。

在版本 2012-02-12 和更新版本中,即使 Put Blob 请求不包含 MD5 标头,Put Blob 也会设置块 Blob 的 MD5 哈希值。

如果请求读取指定范围,并且 设置为 ,则只要范围大小小于或等于 4 MiB,请求就返回该范围的 x-ms-range-get-content-md5 true MD5 哈希。

如果不是这些条件设置,则 Content-MD5 标头不返回任何值。

如果不带 x-ms-range-get-content-md5 标头指定 Range,服务将返回状态码 400(错误请求)。

如果 当范围大小超过 4 MiB 时设置为 ,则服务返回状态代码 x-ms-range-get-content-md5 true 400 (错误请求) 。
x-ms-content-crc64 如果请求读取指定范围,并且 设置为 ,则只要范围大小小于或等于 4 MiB,请求就返回该范围的 x-ms-range-get-content-crc64 true CRC64 哈希。

如果不带 x-ms-range-get-content-crc64 标头指定 Range,服务将返回状态码 400(错误请求)。

如果 当范围大小超过 4 MiB 时设置为 ,则服务返回状态代码 x-ms-range-get-content-crc64 true 400 (错误请求) 。
Content-Encoding 此标头返回为 Content-Encoding 请求标头指定的值。
Content-Language 此标头返回为 Content-Language 请求标头指定的值。
Cache-Control 如果为 Blob 指定了此标头,则返回此标头。
Content-Disposition 针对版本 2013-08-15 和更高版本的请求将返回此标头。 此标头返回为 x-ms-blob-content-disposition 标头指定的值。

Content-Disposition 响应标头字段传达有关如何处理响应负载的详细信息,也可用于附加更多元数据。 例如,如果设置为 attachment,它指示用户代理不应显示响应,而是应显示指定了文件名而非 Blob 名称的 “另存为” 对话框。
x-ms-blob-sequence-number 页 Blob 的当前序列号。

块 Blob 或追加 Blob 不返回此标头。
x-ms-blob-type: <BlockBlob | PageBlob | AppendBlob> 返回 Blob 的类型。
x-ms-copy-completion-time: <datetime> 版本 2012-02-12 及更高版本。 上次尝试的Copy Blob 操作(将此 Blob 作为目标 Blob)的结束时间。 该值可以指定已完成、已中止或失败的复制尝试时间。 如果复制挂起,从未在Copy Blob 操作中将此 Blob 作为目标,或者在Copy Blob 操作结束后使用Set Blob PropertiesPut BlobPut Block List修改了此 Blob,则不会显示此标头。
x-ms-copy-status-description: <error string> 版本 2012-02-12 及更高版本。 仅当 x-ms-copy-statusfailedpending 时显示。 说明上次严重或不严重的复制操作故障的原因。 如果从未在Copy Blob 操作中将此 Blob 作为目标,或者在Copy Blob 操作结束后使用Set Blob PropertiesPut BlobPut Block List修改了此 Blob,则不会显示此标头。
x-ms-copy-id: <id> 版本 2012-02-12 及更高版本。 上次尝试的Copy Blob 操作(将此 Blob 作为目标 Blob)的字符串标识符。 如果从未在Copy Blob 操作中将此 Blob 作为目标,或者在Copy Blob 操作结束后使用Set Blob PropertiesPut BlobPut Block List修改了此 Blob,则不会显示此标头。
x-ms-copy-progress: <bytes copied/bytes total> 版本 2012-02-12 及更高版本。 包含在上次尝试的Copy Blob 操作(将此 Blob 作为目标 Blob)中复制的字节数和源中的总字节数。 可能显示复制了 0 到 Content-Length 字节。 如果从未在Copy Blob 操作中将此 Blob 作为目标,或者在Copy Blob 操作结束后使用Set Blob PropertiesPut BlobPut Block List修改了此 Blob,则不会显示此标头。
x-ms-copy-source: url 版本 2012-02-12 及更高版本。 长度最大为 2 KiB 的 URL,指定上次尝试操作中使用的源 Blob 或文件,其中 Copy Blob 此 Blob 是目标 Blob。 如果从未在Copy Blob 操作中将此 Blob 作为目标,或者在Copy Blob 操作结束后使用Set Blob PropertiesPut BlobPut Block List修改了此 Blob,则不会显示此标头。

此标头中返回的 URL 包含源 Blob 上的复制操作中使用的任何请求参数,包括用于访问源 Blob 的 SAS 令牌。
x-ms-copy-status: <pending | success | aborted | failed> 版本 2012-02-12 及更高版本。 由 x-ms-copy-id 标识的复制操作状态,它具有以下值:

- success:复制已成功完成。
- pending:复制正在进行。 如果间发的非严重错误减慢复制速度但未导致失败,请检查 x-ms-copy-status-description
- aborted:复制已由 结束 Abort Copy Blob
- failed:复制失败。 参见 x-ms-copy-status-description 了解失败详细信息。

如果从未在Copy Blob 操作中将此 Blob 作为目标,或者在Copy Blob 操作完成后使用Set Blob PropertiesPut BlobPut Block List修改了此 Blob,则不会显示此标头。
x-ms-lease-duration: <infinite | fixed> 版本 2012-02-12 及更高版本。 在租用 Blob 时,指定租约是无限期还是固定时间。
x-ms-lease-state: <available | leased | expired | breaking | broken> 版本 2012-02-12 及更高版本。 Blob 的租约状态。
x-ms-lease-status:<locked | unlocked> Blob 的当前租约状态。
x-ms-request-id 此标头唯一地标识发出的请求,并且可用于解决请求问题。 有关详细信息,请参阅 API 操作疑难解答
x-ms-version 指示用于执行请求的 BLOB 服务的版本。 使用版本 2009/9/19 和更新版本发出的请求中包括。

如果使用 BLOB 服务的 2009-09-19 版将容器标记为公共访问,则也会为未指定版本的匿名请求返回此标头。
Accept-Ranges: bytes 指示服务支持针对部分 Blob 内容的请求。 使用版本 2011-08-18 和更新版本发出的请求中包括,SDK 版本 1.6 或更新版本的本地存储服务中也包括。
Date 服务生成的 UTC 日期/时间值指示启动响应的时间。
Access-Control-Allow-Origin 如果请求包含 Origin 标头并且通过匹配的规则启用了 CORS,则返回此标头。 如果存在匹配项,此标头返回原始请求标头的值。
Access-Control-Expose-Headers 如果请求包含 Origin 标头并且通过匹配的规则启用了 CORS,则返回此标头。 返回将向客户端或请求的发出方公开的响应标头的列表。
Vary 如果指定了 CORS 规则,则随 Origin 标头的值一起返回此标头。 有关详细信息,请参阅 存储 服务的 CORS支持。
Access-Control-Allow-Credentials 如果请求包含 Origin 标头并且通过不允许全部来源的匹配规则启用了 CORS,则返回此标头。 此标头将设置为 True。
x-ms-blob-committed-block-count Blob 中已提交块的数量。 仅针对追加 Blob 返回此标头。
x-ms-server-encrypted: true/false 版本 2015-12-11 或更高版本。 如果 Blob 数据和应用程序元数据使用指定的算法完全加密,则此标头 true 的值设置为 。 否则,如果 blob 未加密 (或仅对 blob/应用程序元数据的某些部分进行加密,该值将 false 设置为) 。
x-ms-encryption-key-sha256 版本 2019-02-02 或更高版本。 如果 Blob 使用客户提供的密钥加密,则返回此标头。
x-ms-encryption-scope 版本 2019-02-02 或更高版本。 如果 Blob 使用加密范围进行加密,则返回此标头。
x-ms-blob-content-md5 从版本 2016-05-31 开始,如果 Blob 具有 MD5 哈希,并且请求包含范围标头 (Range 或 x-ms-range) ,则返回此响应标头,其中包含整个 Blob 的 MD5 值的值。 此值不一定等于 Content-MD5 标头中返回的值,后者根据请求的范围进行计算。
x-ms-client-request-id 此标头可用于对请求和相应响应进行故障排除。 如果标头存在于请求中,并且该值最多为 1024 个可见 ASCII 字符,则此标头的值等于标头 x-ms-client-request-id 的值。 如果 x-ms-client-request-id 请求中不存在标头,则响应中将不存在此标头。
x-ms-last-access-time 版本 2020-02-10 或更高版本。 指示根据存储帐户的上一次访问时间跟踪策略访问 Blob 数据的最后一次时间。 如果存储帐户没有上一次访问时间跟踪策略,或者策略已禁用,将不会返回标头。 有关设置存储帐户的上一次访问时间跟踪策略的信息,请参阅 Blob 服务 API
x-ms-blob-sealed 版本 2019-12-12 或更高版本,仅为追加 Blob 返回。 如果追加 Blob 已密封,则值为 true,请参阅 密封追加 Blob
x-ms-immutability-policy-until-date 版本 2020-06-12 或更高版本。 指定在 Blob 上设置的"保留期到"日期。 这是可保护 Blob 免遭修改或删除的日期。 仅在 blob 上设置了不可变策略时返回。 此标头的值为 RFC1123 格式。
x-ms-immutability-policy-mode: unlocked/locked 版本 2020-06-12 或更高版本。 在 Blob 上设置不可变策略时返回的不可变策略模式。 值为 unlocked / lockedunlocked 指示用户可能会通过增加或减少保留日期来更改策略。 locked 指示禁止这些操作。
x-ms-legal-hold: true/false 版本 2020-06-12 或更高版本。 如果 Blob 上没有法定保留,则不返回此标头。 如果 blob 包含法定保留,并且其值为 true,则此标头的值设置为 true。 否则,如果 blob 包含法定保留及其值 false,则该值设置为 false。
x-ms-owner 版本 2020-06-12 或更高版本仅适用于启用了分层命名空间的帐户。 返回文件或目录的所有者用户。
x-ms-group 版本 2020-06-12 或更高版本仅适用于启用了分层命名空间的帐户。 返回文件或目录的拥有组。
x-ms-permissions 版本 2020-06-12 或更高版本仅适用于启用了分层命名空间的帐户。 返回针对文件或目录的"user"、"group"和"other"设置的权限。 每个单独的权限采用 [r,w,x,-] {3} 格式。
x-ms-resource-type 版本 2020-10-02 或更高版本仅适用于启用了分层命名空间的帐户。 返回路径的资源类型,可以是 。 file / directory

响应正文

响应正文包含 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>  
  

授权

如果容器的访问控制列表 (ACL) 设置为允许匿名访问 Blob,则任何客户端都可以调用此操作。 如果容器是私有的,则帐户所有者以及使用有权读取 Blob 的共享访问签名的任何人可以执行此操作。

备注

对于页 Blob,尚无内容或内容已清除的页面范围的Get Blob 操作对这些字节返回零。

如果对不指定范围的页 Blob 调用Get Blob,该服务将返回为 x-ms-blob-content-length 标头指定的值为范围的页面。 对于缺少内容的所有页,该服务都会对这些字节返回零。

对于追加 Blob, Get Blob 操作返回 x-ms-blob-committed-block-count 标头。 此标头指示 Blob 中已提交块的数量。 块 x-ms-blob-committed-block-count Blob 或页 blob 不返回标头。

每个 Get Blob MiB 允许操作完成 2 分钟。 如果操作平均每 MiB 需要的时间超过 2 分钟,则操作将退出。

检索属于私有容器的 Blob 需要 x-ms-version 标头。 如果 Blob 所属的容器对整个或部分公共访问可用,则任何客户端都不必指定版本就能对其进行读取;检索属于公共容器的 Blob 不需要服务版本。 有关详细信息,请参阅限制对容器和 Blob 的访问

存档 Get Blob 块 Blob 上的 将失败。

复制操作

要确定Copy Blob 操作是否已完成,首先需要检查目标 Blob 的 x-ms-copy-id 标头值是否与对 Copy Blob 的原始调用提供的复制 ID 匹配。 如果匹配,则可以确信另一个应用程序没有中止复制并启动新的Copy Blob 操作。 然后,检查 x-ms-copy-status: success 标头。 但要注意,除了LeasePut PagePut Block操作以外,在 Blob 上执行的所有其他写入操作从 Blob 中删除所有 x-ms-copy-* 属性。 使用 2012-02-12 之前版本的Copy Blob 操作也不复制这些属性。

警告

标头中返回的 x-ms-copy-source URL 包含源 Blob 上的复制操作中使用的任何请求参数。 如果使用 SAS 令牌访问源 Blob,则目标 Blob 上调用 时,该 SAS 令牌 x-ms-copy-source Get Blob 将显示在标头中。

当响应中出现 x-ms-copy-status: failed 时,x-ms-copy-status-description 中包含有关Copy Blob 失败的详细信息。

下表说明了每个 x-ms-copy-status-description 值的三个字段。

组件 说明
HTTP 状态代码 指定错误的标准 3 位整数。
错误代码 描述 Azure 在 ErrorCode 元素中提供的<> 关键字。 如果未<ErrorCode 元素,则使用关键字,其中包含与 HTTP 规范中的 3 位数 > HTTP 状态代码关联的标准错误文本。 请参阅 常见REST API错误代码
信息 用引号引起来的详细错误说明。

下表说明了常见错误情形的 x-ms-copy-statusx-ms-copy-status-description 值。

重要

此处显示的说明文本可能会更改而不提供警告,即使版本没有发生变化也是如此,因此,不要依赖于精确匹配该文本。

方案 x-ms-copy-status 值 x-ms-copy-status-description 值
已成功完成复制操作。 success empty
在完成之前,用户终止了复制操作。 已中止 empty
在复制操作期间从源 Blob 中读取时出现错误,但会重试该操作。 挂起 502 BadGateway“读取源时遇到可重试的错误。 将重试。 失败时间:<时间 > "
在写入到复制操作的目标 Blob 时出现错误,但会重试该操作。 挂起 500 InternalServerError“遇到可重试的错误。 将重试。 失败时间:<时间 > "
从复制操作的源 Blob 中读取时出现无法恢复的错误。 “失败” 404 ResourceNotFound“在读取源时复制失败”。

注意: 报告此基础错误时,Azure 在 ResourceNotFound 元素中 ErrorCode 返回 。 如果 ErrorCode 响应中未出现任何元素,则会显示 HTTP 状态的标准字符串表示形式, NotFound 例如 。
限制所有复制操作的超时时间已过。 (当前超时时间为 2 周。) “失败” 500 OperationCancelled“复制超过允许的最长时间”。
从源中读取时,复制操作失败过于频繁,而不符合最低的尝试成功比率要求。 (此超时可防止在失败之前重试较差的源超过 2 周。) “失败” 500 OperationCancelled“在读取源时复制失败”。

x-ms-last-access-time 跟踪根据存储帐户的 "上次访问时间" 跟踪策略访问 blob 数据的时间。 访问 blob 的元数据不会更改其上次访问时间。

请参阅

授权 Azure 存储的请求
状态和错误代码
Blob 服务错误代码
为 Blob 服务操作设置超时