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

获取 Blob 属性

Get Blob Properties 作返回 blob 的所有用户定义的元数据、标准 HTTP 属性和系统属性。 它不会返回 blob 的内容。

Request

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

HEAD 方法请求 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

模拟存储服务 URI

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

HEAD 方法请求 URI HTTP version
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob HTTP/1.1

有关详细信息,请参阅使用 Azure 存储模拟器进行开发和测试

URI parameters

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

Parameter Description
snapshot Optional. 快照参数是一个不透明 DateTime 的值,如果存在,则指定要检索的 blob 快照。 有关使用 blob 快照的详细信息,请参阅 创建 blob 的快照
versionid Optional. 版本 2019-12-12 及更高版本。 该 versionid 参数是一个不透明 DateTime 的值,如果存在,则指定要检索的 blob 的版本。
timeout Optional. timeout 参数以秒为单位表示。 有关详细信息,请参阅 为 Blob 存储作设置超时

Request headers

下表描述了必需和可选的请求标头。

Request header Description
Authorization Required. 指定授权方案、帐户名称和签名。 有关详细信息,请参阅 授权对 Azure 存储的请求。
Datex-ms-date Required. 指定请求的协调世界时(UTC)。 有关详细信息,请参阅 授权对 Azure 存储的请求。
x-ms-version 所有授权请求都是必需的。 对于匿名请求,可选。 指定要用于此请求的操作的版本。 有关详细信息,请参阅 Azure 存储服务的版本控制
x-ms-lease-id: <ID> Optional. 如果指定了此标头,则仅当满足以下两个条件时才会执行作 Get Blob Properties

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

如果不满足这些条件中的任何一个,则请求将失败,并且 Get Blob Properties 作将失败,状态代码为 412(先决条件失败)。
x-ms-upn Optional. 版本 2020-06-12 及更高版本。 适用于启用了分层命名空间的帐户。 如果为 true,则 中 x-ms-groupx-ms-acl返回x-ms-owner的用户标识值和响应标头将从 Microsoft Entra 对象 ID 转换为用户主体名称。 如果该值为 false,则它们将作为 Microsoft Entra 对象 ID 返回。 默认值是 false。 请注意,不会翻译组和应用程序对象 ID,因为它们没有唯一的友好名称。
x-ms-client-request-id Optional. 提供客户端生成的不透明值,其字符限制为 1 KB (KiB),启用存储分析日志记录时,该值将记录在分析日志中。 强烈建议在将客户端活动与服务器收到的请求相关联时使用此标头。 有关详细信息,请参阅 关于 Azure 存储分析日志记录

此作还支持仅在满足指定条件时使用条件标头返回 blob 属性和元数据。 有关详细信息,请参阅 为 Blob 存储操作指定条件标头

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

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

Request header Description
x-ms-encryption-key Required. Base64 编码的 AES-256 加密密钥。
x-ms-encryption-key-sha256 Optional. 加密密钥的 Base64 编码 SHA256 哈希。
x-ms-encryption-algorithm: AES256 Required. 指定要用于加密的算法。 此标头的值必须为 AES256

Request body

None.

Response

响应包括 HTTP 状态代码和一组响应标头。

Status code

成功的操作返回状态代码 200(正常)。

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

Response headers

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

Response header Description
Last-Modified 上次修改 blob 的日期/时间。 日期格式遵循 RFC 1123。 有关详细信息,请参阅 表示标头中的日期/时间值。

修改 blob 的任何作(包括更新 blob 的元数据或属性)都会更改 blob 的上次修改时间。

请注意,对于大于 4 TiB 的托管磁盘和托管磁盘快照,不会返回。Last-Modified
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 上没有标记,则不会返回此标头。
x-ms-blob-type:<BlockBlob\|PageBlob\|AppendBlob> Blob 类型。
x-ms-copy-completion-time:<datetime> 版本 2012-02-12 及更高版本。 上次尝试 Copy Blob 的作的结束时间,其中此 blob 是目标 blob。 此值可以指定已完成、中止或失败复制尝试的时间。 如果副本处于挂起状态、此 blob 从未是作中的Copy Blob目标,或者如果此 blob 在使用 Set Blob PropertiesPut BlobPut Block List的已结束Copy Blob作后已修改,则不会显示此标头。
x-ms-copy-status-description: <error string> 版本 2012-02-12 及更高版本。 仅当 x-ms-copy-statusfailedpending时才显示。 描述致命或非致命复制作失败的原因。 如果此 blob 从未是作中的Copy Blob目标,或者此 blob 在使用 Set Blob PropertiesPut Blob或 的Put Block List结束Copy Blob作后已修改,则不会显示此标头。
x-ms-copy-id: <id> 版本 2012-02-12 及更高版本。 上次尝试 Copy Blob 的作的字符串标识符,其中此 blob 是目标 blob。 如果此 blob 从未是作中的Copy Blob目标,或者此 blob 在使用 Set Blob PropertiesPut Blob或 的Put Block List结束Copy Blob作后已修改,则不会显示此标头。
x-ms-copy-progress: <bytes copied/bytes total> 版本 2012-02-12 及更高版本。 包含上次尝试 Copy Blob 的作中复制的字节数和源中的总字节数,其中此 blob 是目标 blob。 可以显示从 0 到 Content-Length 复制的字节。 如果此 blob 从未是作中的Copy Blob目标,或者此 blob 在使用 Set Blob PropertiesPut Blob或 的Put Block List结束Copy Blob作后已修改,则不会显示此标头。
x-ms-copy-source: url 版本 2012-02-12 及更高版本。 长度不超过 2 KiB 的 URL,用于指定上次尝试 Copy Blob 作中使用的源 Blob,其中此 Blob 是目标 Blob。 如果此 blob 从未是作中的Copy Blob目标,或者此 blob 在使用 Set Blob PropertiesPut Blob或 的Put Block List结束Copy Blob作后已修改,则不会显示此标头。
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

如果此 blob 从未是作中的Copy Blob目标,或者此 blob 在使用 Set Blob PropertiesPut BlobPut Block List的完成Copy Blob作后已修改,则不会显示此标头。
x-ms-incremental-copy: true 版本 2016-05-31 及更高版本。 如果 blob 是增量副本 blob,则包括在内。
x-ms-copy-destination-snapshot:<datetime> 版本 2016-05-31 及更高版本。 如果 blob 是增量复制 blob 或增量副本快照,则包括在内,如果 x-ms-copy-status 是 success。 此 Blob 上次成功的增量复制快照的快照时间。
x-ms-lease-duration: <infinite \| fixed> 当 Blob 租用时,指定租约是无限持续时间还是固定持续时间。 包括在使用版本 2012-02-12 及更高版本的请求中。
x-ms-lease-state: <available \| leased \| expired \| breaking \| broken> Blob 的租约状态。 包括在使用版本 2012-02-12 及更高版本的请求中。
x-ms-lease-status:<locked\| unlocked> blob 的租约状态。
Content-Length Blob 大小,以字节为单位。 对于页 blob,此标头返回与 blob 一起存储的标头的 x-ms-blob-content-length 值。
Content-Type 为 blob 指定的内容类型。 如果未指定内容类型,则默认内容类型 application/octet-stream
Etag ETag 包含可用于有条件地执行作的值。 有关详细信息,请参阅 为 Blob 存储操作指定条件标头。 如果请求版本为 2011-08-18 或更高版本,则 ETag 值用引号引起来。
Content-MD5 如果已为 blob 设置标头,则 Content-MD5 返回此响应标头,以便客户端可以检查消息内容的完整性。

在版本 2012-02-12 及更高版本中, Put Blob 即使请求不包含 MD5 标头,也会 Put Blob 设置块 blob 的 MD5 值。
Content-Encoding 如果之前已为 blob 设置了请求标头,则 Content-Encoding 在此标头中返回该值。
Content-Language 如果之前已为 blob 设置了请求标头,则 Content-Language 在此标头中返回该值。
Content-Disposition 如果之前已为 blob 设置了请求标头,则 Content-Disposition 对于针对版本 2013-08-15 及更高版本的请求,将在此标头中返回该值。

Content-Disposition响应标头字段传达有关如何处理响应有效负载的其他信息,也可用于附加其他元数据。 例如,如果标头设置为 attachment,则表示用户代理不应显示响应,而是显示“另存为”对话框。
Cache-Control 如果之前已为 blob 设置了请求标头,则 Cache-Control 在此标头中返回该值。
x-ms-blob-sequence-number 页 Blob 的当前序列号。

不会为块 blob 或追加 blob 返回此标头。

不会为块 blob 返回此标头。
x-ms-request-id 此标头唯一标识发出的请求,您可以使用它对请求进行故障排除。 有关详细信息,请参阅 API作故障排除
x-ms-version 指示用于执行请求的 Blob 存储版本。 对于针对版本 2009-09-19 及更高版本发出的请求,将返回此标头。

如果容器使用 Blob 存储版本 2009-09-19 标记为公共访问,则对于没有指定版本的匿名请求,也会返回此标头。
Date 服务生成的 UTC 日期/时间值,指示启动响应的时间。
Accept-Ranges: bytes 指示服务支持对部分 Blob 内容的请求。 包括使用版本 2013-08-15 及更高版本发出的请求。
x-ms-blob-committed-block-count Blob 中存在的已提交的块数。 仅针对追加 Blob 返回此标头。
x-ms-server-encrypted: true/false 版本 2015-12-11 及更高版本。 如果 blob 数据和应用程序元数据使用指定的算法完全加密,则此标头的值将设置为 true 。 否则,该值设置为 false (当 blob 未加密时,或者如果仅加密了部分 blob/应用程序元数据) 。
x-ms-encryption-key-sha256 版本 2019-02-02 及更高版本。 如果 blob 使用客户提供的密钥进行加密,则返回此标头。
x-ms-encryption-context 版本 2021-08-06 及更高版本。 如果设置加密上下文属性值,它将返回设置值。 仅在为帐户启用分层命名空间时有效。
x-ms-encryption-scope 版本 2019-02-02 及更高版本。 如果 blob 使用加密范围进行加密,则返回此标头。
x-ms-access-tier 版本 2017-04-17 及更高版本。 高级存储帐户上的页 blob 层或 blob 存储或常规用途 v2 帐户中的块 blob 层。 有关允许的高级页 Blob 层的列表,请参阅 VM 的高性能高级存储和托管磁盘。 对于 blob 存储或常规用途 v2 帐户,有效值为 HotCoolColdArchive注意:版本 2021-12-02 及更高版本支持Cold 层。 有关标准 Blob 帐户块 Blob 级分层的详细信息 ,请参阅热存储层、冷存储层和存档存储层
x-ms-access-tier-inferred: true 版本 2017-04-17 及更高版本。 仅适用于高级存储帐户上的页 Blob。 如果未在 blob 上显式设置访问层,则会根据其内容长度推断该层,并返回此标头的值 true为 。 对于 Blob 存储或常规用途 v2 帐户上的块 Blob,如果 Blob 未设置访问层,则可以从存储帐户属性推断层。 仅当推断块 blob 层时,才会设置此标头。
x-ms-archive-status 版本 2017-04-17 及更高版本。 对于 blob 存储或常规用途 v2 帐户,有效值为 rehydrate-pending-to-hot、 和 rehydrate-pending-to-coolrehydrate-pending-to-cold。 如果正在解除冻结 blob 且不完整,则返回此标头,该标头既指示解除冻结处于挂起状态,又显示目标层。 有关标准 Blob 帐户块 Blob 级分层的详细信息,请参阅 热存储层、冷存储层和存档存储层
x-ms-access-tier-change-time 版本 2017-04-17 及更高版本。 指示上次更改对象上的层的时间。 仅当设置了块 blob 上的层时,才会返回此标头。 日期格式遵循 RFC 1123。 有关详细信息,请参阅 表示标头中的日期/时间值。 有关标准 blob 帐户块 blob 级分层的详细信息,请参阅 热存储层、冷存储层和存档存储层
x-ms-client-request-id 可用于对请求及其相应的响应进行故障排除。 此标头的值等于标头的 x-ms-client-request-id 值(如果请求中存在),并且该值最多为 1,024 个可见的 ASCII 字符。 如果请求中不存在 x-ms-client-request-id 标头,则响应中不存在此标头。
x-ms-rehydrate-priority 版本 2019-12-12 及更高版本。 如果某个对象处于解除冻结挂起状态,则返回此标头,优先级为解除冻结。 有效值为 High/Standard。 有关标准 Blob 帐户块 Blob 级分层的详细信息 ,请参阅热存储层、冷存储层和存档存储层
x-ms-or-{policy-id}_{rule-id} 版本 2019-12-12 及更高版本,仅针对块 blob 返回。 policy-id 是一个 GUID 值,表示存储帐户上对象复制策略的标识符。 rule-id 是一个 GUID 值,表示 blob 容器上策略规则的标识符。 如果帐户已 ObjectReplication启用,则此标头的值表示具有给定策略和规则标识符( completefailed)的 blob 的复制状态。
x-ms-or-policy-id 版本 2019-12-12 及更高版本,仅针对块 blob 返回。 如果帐户是 ObjectReplication-enabled,则此标头的值表示管理复制的策略。
x-ms-last-access-time 版本 2020-02-10 及更高版本。 指示上次根据存储帐户的上次访问时间跟踪策略访问 blob 数据的时间。 如果存储帐户没有上次访问时间跟踪策略,或者该策略已禁用,则不会返回标头。 有关设置存储帐户的上次访问时间跟踪策略的信息,请参阅 Blob 存储 API
x-ms-blob-sealed 版本 2019-12-12 及更高版本,仅针对追加 blob 返回。 如果追加 blob 已密封,则该值将为 true。 有关详细信息,请参阅 追加 Blob Seal
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 及更高版本。 仅适用于启用了分层命名空间的帐户。 返回在文件或目录上为 用户和其他 设置的权限。 每个单独的权限都是格式化的 [r,w,x,-]{3}
x-ms-acl 版本 2023-11-03 及更高版本。 仅适用于启用了分层命名空间的帐户。 返回为文件或目录上的用户、和其他设置的访问和默认访问控制列表的组合列表。 每个访问控制条目 (ACE) 由范围、类型、用户或组标识符以及格式 [scope]:[type]:[id]:[permissions]为 的权限组成。 作用域指示 default ACE 属于目录的默认 ACL;否则作用域是隐式的,并且 ACE 属于访问 ACL。 每个单独的权限都是格式化的 [r,w,x,-]{3}
x-ms-resource-type 版本 2020-10-02 及更高版本。 仅适用于启用了分层命名空间的帐户。 返回路径的资源类型,可以是 filedirectory
x-ms-expiry-time 版本 2020-02-10 及更高版本。 仅适用于启用了分层命名空间的帐户。 返回在 blob 上设置的过期时间。 仅针对设置了过期时间的文件返回。

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

在 Azure 存储中调用任何数据访问操作时,需要授权。 可以按如下所述授权 Get Blob Properties 操作。

Important

Microsoft建议将 Microsoft Entra ID 与托管标识配合使用来授权对 Azure 存储的请求。 与共享密钥授权相比,Microsoft Entra ID 提供更高的安全性和易用性。

Azure 存储支持使用 Microsoft Entra ID 来授权请求 Blob 数据。 使用 Microsoft Entra ID,可以使用 Azure 基于角色的访问控制(Azure RBAC)向安全主体授予权限。 安全主体可以是用户、组、应用程序服务主体或 Azure 托管标识。 安全主体由 Microsoft Entra ID 进行身份验证,以返回 OAuth 2.0 令牌。 然后可以使用令牌来授权对 Blob 服务发出请求。

若要详细了解如何使用 Microsoft Entra ID 进行授权,请参阅 使用 Microsoft Entra ID授予对 blob 的访问权限。

Permissions

下面列出了Microsoft Entra 用户、组、托管标识或服务主体调用 Get Blob Properties 操作所需的 RBAC 操作,以及包含此操作的最小特权内置 Azure RBAC 角色:

若要详细了解如何使用 Azure RBAC 分配角色,请参阅 分配 Azure 角色以访问 blob 数据

Remarks

若要确定作是否 Copy Blob 已完成,请首先检查以确保 x-ms-copy-id 标头值与原始调用 Copy Blob提供的副本 ID 匹配。 匹配可确保另一个应用程序不会中止副本并启动新 Copy Blob 作。 接下来,检查 x-ms-copy-status: success 标题。 但请注意,除 、 和Put BlockPut Page作之外,对 Leaseblob 的所有写入作都会从 blob 中删除所有x-ms-copy-*属性。 使用 2012-02-12 之前版本的作也不会复制 Copy Blob 这些属性。

x-ms-copy-status-description 包含有关 Copy Blob 失败的详细信息。 下表描述了这些 x-ms-copy-status-description 值:

Component Description
HTTP 状态代码 指定失败的标准 3 位整数。
Error code 描述 Azure 在 ErrorCode> 元素中<提供的错误的关键字。 如果未 <显示 ErrorCode> 元素,则使用与 HTTP 规范中的 3 位 HTTP 状态代码关联的具有标准错误文本的关键字。 有关详细信息,请参阅常见 REST API 错误代码
Information 故障的详细说明,用引号括起来。

x-ms-copy-status下表描述了常见故障方案的 和 x-ms-copy-status-description 值:

Important

即使没有版本更改,以下错误描述也可能在没有警告的情况下更改,因此文本可能不完全匹配。

Scenario x-ms-copy-status value x-ms-copy-status-description value
复制操作成功完成。 success empty
用户在复制作完成之前中止了复制作。 aborted empty
在复制作期间从源 blob 读取时发生故障,但将重试该作。 pending 502 BadGateway “读取源时遇到可重试错误。 Will retry. 失败时间:<时间>”
写入复制作的目标 blob 时发生故障,但将重试该作。 pending 500 InternalServerError “遇到可重试的错误。 Will retry. 失败时间:<时间>”
从复制操作的源 Blob 读取时发生不可恢复的失败。 failed 404 ResourceNotFound “读取源时复制失败。注意:当服务报告此基础错误时,它会在 ErrorCode> 元素中<返回ResourceNotFound。 如果响应中未 <出现 ErrorCode> 元素,则会出现 HTTP 状态的标准字符串表示形式,例如 NotFound
限制所有复制操作已用的超时期限。 (目前,超时期限为两周。 failed 500 OperationCancelled “副本超出了允许的最大时间”。
从源读取时,复制作经常失败,并且未达到尝试与成功的最低比率。 (此超时可防止在失败前两周内重试非常糟糕的源)。 failed 500 OperationCancelled “读取源时复制失败。

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

Billing

定价请求可能源自使用 Blob 存储 API 的客户端,可以直接通过 Blob 存储 REST API 或 Azure 存储客户端库。 这些请求按事务产生费用。 事务类型会影响帐户的计费方式。 例如,读取事务累算到与写入事务不同的计费类别。 下表显示了基于存储帐户类型的 Get Blob Properties 请求的计费类别:

Operation 存储帐户类型 Billing category
获取 Blob 属性 高级块 Blob
标准常规用途 v2
Other operations
获取 Blob 属性 标准常规用途 v1 Read operations

若要了解指定计费类别的定价,请参阅 Azure Blob 存储定价

See also

授权对 Azure 存储 的请求
状态和错误代码
Blob 存储错误代码